top of page

For a given Analysis Results entry, the entry will contain the following pieces of metadata in addition to the link to the Analysis Results File:

session_uid string 

Session UUID generated by Trax​

client_session_uid string

Session UUID generated by the client​

project_name string

Project Name as provided by Trax

store_number string

Client store unique identifier

external_route_id string

Client route unique identifier

session_date string (YYYY-MM-DD)

Visit date in local time zone

session_start_time number (Unix Epoch Time timestamp)

The Unix Epoch Timestamp of the session start time as provided by the client application

session_end_time number (Unix Epoch Time timestamp)

The Unix Epoch Timestamp of the session end time as provided by the client application. The value is empty in case: 

  • Session did not begin to upload

  • User did not click on the "End Visit" button

visitor_identifier string

The user email

visit_date string (YYYY-MM-DD)

Visit date in local time zone

message_id string 

API universal message ID

results_link string 

Analysis Results JSON file link 

report_metadata Object

Analysis Results API response metadata containing the following fields:​

message_id string 

API universal message ID

generation_time number (Unix Epoch Time timestamp) 

The Unix Epoch Timestamp of analysis data generation 

version number

The report may have versions. For example, if an additional section has been computed and added to an initial report, another version will be generated

status string

Options:

  • Completed

  • Partial 

Partial reports are automatically generated by Trax when the expected SLA time has passed and some data from the client has failed to arrive. For example, one or more images from a store visit failed to upload. If and when the missing data will arrive, the results will be updated​

{

"session_uid" : "e9599eb1-f352-4b90-a287-a5ac1e1befb7",
 

"client_session_uid" : "e9599eb1-f352-4b90-a287-a5ac1e1befb8",
 

"project_name" : "projectName",
 

"store_number" : "200",
 

"external_route_id": "2",

"session_date" : "1982-09-17",

"session_start_time" : 1490183405,

"session_end_time" : 1490183406,
 

"visitor_identifier" : "sally@example.com",

"visit_date": "1982-09-17",

"message_id": "U0RQBhYsXUZIUTcZCGhRDk9eIz81IChFEAkHTwIoXXkxVylBXXJoUQ",

"report_metadata" : {

"message_id":"U0RQBhYsXUZIUTcZCGhRDk9eIz81IChFEAkHTwIoXXkxVylBXjx",

"generation_time" : 1490184185,

"version" : 2,

"status" : "Completed"

},

"results_link" : "https://services.traxretail.com/crypt/traxus/eJfWu%2FhxyFwCLEYL4FAI

   WD9kp%2FBRwQRMSpPvTUC%2B7ZcXfNXFgW%2BbS4Pjb8NiEWUFVPix"

}

Analysis Results Entry Metadata Example

Analysis Results Entry Metadata

Bulk Analysis Results

This method can be used to obtain a collection of analysis result links. It should be used to populate the client results storage with large amounts of results links, for example - all the results generated in the last working day.  

Note: Results are archived after 6 months and will not be available for querying via API.

GET /api/:version_number/:project_name/analysis-results?query_params&:pagination_params

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v4/my-project/analysis-results?from=1490183400&to=1490183410

Supported Protocol: HTTPS

GET

*

Mandatory fields marked indicated by

Request Details

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

from=:timestamp string / number 

Start time of time range. The timestamp is a number in Epoch time according to the generation time of the file ​

to=:timestamp string / number 

End time of time range. The timestamp is a number in Epoch time according to the generation time of the file ​

from_visit_date=:date string (Date in YYYY-MM-DD format)

The returned values are according to the visit date set by the agent as part of the session <link to Session Page>. 

Note: In many cases an agent may have the ability to change the visit date, which may affect the returned values

to_visit_date=:date string (Date in YYYY-MM-DD format)

The returned values are according to the visit date set by the agent as part of the session <link to Session Page>. 

Note: In many cases an agent may have the ability to change the visit date, which may affect the returned values

visit_type_id=:number string / number 

The visit type id of the wanted sessions, where the id is a number (can only use visit_type_id or visit_type_display_name in a request)

visit_type_display_name=:string string 

The visit type display name of the wanted session (can only use visit_type_id or visit_type_display_name in a request)

pagination params 

For more info see the Pagination page. By default the first page will be returned first

The Bulk Analysis GET reply body will contain the following fields:

Response Details

from_time string

Start time of time range

to_time string

End time of time range

metadata object

Info related to Pagination

results_generated number

Number of results generated ​

results Object[]

Array of Analysis Results objects. Each result will contain the info defined in the Analysis Results Entry Metadata section

