Frequently Asked Question

SiteTrax API - Output (JSON)
Last Updated 8 days ago

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. 

Request API Server Access>>

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.

image


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

  1. Video length: If the video is more than 1 minute in length, it is recommended to split the video into multiple 1 minute videos. 
  2. The recommended resolution of video is 1920x1080 with a frame rate of 30 frames per second. 
  3. 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.
  4. 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:

  1. Mobile App (i.e. Android) - Many cameras for one bucket.  The GPS coordinates are dynamically sent base on the location of the mobile app.
  2. 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

FieldTypeDescription

slno

str

Name of the video in which container was detected.

TypestrType of detected asset ID. (Horizontal of Vertical)
TextstrDetected asset ID.
datetimestrTime in ISO8601 of when the camera was passing in front of the asset.
datetime_originalstrTime in ISO8601 of when the video was created.
datetime_digitizedstrTime in ISO8601 of when the video was digitized.
gps_latfloatLatitude of detected asset in decimal format.
gps_lonfloatLongitude of detected asset in decimal format.
Container_CompanystrCompany associated with the container. For more information please check BIC database. (International Intermodal Exclusive Entry)
Container_CountrystrCountry of the company. (International Intermodal Exclusive Entry)
StatusstrVerbal description of the container entry detection status. (International Intermodal Exclusive Entry)
Status_CodestrReturn code associated with the status of the entry. (International Intermodal Exclusive Entry)
Asset ImagestrA public URL to the image of the asset that we are trying to track.
Asset Heading [optional]strSpecifies the asset direction within the camera frame. 
R2L: Asset moving from right to left.

L2R: Asset moving from left to right.
U2D: Asset moving from up to down.
D2U: Asset moving from down to up.

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]
strFor containers and chassis detection. This field pairs a container record with it's corresponding chassis record.

Status Codes (International Intermodal Exclusive)

CodeDescription
A0No errors were detected for the container entry.
A1Check digit of the entry is interpolated.
I1BIC repository cannot verify the company of the container.
I2Check digit of the container cannot be verified. A record containing this code can be classified as incorrect right away.
I3We 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.
I4The provided database of assets does not contain the listed asset.
I5When 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.
I6Low confidence detection.
I7Low 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

Please Wait!

Please wait... it will take a second!