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
*
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. Support multiple values example: 0,1,2 (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 sessions, support multiple value. Example: type1,type2,type3 (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 links are still available to query outside the queue using Bulk Analysis Results
-
-
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