Frequently Asked Question
The SiteTrax JSON API is a simple, JSON-backed push interface for sending SiteTrax captured geolocation and asset ID information to any REST API server. It is fully compatible with most REST API servers that accept JSON messages.
The JSON API is intended for software developers. To use it you should be familiar with web programming and be comfortable creating applications that consume web services through HTTP requests.
Getting Started
The SiteTrax backend requires an AWS bucket to be able to transfer data to and from it. The bucket information and access keys will be provided by SiteTrax. Please submit a support ticket to request a bucket and access keys to process videos.
For instructions on setting up a test environment, please see the Test Development Environment - Setup SiteTrax Test API and JSON article.
Overview
The SiteTrax backend analyzes video stored in an Amazon S3 bucket and outputs that data to any REST API server.
Reference: https://docs.google.com/drawings/d/1ZwDE18DMtbIDPIujX_M61jRm2SvanIolZJ7RsnY4XW0/edit
Step #1: Upload Video (Push) - See Input - Video Specifications below for more details
- Option #1: Using the SiteTrax.io Android app, capture video using any mode, which will upload capture and upload the video automatically for you into a storage bucket.
- Option #2: Upload video (no more than 1 minute in length) to the Amazon S3 bucket provided.
Step #2: REST API Server (Push)
After the video is uploaded in Step #1 above, the SiteTrax.io Backend will analyze the video and push the data analyzed to any REST API server via the SiteTrax.io Router. See Output - REST API section below for more information.
NOTE: Make sure to request API Server access via the link in the Overview section above.
Input - Video Specifications
The files that should be uploaded in {bucket_name}/notprocessed folder. The maximum recommended length of a video is 1 minute.
- Video length: If the video is more than 1 minute in length, it is recommended to split the video into multiple 1 minute videos.
- The recommended resolution of video is 1920x1080 with a frame rate of 30 frames per second.
- The lens of 6mm or longer should be used. A lens less than 5mm could cause distortion and the backend may not be able to read the OCR.
- The GPS information should be embedded in the subtitles of the video (this can be overwritten for static cameras)
SiteTrax Camera Types
SiteTrax can capture data from many different types of cameras including Android and basic security cameras. For implementation purposes, we recommend:
- Mobile App (i.e. Android) - Many cameras for one bucket. The GPS coordinates are dynamically sent base on the location of the mobile app.
- Stationary camera - One camera to one bucket. The GPS coordinates have to be manually defined for each camera.
Output - REST API
The orientation of output JSON is in records format. These records represent each detected asset and its metadata. These records of a single video are sent in series one after another. Samples of each type of record are given below.
International Intermodal Shipping Container ID
{"slno":"2_20211018T042608717Z_s00",
"Type":"International Intermodal Vertical ID",
"Text":"TGHU9884379",
"datetime":"2021-10-18T16:26:11.900000Z",
"datetime_original":"2021-10-18T16:26:08.000000Z",
"datetime_digitized":"2021-10-18T16:26:08.000000Z",
"gps_lat":36.8604,
"gps_lon":-76.2334,
"Container_Company":"TEXTAINER EQUIPMENT MANAGEMENT LTD",
"Container_Country":"Bermuda",
"Status":"Success",
"Status_Code":"A0",
"Asset Image":"https:\/\/container-thumbnails-public.s3.amazonaws.com\/2_20211018T042608717Z_s00_TGHU9884379.jpg",
"Asset Heading": "L2R",
"Sorting": 1657713349069
} International Intermodal Shipping Container Chassis
{
"slno":"1_20210810T103622681Z_s00",
"Type":"International Intermodal Chassis ID",
"Text":"MCCZ406697",
"datetime":"2021-08-10T10:36:41.850000Z",
"datetime_original":"2021-08-10T10:36:12.000000Z",
"datetime_digitized":"2021-08-10T10:36:12.000000Z",
"gps_lat":36.7845624,
"gps_lon":-76.2404794,
"Container_Company":"-",
"Container_Country":"-",
"Status":"-",
"Status_Code":"-",
"Asset Image":"https:\/\/container-thumbnails-public.s3.amazonaws.com\/1_20210810T103622681Z_s00_MCCZ406697.jpg",
"Asset Heading": "L2R",
"Sorting": 1657713349069
} Shipping Container and Chassis
{
"slno": "98_20230201T113352114Z_s00",
"Type": "International Intermodal Vertical ID",
"Text": "TLLU5112118",
"datetime": "2023-02-01T23:33:50.900000Z",
"datetime_original": "2023-02-01T23:33:50.000000Z",
"datetime_digitized": "2023-02-01T23:33:50.000000Z",
"gps_lat": 33.7997204,
"gps_lon": -118.2265971,
"Container_Company": "TAL INTERNATIONAL",
"Container_Country": "United States",
"Status": "Success",
"Status_Code": "A0",
"Asset Image": "https://container-thumbnails-public.s3.amazonaws.com/98_20230201T113352114Z_s00_TLLU5112118.jpg",
"Asset Heading": "R2L",
"Stacking": "1675294430_000_000"
} Generic Text Asset Tracking
{
"slno": "6_20211018T091802622Z_s00_3d8a1e59-39f3-4d1b-b0d9-ed2d19e60b23",
"Type": "Generic OCR",
"Text": "MSDU1569542",
"datetime": "2021-10-18T21:17:55.800000Z",
"datetime_original": "2021-10-18T21:17:55.000000Z",
"datetime_digitized": "2021-10-18T21:17:55.000000Z",
"gps_lat": 36.8130012,
"gps_lon": -76.0557063,
"Asset Image": "https://container-thumbnails-public.s3.amazonaws.com/6_20211018T091802622Z_s00_3d8a1e59-39f3-4d1b-b0d9-ed2d19e60b23_MSDU1569542.jpg",
"Asset Heading": "L2R",
"Sorting": 1657713349069
} Each record has a variety of metadata to track and localize an asset across the globe. There are also status codes included in international intermodal shipping container records to represent how sure we are of each input container.
API Reference
| Field | Type | Description |
|---|---|---|
|
| Name of the video in which container was detected. |
Type | str | Type of detected asset ID. (Horizontal of Vertical) |
Text | str | Detected asset ID. |
datetime | str | Time in ISO8601 of when the camera was passing in front of the asset. |
datetime_original | str | Time in ISO8601 of when the video was created. |
datetime_digitized | str | Time in ISO8601 of when the video was digitized. |
gps_lat | float | Latitude of detected asset in decimal format. |
gps_lon | float | Longitude of detected asset in decimal format. |
Container_Company | str | Company associated with the container. For more information please check BIC database. (International Intermodal Exclusive Entry) |
Container_Country | str | Country of the company. (International Intermodal Exclusive Entry) |
Status | str | Verbal description of the container entry detection status. (International Intermodal Exclusive Entry) |
Status_Code | str | Return code associated with the status of the entry. (International Intermodal Exclusive Entry) |
Asset Image | str | A public URL to the image of the asset that we are trying to track. |
Asset Heading [optional] | str | Specifies the asset direction within the camera frame. R2L: Asset moving from right to left. L2R: Asset moving from left to right. |
Sorting [optional] | str | [Deprecated] [Replaced by below field] If more than one processing type is selected, this field is populated. Users can sort the records via this field to match assets that may pair together. |
Stacking [optional] | str | For containers and chassis detection. This field pairs a container record with it's corresponding chassis record. |
Status Codes (International Intermodal Exclusive)
| Code | Description |
|---|---|
| A0 | No errors were detected for the container entry. |
| A1 | Check digit of the entry is interpolated. |
| I1 | BIC repository cannot verify the company of the container. |
| I2 | Check digit of the container cannot be verified. A record containing this code can be classified as incorrect right away. |
| I3 | We detected the container but its ID cannot be determined. This can be due to damaged or scratched ID or the asset might not be a standard asset. |
| I4 | The provided database of assets does not contain the listed asset. |
| I5 | When processing for both container and chassis is selected, if there is no container for a chassis because it is a bare chassis then the entry for that missing container will have this status code. |
| I6 | Low confidence detection. |
The status code, status text, country and company are only available for international intermodal shipping container IDs. For chassis ID and generic text detection, these entries are not available.
If records from a video do not show up please check our status page or if all services are up then please submit a support ticket at our support page.