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
{
"video_name": "video24-05-07_09-43-03-39_01424",
"type": "International Intermodal Vertical ID",
"text": "TRBU5341840",
"datetime": "2024-05-07T13:43:43.701000Z",
"datetime_original": "2024-05-07T13:43:43.701000Z",
"datetime_digitized": "2024-05-07T13:43:43.701000Z",
"gps_lat": 30.4178413846,
"gps_lon": -81.5642421112,
"container_company": "CJ DARCL LOGISTICS LIMITED",
"container_country": "India",
"status": "Success",
"status_code": "A0",
"asset_image": "https://d11isnr6z7061v.cloudfront.net/video24-05-07_09-43-03-39_01424_TRBU5341840.jpg",
"asset_heading": "R2L",
"camera": "B8A44F9E3A9E"
} International Intermodal Shipping Container Chassis
{
"video_name": "1_20210810T103622681Z_s00",
"type": "International Intermodal Chassis ID",
"text": "MCCZ406697",
"datetime": "2024-05-07T13:43:43.701000Z",
"datetime_original": "2024-05-07T13:43:43.701000Z",
"datetime_digitized": "2024-05-07T13:43:43.701000Z",
"gps_lat": 30.4178413846,
"gps_lon": -81.5642421112,
"container_company": "CJ DARCL LOGISTICS LIMITED",
"container_country": "India",
"status": "Success",
"status_code": "A0",
"asset_image": "https:\/\/container-thumbnails-public.s3.amazonaws.com\/1_20210810T103622681Z_s00_MCCZ406697.jpg",
"asset_heading": "R2L",
"camera": "B8A44F9E3A9E"
} Shipping Container and Chassis
{
"video_name": "video24-05-07_09-43-03-39_01424",
"type": "International Intermodal Vertical ID",
"text": "TRBU5341840",
"datetime": "2024-05-07T13:43:43.701000Z",
"datetime_original": "2024-05-07T13:43:43.701000Z",
"datetime_digitized": "2024-05-07T13:43:43.701000Z",
"gps_lat": 30.4178413846,
"gps_lon": -81.5642421112,
"container_company": "CJ DARCL LOGISTICS LIMITED",
"container_country": "India",
"status": "Success",
"status_code": "A0",
"asset_image": "https://d11isnr6z7061v.cloudfront.net/video24-05-07_09-43-03-39_01424_TRBU5341840.jpg",
"asset_heading": "R2L",
"stacking": "314875212301145617478946594181356160171_000_000",
"camera": "B8A44F9E3A9E"
} Generic Text Asset Tracking
{
"video_name": "video24-05-07_09-43-03-39_01424",
"type": "Generic OCR",
"text": "TRBU5341840",
"datetime": "2024-05-07T13:43:43.701000Z",
"datetime_original": "2024-05-07T13:43:43.701000Z",
"datetime_digitized": "2024-05-07T13:43:43.701000Z",
"gps_lat": 30.4178413846,
"gps_lon": -81.5642421112,
"container_company": "CJ DARCL LOGISTICS LIMITED",
"container_country": "India",
"status": "Success",
"status_code": "A0",
"asset_image": "https://d11isnr6z7061v.cloudfront.net/video24-05-07_09-43-03-39_01424_TRBU5341840.jpg",
"asset_heading": "R2L",
"camera": "B8A44F9E3A9E"
} 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. |
camera [optional] | str | Unique serial number of the camera. Only available to virtual gate applications. |
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. |
| I7 | Low confidence detection. ID has been interpolated. |
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.
Generating Test Sample Data
We recommend using SiteTrax directly to generate test data. This can be done by scanning a picture of an intermodal containers to trigger events whenever you wish. It is recommended to scan a complete container so that the object detection and first identify the container and then scan the ID.
Preparing test data to be pushed to you for testing:
- Locate an Android 10 or later device
- Register for a free SiteTrax account - https://www.sitetrax.io (Click Register)
- Download the SiteTrax Android app (link provided after registering your account above).
- Scan an international intermodal container and/or chassis.
- View the results in a Google Spreadsheet.
Next, use the one or more images of containers on a full screen computer and scan the ISO numbers. Make sure to have the whole object in frame and make sure the picture is taking up the entire screen. Below are some sample images (click to view in a New Window in your web browser).
Sample Image #1 - International Intermodal Container:
Sample Image #2 - Multiple International Intermodal Containers:
Use the images above in a full screen monitor to test scan with the Android app. The data should push to the spreadsheet that you set up to see the sample payload within a spreadsheet when you registered.
Reviewing the Data:
Please visit https://www.sitetrax.io and login to the SiteTrax Service Portal if you need to troubleshoot or monitor what you scanned (along with the results). A sample JSON payload is also available with each record in the SiteTrax Service Portal if needing to troubleshoot further.
NOTE: The default settings for free accounts is typically limited to 100 scans per month and scanning one asset (or image) at a time. If you wish to scan continuously with the app, please submit a support ticket at our support page.
Custom Endpoint: When you're ready to have live data pushed to your endpoint, please submit a support ticket at our support page and supply your registered username and project to request that the data is sent to your webhook destination.
Troubleshooting
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.