Deprecated APIs
The v1 methods on this page, while still supported, have been succeeded by enhanced v2 methods. Refer to the API documentation for the up-to-date API commands and examples.
Authentication
All API endpoints are authenticated using your API token over HTTP basic auth. API tokens have a unique Access Key and Secret Key that are used during API authentication.
Subscription Admins can issue and manage API tokens for their subscription from the RetailNext cloud interface in Admin Settings > System Access Tokens. Visit System Access Tokens to learn more.
Authentication Header
--basic --user <AccessKey>:<SecretKey>Pagination
All API v1 responses have a default and maximum page length limit of 100 entries. Queries with more items than the page length limit will have responses split across multiple pages.
Parameters
X-Page-Length integer default: 100 | If included, the response page length will match the specified value. The maximum page length is 100. |
X-Page-Start integer | If included, the response will start at the specified value. This is typically used to retrieve subsequent pages for queries that exceed the page length limit. |
Example Request
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "X-Page-Length: 20" \
"https://<subscription>.api.retailnext.net/v1/location"Example Response
HTTP/2 206
content-type: application/json
...
x-frame-options: SAMEORIGIN
x-page-next: 20
...Example Request for Subsequent Pages
Fetch the next page by adding "X-Page-Start" to your original request header with a value that matches "X-Page-Next" from the previous response.
The HTTP response code indicates whether a response contains all possible entries, or if you need to fetch more pages; whereby:
200: OK (no additional pages)206: Partial Content
Locations
Query Locations
Returns a list of locations and related fields.
GET https://<subscription>.api.retailnext.net/v1/location
Example Request
Example Response
Datamine
Query Metrics
Returns a list of metrics within specified parameters.
POST https://<subscription>.api.retailnext.net/v1/datamine
Parameters
locations* string | UUID of the location |
metrics* string | See Metrics Glossary for API identifiers |
date_ranges* string |
|
time_ranges* string |
|
group_bys* string |
See More Details on Group Bys further below |
* required parameter
Traffic metrics validity - When querying traffic metrics the response will include an additional "validity" fields with the possible values being: "complete", "incomplete" and "imputed". An "incomplete" or "imputed" response indicates that there was a problem collecting traffic data during the queried range (e.g. power not supplied to sensor). Learn more about these values on the Knowledge Base page, Imputing Missing Traffic Data.
Example Request
This example queries Traffic In & Out metrics from February 20, 2021 to February 27, 2021 during store hours, with the response grouped by one day.
Where the request.json file contains:
Example Response
More Details on Group Bys
The "group_bys" option determines how the data is sliced, or grouped, in the response. It supports one or more of the following "group" keys: "time", "date", "location", "day_of_week". Each group is further associated with a "unit" and "value" key for additional flexibility.
Example Requests
Single Grouping by date - the request.json file contains:
Layered Grouping by location, then time - the request.json file contains:
Supported Options
Occupancy
Query Current Occupancy
Returns the current occupancy at a location.
POST https://<subscription>.api.retailnext.net/v1/datamine
Example Request
This example queries for the current occupancy of the store location dace69f6-b307-11e9-819d-0000698cf233.
Where the request.json file contains:
Example Response
The query results in a traffic_out of 26 and traffic_in of 34, so the total_occupancy is 8.
On This Page