{

  "from_time": "1970-01-01 00:00:00",

  "to_time": "2020-01-01 12:00:00",

  "metadata": {

"page": 2,

"per_page": "10",

"page_count": 1167,

"total_count": 11668,

"links": {

"self": "?page=1&per_page=10",


"first": "?page=1&per_page=10",

"previous": " ",

"next": "?page=2&per_page=10",

"last": "
?page=86&per_page=10",

}

  },

  "results_generated": 200,

  "results": [

{

"session_uid": "A323FDD9-8D4E-417D-878C-58ED7839BA51",

"client_session_uid": "e9599eb1-f352-4b90-a287-a5ac1e1befb3",

"client_type": "On-Device",

"project_name": "my-project",

"store_number": "100050000072419",

"session_date": "2017-03-02",

"session_start_time": "2017-03-02 15:15:48",

"visitor_identifier": "",

"results_metadata": {

"generation_time": "2017-03-02 15:17",

"version": 1,

"status": "completed",

"sections_included": ["calculations", "recognized_items", "session_data"]

},

"results_link":"https://services.traxretail.com/crypt/traxus/eJf

Wu%2FhxyFwCLEYL4FAIWD9kp%2FBRwQRMSpPvTUC%2NXFgW%2BbWUFVPix

}

  ]

}

Response

Should there be issues with the query, an error code and error will be returned. It will contain one the following errors based on failing the related validation:

Validation

Mandatory Variables

  • Error Code: 400 - Bad Request

  • Error:

missing mandatory field - <field_name>
OR
missing mandatory fields: - <field_name>,<field_name>...

 

Variable Types

  • Error Code: 400 - Bad Request

  • Error:

Invalid variable type:<field_name>-expected type: <expected_variable_type>
OR
Invalid variable types:<field_name>-expected type: <expected_variable_type>, <field_name>-expected type: <expected_variable_type>....

Incorrect Format

  • Error Code: 400 - Bad Request

  • Error:

Incorrect format field: <field_name>,
the correct format: <correct_format>

Lookup Value does not exist, Unknown Value

  • Error Code: 400 - Bad Request

  • Error:

Unknown Store <Look Up Value>

example​

Unknown Store <request_store_identifier_>

Internal Error 

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Analysis Results Queue

The processing time of a full store-visit may vary according to the agreed SLA. Whenever the processing is completed the analysis result file is uploaded by Trax to storage and a header+link message is pushed to the analysis-results queue.

The API provides access to pull messages from this queue, as well as determining the size of the queue.

The best practice for using the queue is: 

  • Establishing a single worker on the API client backend 

  • Have this worker pull up to ten messages periodically (e.g. every 30 seconds) 

    • When the client determines that the queue is empty it SHOULD increase the polling interval accordingly ​

  • Populate a database for analysis results based on these messages ​

  • If needed, send an acknowledgment to Trax marking the successful reception of the message

  • Distribute links (or the actual results) to endpoints on the client side 

Limitations

  • Messages that are not pulled from the queue will be deleted after 10 days 

  • The usage of this API is limited as documented in our Terms of Use. A breach of this limit will result in returning
    429- Too Many Requests response

     

Methods

There are several methods relevant to working with the queue and they are: 

Query analysis results queue size

Pull messages from the analysis results queue

Acknowledge the reception of a message pulled from the queue

Response Body

results_requested number

The number of results requested by the customer

results_generated number

The number of results returned

results Object[]

An array of analysis results

Valid request 

A Unix Epoch datetime value generated by the service that indicates the time at which the response was initiated

  • HTTP Code: 200 OK 

  • Response header: Date

Incorrect request 

Error parsing request

  • HTTP Code: 400 - Bad Request

Validation and Errors

When submitted the POST request one of the following codes will be returned: 

Response

{

  "from_time": "1970-01-01 00:00:00",

  "to_time": "2020-01-01 12:00:00",

  "metadata": {

"page": 2,

"per_page": "10",

"page_count": 1167,

"total_count": 11668,

"links": {

"self": "?page=1&per_page=10",


"first": "?page=1&per_page=10",

"previous": " ",

"next": "?page=2&per_page=10",

"last": "
?page=86&per_page=10",

}

  },

  "results_generated": 200,

  "results": [

{

"session_uid": "A323FDD9-8D4E-417D-878C-58ED7839BA51",

"client_session_uid": "e9599eb1-f352-4b90-a287-a5ac1e1befb3",

"client_type": "On-Device",

"project_name": "my-project",

"store_number": "100050000072419",

"session_date": "2017-03-02",

"session_start_time": "2017-03-02 15:15:48",

"visitor_identifier": "",

"results_metadata": {

"generation_time": "2017-03-02 15:17",

"version": 1,

"status": "completed",

"sections_included": ["calculations", "recognized_items", "session_data"]

},

"results_link":"https://services.traxretail.com/crypt/traxus/eJf

Wu%2FhxyFwCLEYL4FAIWD9kp%2FBRwQRMSpPvTUC%2NXFgW%2BbWUFVPix

}

  ]

}

POST /api/:version_number/:project_name/analysis-results/queue/ack

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v4/my-project/analysis-results/queue/ack

POST - Acknowledge Remove Messages from Queue

Supported Protocol: HTTPS

Update the queue with the message ids you wish to remove from it. 

Note: this method should only be used if 'require_ack' is set to 'true' in the analysis results pull request

*

Mandatory fields marked indicated by

Request Details

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Content-Type string

Value: 'application/json'

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

message_ids String[] *

An array of strings. Each string in the array is a message ID which corresponds with a message in the queue. All message IDs are part of the metadata returned for each session when pulled

Request Body

*

Mandatory fields marked indicated by

Request Body Example

{

"message_ids": [ "AQEBHbAVvtYdpCPaJFifn3",

   "FpOmNldmXOShT66GnHJvInF", 

   "pyDeXR28uiFl5PYNSRjU7eL",

   "sRocq2d0ky2FZjjFsMvEZu",

   "n+kzulbVmohcVV8zlfKRL+6l"]

}

failed String[]

All message ids that were not removed from the queue

successful String[]

All message ids that were successfully removed from the queue

Response Body

Response

{

"failed": ["AQEBHbAVvtYdpCPaJFifn3",

"FpOmNldmXOShT66GnHJvInF"],
 

"successful": [ "pyDeXR28uiFl5PYNSRjU7eL",

"sRocq2d0ky2FZjjFsMvEZu"]

}

Valid request 

A Unix Epoch datetime value generated by the service that indicates the time at which the response was initiated

  • HTTP Code: 200 OK 

  • Response header: Date

Incorrect request 

Error parsing request

  • HTTP Code: 400 - Bad Request

Validation and Errors

When submitted the POST request one of the following codes will be returned: 

GET - Determine size of the queue

GET /api/:version_number/:project_name/analysis-results/queue/size

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v4/my-project/analysis-results/queue/size

Supported Protocol: HTTPS

Request Details

*

Mandatory fields marked indicated by

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

Response Details

Mandatory fields marked indicated by

*

queue_size number *

The current queue size

Response

{

"queue_size": 3

}

Valid request 

A Unix Epoch datetime value generated by the service that indicates the time at which the response was initiated

  • HTTP Code: 200 OK 

  • Response header: Date

Incorrect request 

Error parsing request

  • HTTP Code: 400 - Bad Request

When submitted the GET request will return one of the following codes will be returned: 

Validation and Errors

POST /api/:version_number/:project_name/analysis-results/queue/pull

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v4/my-project/analysis-results/queue/pull

Supported Protocol: HTTPS

POST - Pull Messages from the Queue

This method should be used to extract the header and link to the analysis results file. POST is used here (and not HTTP GET) since this method changes the state of the queue resource.

The pull route offers two options for message handling, which are defined by the value of the 'require_ack' parameter: 

 

1. 'require_ack = false', or empty (default). In this case Trax automatically removes the message from the queue once the response is sent to the client

2. 'require_ack = true'. In this case the message will be deleted only once the client is acknowledging the received message. There is a time-window of 3 minutes from the response time, and within this period the sender should return an ACK (acknowledgement) message; otherwise the message will return to the queue and will be resent to the client in the next request/s

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Content-Type string

Value: 'application/json'

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

Mandatory fields marked indicated by

*

Request Details

Request Body

max_count number

The maximum amount of messages to be returned in the request. Valid values are 1 to 10, 1 by default

require_ack boolean

This field affects the logic for removing requests from the queue. 

  • 'require_ack=false', or empty (the default). In this case, Trax automatically removes the message from the queue once the response is sent to the client 
     

  • 'require_ack=true'. In this case the message will be deleted only once the client acknowledges the received message. There is a time-window of 3 minutes from the response time, and within this period the sender should return an ACK (acknowledgement) message; otherwise the message will return to the queue and will be resent to the client in the next request/s

Request Body Example

{

"max_count": 5,

"require_ack": true,

}

Retrieving Analysis Results

Since the actual results file may contain large amounts of data, obtaining the Analysis Results will be done in two steps:

  • Obtaining the link to the full results

  • Downloading the full results (a JSON file) from the link

Links to the analysis results file will always contain metadata about the store visit. The documentation of these fields are shown below

There are two methods that can be used to extract links to the analysis results of store visits from Trax: 

Retrieve Analysis Results in Bulk for batch processing

Pull Analysis Results from a virtual queue

bottom of page