RetailNext has an extensive API for users to access and modify data in the RetailNext cloud service and integrate them with other existing systems.
The API calls are REST compliant and make use of the most common HTTP methods such as GET and POST, with the data sent and received in JSON format. All requests require HTTPS connections and authentication with API keys.
This page details the most recent API methods available, while old methods are listed at Deprecated APIs .
For help with using this page, more examples, and frequently asked questions; visit Getting Started with the API .
Please review our API Implementation Considerations before building or integrating applications with the RetailNext API.
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 API Tokens. Visit System API Tokens to learn more.
1
--basic --user <AccessKey>:<SecretKey>
Version 1 API 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 Show example
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "X-Page-Length: 20" \
"https://<subscription>.api.retailnext.net/v1/location"
Example Response Show response
1
2
3
4
5
6
HTTP/2 206
content-type: application/json
...
x-frame-options: SAMEORIGIN
x-page-next: 20
...
Example Request: Subsequent Pages The HTTP response code indicates whether a response contains all possible entries, or if you need to fetch more pages; whereby:
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.
Show example
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "X-Page-Length: 20" -H "X-Page-Start: 20" \
"https://<subscription>.api.retailnext.net/v1/location"
Version 2 API API v2 methods do not support pagination and have a limit of 10,000 entries per response.
If you expect a large response that may get trimmed by this limit, be more specific in your query, e.g. use additional filters.
Locations
Query Locations Returns locations and related fields.
POST https://<subscription>.api.retailnext.net/v2/location
Example Request Show request
This example filters for only store
type locations and includes extra fields for store_id
and occupancy_limit
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/location"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"extra_fields": [
"store.store_id",
"store.occupancy_limit"
],
"where": {
"and": [
{
"location_types": [
"store"
]
}
]
}
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
"nodes": [
[
{
"store_id": "50",
"occupancy_limit": 50,
"location_type": "store",
"area": null,
"uuid": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"parent_uuid": "22940210-f49b-11e6-944b-c0001cd87189",
"name": "Caspar City Plaza",
"type": "location",
"archive_date": null
},
{
"store_id": "101",
"occupancy_limit": 15,
"location_type": "store",
"area": null,
"uuid": "86b03ba2-a117-11ea-802c-c00010892d7a",
"parent_uuid": "01b1ed64-f49b-11e6-9ef8-400075388ff3",
"name": "Willow Glen",
"type": "location",
"archive_date": null
},
...
}
Extra Fields and Filtering As in the example above, you can specify extra fields
in your query to include additional location fields that are normally not returned in responses. The supported options are as follows:
store.time_zone
store.store_id
store.pos_id
store.pos_division_id
store.staff_hour_id
store.occupancy_limit
Specify location_type
filters in your query to limit responses by certain location types. This is particularly useful when normal responses exceed the API pagination limit. The supported filters are:
display
entrance
fitting_room
other
store
region
Create Locations Creates sublocations and regions.
POST https://<subscription>.api.retailnext.net/v2/location/create
Parameters name *
string
The name of the location
parent_UUID *
string
The UUID of the parent store or region
location_type *
string
Supported sublocation types: entrance
, fitting_room
, display
, other
Supported region type: region
(parent UUID must be another region)
area
integer
The area in square feet (only applicable to sublocations)
aggregate_to_parent
boolean
default: true when "entrance", false otherwise
true
, false
(only applicable to sublocations)
aggregate_to_store
boolean
default: true when "entrance", false otherwise
true
, false
(only applicable to sublocations when floor level conversion is enabled)
* required parameter
Creating store locations is not supported through the API
To create a region under the top-level parent, or the "Organization" level, you must set the parent_uuid
value to that of the subscription UUID. Contact RetailNext support if you need help obtaining this value.
After creating a location, the API response includes the UUID of the newly created location to use in further API operations
Example Request Show request
This example creates a new Display sublocation type within a store.
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/location/create"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
{
"name": "Front Table",
"parent_uuid": "2512a786-a117-11ea-874c-8000df845ed7",
"location_type": "display",
"area": 53.1,
"aggregate_to_parent": true,
"aggregate_to_store": false
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
{
"location_type": "display",
"aggregate_to_parent": true,
"aggregate_to_store": false,
"area": 53.1,
"uuid": "fb2d8bf5-c19e-11e8-b05c-40008b55ebf7",
"parent_uuid": "2512a786-a117-11ea-874c-8000df845ed7",
"name": "Front Table",
"type": "location",
"archive_date": null
}
Update Locations Update location fields.
PUT https://<subscription>.api.retailnext.net/v2/location/<location_uuid>
Parameters name
string
Name of location
parent_UUID
string
Moves the location beneath the specified parent location
location_type
string
Supported sublocation types: entrance
, fitting_room
, display
, other
area
integer
Area in square feet (only applicable to stores and sublocations)
occupancy_limit
integer
Occupancy limit (only applicable to stores)
bandwidth_limit_kilobits_per_second
integer
Custom outbound bandwidth limit of a store (only applicable when global bandwidth limits are enabled)
Sending a value of 0
clears any existing custom store limit and reverts its value to the global limit.
aggregate_to_parent
boolean
true
, false
(only applicable to sublocations)
aggregate_to_store
boolean
true
, false
(only applicable to sublocations when floor level conversion is enabled)
Example Request Show request
This example updates a store by changing its name, area and occupancy limit; as well as moving it to a new parent region.
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v2/location/<location_uuid>"
Where the request.json
file contains:
1
2
3
4
5
6
{
"name": "Willow Glen Updated",
"parent_uuid": "286b1000-f8b1-11e7-9337-c0009584d333",
"area": 270.8,
"occupancy_limit": 20
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
{
"occupancy_limit": 20,
"location_type": "store",
"area": 270.8,
"uuid": "<location_uuid>",
"parent_uuid": "286b1000-f8b1-11e7-9337-c0009584d333",
"name": "Willow Glen Updated",
"type": "location",
"archive_date": null
}
Updating Locations in Bulk You can update a bulk selection of locations to a specified parameter value in certain situations.
Show bulk update occupancy limit example
This example updates the respective occupancy limit parameter of multiple store locations.
1
2
3
while IFS=, read -r site_uuid occupancy;do curl -viL --basic --user <AccessKey>:<SecreteKey> \
-XPUT "https://<subscription>.api.retailnext.net/v2/location/$site_uuid" \
-d "{\"occupancy_limit\": $occupancy}";done < ./occupancy_limit.csv
Where the occupancy_limit.csv
file contains:
1
2
3
site_uuid, occupancy_limit
18ef3a2e-cc3f-11e6-8d5c-0000124e6871,40
ff94800e-7c5f-11e6-8056-c000704d0145,35
Store Hours Query Store Hours Returns store hours within specified parameters.
POST https://<subscription>.api.retailnext.net/v1/storehours
Parameters stores *
string
UUID of store location
start_date *
ISO 8601
Start date in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ )
end_date *
ISO 8601
End date in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ )
* required parameter
Example Request Show request
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/storehours"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
{
"stores" : [
"aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9", "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9"
],
"start_date" :
"2021-01-15T00:00:00Z"
,
"end_date" :
"2021-01-22T00:00:00Z"
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"result": {
"aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9": {
"2021-01-15T00:00:00Z": {
"store_uuid": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"effective_day": "2021-01-15T00:00:00Z",
"open": "2021-01-15T10:00:00Z",
"close": "2021-01-15T21:00:00Z"
},
...
},
"2021-01-22T00:00:00Z": {
"store_uuid": "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9",
"effective_day": "2021-01-22T00:00:00Z",
"open": "2021-01-22T09:00:00Z",
"close": "2021-01-22T21:00:00Z"
}
}
}
}
Datamine Query Metrics Returns metrics within specified parameters.
POST https://<subscription>.api.retailnext.net/v2/datamine
Parameters locations *
string
UUID of location
metrics *
string
See Metrics Glossary for API identifiers
date_ranges *
string
from
and to
in conjunction with additional objects.
See More Details on Date Ranges below
time_ranges *
string
from
and until
in hh:mm , or,
type: store_hours
group_bys *
string
time
, date
, location
and day_of_week
See More Details on Group Bys below
* required parameter
Datamine API responses typically include the following indicators:
Ok: When querying any metric, each response entry includes an ok
field. A value of true
means that there was no error in serving the data, while false
indicates there was an error with a further description. Errors in serving data generally relate to inadequate API token permissions or bad requests, e.g. if you’re querying metrics for a store that is not included in the Location Profile assigned to your API token.
Validity: When querying traffic metrics, each data point additionally includes a validity
field. The possible values are: complete
, incomplete
and imputed
, where an incomplete
or imputed
response means that there was a problem collecting traffic data during the queried range, e.g. power not supplied to the sensor. Learn more about traffic validation and imputing at Imputing Missing Traffic Data .
Response timestamps are prefixed with -
or +
when the store hours of a store on a given day are configured to overlap with the previous day or the following day, respectively. See Managing Store Hours for more information.
Example Request Show request
This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day.
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
"metrics" : [
"traffic_in",
"traffic_out"
],
"date_ranges" : [
{
"from": {
"relative": {
"add_weeks": -1 }
},
"to": {
"relative": {
"base": {
"name": "now" },
"truncate_to": "week"
}
}
}
],
"time_ranges" : [
{
"type": "store_hours"
}
],
"group_bys" : [
{
"group": "date",
"unit": "days",
"value": 1
}
],
"locations" : [
"aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9"
],
"time_zone": "America/Los_Angeles"
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
"ok": true,
"metrics": [
{
"name": "traffic_in",
"ok": true,
"data": [
{
"value": 173,
"validity": "complete",
"group": {
"type": "date",
"from": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
},
"through": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
}
},
"index": 0
},
...
]
},
{
"name": "traffic_out",
"ok": true,
"data": [
{
"value": 174,
"validity": "complete",
"group": {
"type": "date",
"from": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
},
"through": {
"gregorian": "2021-02-21",
"year": 2021,
"month": 1,
"day": 22
}
},
"index": 0
},
...
]
}
]
}
More Details on Date Ranges The date_ranges
parameter determines the dates from
and to
, respectively, for which to datamine. It also requires the use of additional objects, being:
name
gregorian
absolute
relative
.
Date range considerations:
The date_ranges
parameter and datamine API responses respect the subscription’s Admin Settings > Calendar configuration. For example: if your query specifies an absolute date range from year:2021, week:5, day:1, and your calendar has been customized such that Saturday is the first day of the week, the response will return metrics starting from Saturday, 30 January 2021.
The maximum date range for queries, i.e. the difference in time between from
and to
, are as follows:
If only one store location is queried, the limit is 5 years
If several stores are queried, the limit is 2 years
Show date_ranges options
Name The name
key supports simple named date values, such as now
and today
.
Specifying a time zone in your query is required when using name
within the date range parameter. Jump to Time Zones in the Occupancy section to learn more.
Example Request 1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
...
"date_ranges" : [
{
"from": {
"name": "today" },
"to": {
"name": "now" }
}
],
...
"time_zone": "America/Los_Angeles"
}
Gregorian The gregorian
key supports Gregorian calendar date values in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ), where “Z” implies that the time zone is UTC.
Example Request 1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
{
...
"date_ranges" : [
{
"from": {
"gregorian": "2021-02-27T00:00:00Z" },
"to": {
"gregorian": "2021-02-28T00:00:00Z" }
}
],
...
}
Absolute The absolute
key supports various date pairs with integer values.
Example Request 1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
...
"date_ranges" : [
{
"from": {
"absolute": {
"year": 2021,
"week": 2,
"day": 4 }
},
"to": {
"absolute": {
"year": 2021,
"week": 3 }
}
}
],
...
}
Supported Options 1
2
3
4
5
6
7
8
9
10
11
12
{
"absolute": {
"year": 2017, // calendar year, required
"quarter": 1, // calendar quarter, starts from 1, optional
"month": 1, // calendar month, starts from 1, optional
"week": 1, // calendar week, starts from 1, optional
"day": 1, // calendar day, starts from 1, optional
"hour": 0, // hour, starts from 0, optional
"minute": 0, // minute, starts from 0, optional
"second": 0 // second, starts from 0, optional
}
}
Date Examples 1
2
3
4
5
6
7
8
9
10
11
12
13
14
// beginning of first day of 2017
year=2017
// beginning of 150th day of 2017
year=2017,day=150
// beginning of 12th week of 2017
year=2017,week=12
// beginning of 2018
year=2017,month=13
// 45th min of 12th hour of 5th day of 2nd week of 3rd month of 2nd quarter of 2017
year=2017,quarter=2,month=3,week=2,day=5,hour=12,minute=45
Relative The relative
key supports flexible time-based strings in relation to another specified date, usually used in conjunction with other date options.
If a base
date isn’t specified, any relative
date specification is considered to be in relation to the opposing date range parameter, being from
or to
respectively. See Mixed Options below for more details.
Example Request 1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
...
"date_ranges" : [
{
"from": {
"relative": {
"base": {
"gregorian": "2021-02-27T00:00:00Z" }
}
},
"to": {
"relative": {
"add_days": 5 }
}
}
],
...
}
Supported Options 1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"relative": {
"base": <date>, // any date option, required if "from" and "to" are both "relative"
"truncate_to": <interval>, // truncate base to specified interval (year|quarter|month|week|day|hour|minute|second), optional
"add_years": 1, // add specified number of years, optional
"add_quarters": 1, // add specified number of quarters, optional
"add_months": 1, // add specified number of months, optional
"add_weeks": 1, // add specified number of weeks, optional
"add_days": 1, // add specified number of days, optional
"add_hours": 1, // add specified number of hours, optional
"add_minutes": 1, // add specified number of minutes, optional
"add_seconds": 1, // add specified number of seconds, optional
}
}
Negative values are supported in order to specify a backward-looking interval.
When adding months, the API maintains the same day-of-month as the starting date. If the destination month has too few days, it truncates the day of month to the final day. For example, with the Gregorian calendar, adding 1 month to "Jan 31" yields "Feb 28" (or "Feb 29" in leap year). Adding quarters is equivalent to adding 3 months, and adding years is equivalent to adding 12 months.
Mixed Options You can use a mix of any two options in from
and to
date range specifications, respectively.
For regularly repeated API requests, relative
date ranges are commonly used in conjunction with another option.
Example Requests 1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Date range for June, 2020 plus 4 months - the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
...
"date_ranges" : [
{
"from": {
"absolute": {
"year": 2020,
"month": 6 }
},
"to": {
"relative": {
"add_months": 4 }
}
}
],
...
}
Date range for last week - the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
...
"date_ranges" : [
{
"from": {
"relative": {
"add_weeks": -1 }
},
"to": {
"relative": {
"base": {
"name": "now" },
"truncate_to": "week"
}
}
}
],
...
"time_zone": "America/Los_Angeles"
}
Date range for current month-to-date - the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
...
"date_ranges" : [
{
"from": {
"relative": {
"base": {
"name": "now" },
"truncate_to": "month"
}
},
"to": {
"name": "now" }
}
],
...
"time_zone": "America/Los_Angeles"
}
Date range for the last 24 hours - the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
...
"date_ranges": [
{
"from": {
"relative": {
"add_days": -1
}
},
"to": {
"relative": {
"base": {
"name": "now"
},
"truncate_to": "minute"
}
}
}
],
"time_ranges": [
{
"from": "00:00", "until": "24:00"
}
],
"group_bys": [
{
"group": "location",
"unit": "",
"value": 1
},
{
"group": "date",
"unit": "days",
"value": 1
},
{
"group": "time",
"unit": "hours",
"value": 1
}
],
...
"time_zone": "America/Los_Angeles"
}
More Details on Group Bys The group_bys
parameter determines how the data is sliced, or grouped, in the response. It supports one or more layers of the following group
keys:
time
date
location
day_of_week
Each group is then further associated with a unit
and value
according to specification.
Show group_bys options
Example Requests 1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Single Grouping by date - the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
{
...
"group_bys" : [
{
"group": "date",
"unit": "days",
"value": 1
}
],
...
}
Layered Grouping by location, then time - the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
...
"group_bys" : [
{
"group": "location",
"unit": "",
"value": 1
},
{
"group": "time",
"unit": "hours",
"value": 1
}
],
...
}
Supported Options 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
"group_bys": [
{
"group": "location",
"unit": "", // blank value required when grouping by "location"
"value": 1 // irrelevant, but accepts any positive integer
},
{
"group": "date",
"unit": "<string>", // supports "days", "weeks", "months" and "years"
"value": <integer> // any positive integer
},
{
"group": "time",
"unit": "<string>", // supports "hours" and "minutes"
"value": <integer> // any positive integer
},
{
"group": "day_of_week",
"unit": "", // blank value required when grouping by "day_of_week"
"value": 1 // irrelevant, but accepts any positive integer
}
]
Occupancy
Query Occupancy Returns current occupancy metrics.
POST https://<subscription>.api.retailnext.net/v2/datamine
Example Request Show request
This example queries for the current occupancy of the store location dace69f6-b307-11e9-819d-0000698cf233
.
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v2/datamine"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
"date_ranges" : [
{
"from" : { "name":"today" },
"to" : { "relative" : {"add_days" : 1}}
}
],
"group_bys" : [
{
"group" : "location",
"unit" : "",
"value" : 0
}
],
"locations" : [
"dace69f6-b307-11e9-819d-0000698cf233"
],
"metrics" : [
"traffic_in",
"traffic_out",
"total_occupancy"
],
"time_ranges" : [
{"type": "store_hours"}
],
"time_zone": "America/Los_Angeles"
}
When using date range specifications "to" : { "name":"now" }
, the system automatically truncates data up to the last complete 15 minute bucket in the day to allow fair comparisons against past period.
To bypass this and retrieve metrics beyond the last complete 15 minute bucket, specify "to" : { "relative" : {"add_days" : 1}}
instead to retrieve the most up to date count possible.
Example Response Show response
The query results in traffic_out
of 5 and traffic_in
of 4, so the total_occupancy
is 1 . Note that the query was grouped by location
, so the result includes the name of the store.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
"metrics" : [
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 5
}
],
"name" : "traffic_in",
"ok" : true
},
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 4
}
],
"name" : "traffic_out",
"ok" : true
},
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 1
}
],
"name" : "total_occupancy",
"ok" : true
}
],
"ok" : true
}
Time Zones Current Occupancy requests use "name"
date range specifications, meaning that you must provide a time zone in the query. To request metrics with timestamps that match up with that of a store’s local timezone, use the local timezone of that store in your query.
Additional time zone flexibility is provided specifically for occupancy queries. See the examples below for more information.
Show time zone examples
With Time Zone Obtain the time zone of a location using /v2/location
.
Example Request In the example request below, dace69f6-b307-11e9-819d-0000698cf233
is the store location.
1
2
3
4
5
6
7
8
9
10
{
"extra_fields" : [
"store.time_zone"
],
"where" : {
"uuids" : [
"dace69f6-b307-11e9-819d-0000698cf233"
]
}
}
Example Response 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"nodes" : [
[
{
"archive_date" : null,
"area" : null,
"location_type" : "store",
"name" : "San Jose Store",
"parent_uuid" : "df62161a-64c8-11e6-82d4-c0008ffc38ce",
"time_zone" : "America/Los_Angeles",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
}
]
]
}
Without Timezone Alternatively, you can eliminate the need to supply timezone specifications by using a special time zone string local
instead to return occupancy data as of the current moment in time. Such queries must conform to the following restrictions:
Only total_occupancy
and occupancy_limit
metrics are requested
Group by location
Supply a single date range with from today
to now
Supply a single time range of store_hours
Example Request Request current occupancy for store location dace69f6-b307-11e9-819d-0000698cf233
using /v2/datamine
.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"date_ranges" : [
{
"from" : { "name":"today" },
"to" : { "name":"now" }
}
],
"group_bys" : [
{
"group" : "location",
"unit" : "",
"value" : 0
}
],
"locations" : [
"dace69f6-b307-11e9-819d-0000698cf233"
],
"metrics" : [
"total_occupancy",
"occupancy_limit"
],
"time_ranges" : [
{"type": "store_hours"}
],
"time_zone": "local"
}
Example Response 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
"metrics" : [
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 179
}
],
"name" : "total_occupancy",
"ok" : true
},
{
"data" : [
{
"group" : {
"name" : "San Jose Store",
"qualified_name" : "San Jose Store",
"type" : "location",
"uuid" : "dace69f6-b307-11e9-819d-0000698cf233"
},
"index" : 0,
"validity" : "complete",
"value" : 300
}
],
"name" : "occupancy_limit",
"ok" : true
}
],
"ok" : true
}
Update Occupancy Update occupancy by a specified adjustment value.
POST https://<subscription>.api.retailnext.net/v1/occupancy/adjust
Parameters store_uuid *
string
UUID of store location
adjustment_count*
integer
Occupancy adjustment value. Supports negative or positive values, but must be non-zero.
adjustment_date
ISO 8601
Occupancy adjustment date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ ). If omitted, the current time in store local time zone will be used instead.
* required parameter
Occupancy updates are only accepted within store hours and when the store’s occupancy limit is defined.
Example Request Show request
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/occupancy/adjust"
Where the request.json
file contains:
1
2
3
4
5
{
"store_uuid" : "813737be-9f9d-11ea-8372-000008adea78",
"adjustment_time" : "2021-03-16T12:00:00+00:00",
"adjustment_count" : 5
}
Users
Query Users Returns users and related fields.
GET https://<subscription>.api.retailnext.net/v1/users
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users"
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"users": [
{
"type": "local",
"name": "RetailNext_User",
"email": "retailnextuser@domain.com",
"id": "2abe8330-5e0f-11ea-8522-c0009d2f3ea6",
"disabled": false,
"user_profile_id": "f76545a0-5e0e-11ea-8d71-c0003468dbae",
"location_profile_id": "fb1fcd84-7b9c-11e7-937e-4000eba63dc2",
"last_sign_in_at": "2020-03-04T12:00:28.742Z",
"current_sign_in_at": "2020-03-04T12:01:06.2Z",
"invitation_accepted": true,
"invitation_locale": "en_US"
},
...
]
}
Filtering By appending the URL, you can filter your response to only include users with a specified parameter’s value.
Show filtering examples
Type If you have SSO enabled, you can append your query to only include local
or SSO
users, respectively. The example below queries for SSO users only.
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users?type=SSO"
Email The example below queries for users with an email address that exactly matches storemanager@domain.com
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users?email=storemanager0@domain.com
Create Users Creates an SSO user account.
POST https://<subscription>.api.retailnext.net/v1/users
Parameters email* email address
User email address
type* string
Type of user account. Only sso
value accepted.
name string
default: <user_email>
User name
disabled
boolean
default: false
User disabled status
user_profile_id**
string
UUID of User Profile
location_profile_id**
string
UUID of Location Profile
location_ids**
string
UUID of Location. Interchangeable with location_profile_id
, see Custom Locations for details.
* required parameter
** conditionally required parameter
If Use SAML Attribute is selected in Admin Settings > Single Sign-on: you cannot specify the user’s permissions in RetailNext (i.e. user and/or location profile) as these are managed through the organization's Identity Provider
If, instead, Manage on Users page is selected in Admin Settings > Single Sign-on: you must specify the user’s permissions (i.e. user and/or location profile) when creating a new user
You can only create users if you have the permission: Manage users and location profiles. Similarly, you can only create or view users in RetailNext with the same or lower user and/or location profile permissions compared to yours.
Example Request Show request
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPOST "https://<subscription>.api.retailnext.net/v1/users"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"user": {
"email":
"sandra.bloch@domain.com",
"type":
"sso",
"name":
"Sandra Bloch",
"disabled":
false,
"user_profile_id":
"8b26a6c0-5027-11eb-8039-8000f92819c5",
"location_profile_id":
"9e701012-4c76-11e7-853d-c0001c66456e"
}
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
{
"user": {
"type": "sso",
"name": "Sandra Bloch",
"email": "sandra.bloch@domain.com",
"id": "dc2e3c2e-5029-11eb-8b74-40002f864577",
"disabled": false,
"user_profile_id": "8b26a6c0-5027-11eb-8039-8000f92819c5",
"location_profile_id": "9e701012-4c76-11e7-853d-c0001c66456e",
}
}
Update Users Update the permissions of a user.
PUT https://<subscription>.api.retailnext.net/v1/users/<user_uuid>
Parameters user_profile_id
string
UUID of User Profile
location_profile_id
string
UUID of Location Profile
location_ids
string
UUID of Location. Interchangeable with location_profile_id
, see Custom Locations for details.
Updating the user or location profile of another user requires that the requestor's user account has the same or higher permissions.
Example Request Show request
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v1/users/<user_uuid>"
Where the request.json
file contains:
1
2
3
4
5
6
{
"user_profile_id" :
"74178848-bbf4-11e8-8fcb-40000e637ca2",
"location_profile_id" :
"93334489-6d6a-11eb-9ec3-00000d9c1e4f"
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"user": {
"type": "local",
"name": "RN user",
"email": "rnuser@domain.com",
"id": "332e3c2e-5029-11eb-8b74-40002f864572",
"disabled": false,
"user_profile_id": "74178848-bbf4-11e8-8fcb-40000e637ca2",
"location_profile_id": "93334489-6d6a-11eb-9ec3-00000d9c1e4f",
"last_sign_in_at": "2021-01-06T14:16:53.597Z",
"current_sign_in_at": "2021-01-11T10:21:25.407Z",
"invitation_accepted": true,
"invitation_locale": "en_US"
}
}
Custom Locations Update explicitly authorized locations of a user, instead of a predefined location profile.
To specify custom locations replace the key location_profile_id
with location_ids
, then list the UUIDs of permitted locations.
Show custom locations example
Example Request 1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-XPUT "https://<subscription>.api.retailnext.net/v1/users/<user_uuid>"
Where the request.json
file contains:
1
2
3
4
5
6
{
"location_ids": [
"3749e26c-a7da-11e8-9eae-40007c493637",
"64b13bf4-35af-11e7-9c1c-c000609b0f52"
]
}
Example Response 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"user": {
"type": "local",
"name": "RN user",
"email": "rnuser@domain.com",
"id": "332e3c2e-5029-11eb-8b74-40002f864572",
"disabled": false,
"user_profile_id": "64178848-bbf4-11e8-8fcb-40000e637ca1",
"location_ids": [
"3749e26c-a7da-11e8-9eae-40007c493637",
"64b13bf4-35af-11e7-9c1c-c000609b0f52"
],
"last_sign_in_at": "2021-01-06T14:16:53.597Z",
"current_sign_in_at": "2021-01-11T10:21:25.407Z",
"invitation_accepted": true,
"invitation_locale": "en_US"
}
}
User Profiles Query User Profiles Returns user profiles and related fields.
GET https://<subscription>.api.retailnext.net/v1/user_profiles
To query a specific user profile, append the above URL with /<user_profile_uuid>
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/user_profiles"
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"user_profiles": [
{
"id": "b43dfbe6-1b4d-11e9-93fd-4000551d9e45",
"name": "API Example",
"enterprise_groups": [],
"use_idle_timeout": false,
"idle_timeout": 54000,
"subscription_admin": false,
"visible_dashboard_widgets": {
"pages": [
"analytics",
"reports",
"point_of_sale"
],
"data_types": [
"export_analytics_data",
"guest_wifi",
"individual_data",
"mobile_device_detection",
"pos",
"pos_exception_data",
"pos_individual_transactions",
"pos_transactions_export",
"access_reports",
"staffing_data",
"tracks_and_kinetic_maps",
"traffic"
],
"admin_tasks": [
"health_monitoring_alerts",
"cameras",
"pos_terminals",
"security_event_sources",
"store_appliances",
"fpa",
"pos_uploads",
"sku_map_uploads",
"staff_hour_uploads",
"traffic_uploads",
"store_hours_uploads",
"goals_uploads",
"currency_uploads",
"deleted_items",
"dwell_uploads"
],
"allow_individual_activity": [
"mobile_device_detection"
]
}
},
...
]
}
Location Profiles Query Location Profiles Returns location profiles and related fields.
GET https://<subscription>.api.retailnext.net/v1/location_profiles
To query a specific location profile, append the above URL with /<location_profile_uuid>
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/location_profiles"
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"location_profiles": [
{
"id": "bffb9ff6-1b4d-11e9-8b97-000006c38736",
"name": "API Example",
"enterprise_groups": [],
"location_ids": [
"e235aee4-cf7a-11e5-973e-8000a847d47a"
]
},
...
]
}
Health Monitoring Query Health Alerts Returns health alerts and related fields.
POST https://<subscription>.api.retailnext.net/v1/healthalerts
Parameters start_time
ISO 8601
Alerts created before a date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ )
Example Request Show request
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/healthalerts"
Where the request.json
file contains:
1
2
3
{
"start_time" : "2021-01-22T00:00:00Z"
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"result": [
{
"alert_creation_time": "2021-01-11T11:38:34.942-08:00",
"description": "Haven't heard from Aurora sensor recently",
"event_time": "2021-01-11T10:38:34-08:00",
"resolved": true,
"resolved_time": "2021-01-12T14:11:33.522-08:00",
"severity": "resolved",
"store_uuid": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"store_name": "Caspar City Plaza",
"subject_id": "20:C3:A4:80:09:69",
"subject_name": "CCP Aurora (20:C3:A4:80:09:69)",
"type": "connectiondown",
"uuid": "97fd95e0-5444-11eb-8b83-40003ca6d233",
"obsolete": false
},
...
]
}
Response Fields All Health Monitoring API response fields are a subset of the same fields provided by Automated Systems notification emails. Visit Health Monitoring Emails > Notification to Automated Systems for a list of field descriptions.
Predicted Traffic Query Predicted Traffic Returns predicted traffic metrics within specified parameters.
POST https://<subscription>.api.retailnext.net/v1/predictedtraffic
Parameters store_uuid *
string
UUID of store location. Supports one entry per query.
first_day*
date
First day in yyyy-mm-dd . Must be in the future.
last_day*
date
Last day in yyyy-mm-dd . Must be in the future.
* required parameter
Responses are grouped into 15-minute intervals. This cannot be configured.
In one query, up to 7 days can be requested. For additional days, use multiple requests.
Predicted traffic is available for the upcoming month, up to 31 days. Queries exceeding this range will return an error.
Sufficient historical data is required for predictions
See Traffic Prediction to learn more about the traffic prediction model
Predicted Traffic API supports 3 concurrent requests per subscription. Requests exceeding this limit will receive error HTTP 429.
Example Request Show request
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/predictedtraffic"
Where the request.json
file contains:
1
2
3
4
5
{
"store_uuid" : "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9",
"first_day" : "2021-03-17",
"last_day" : "2021-03-23"
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"ok": true,
"error": "",
"predictions": [
{
"time": "2021-03-17T09:00:00Z",
"value": 10
},
{
"time": "2021-03-17T09:15:00Z",
"value": 10
},
...
{
"time": "2021-03-23T20:45:00Z",
"value": 3
}
]
}
Zone Transitions Query Zone Transitions Returns FPA zone transition metrics within specified parameters.
POST https://<subscription>.api.retailnext.net/v1/zone_transitions
Parameters locations *
string
UUID of location
date_ranges *
string
"start"
and "finish"
paired with respective date values in yyyy-mm-dd
metrics
string
default: all
"all"
, "employee"
and "customer"
transitions
string
default: direct_only
"direct_only"
, "direct_and_indirect"
and "directionless"
dwells
string
default: dwells_only
"dwells_only"
, "non_dwells"
and "all_traffic"
time_ranges
string
default: store_hours
"start"
and "finish"
paired with respective time values in hh:mm , or, "type": "store_hours"
days_of_week
string
default: all days of week
"monday"
, "tuesday"
, "wednesday"
, "thursday"
, "friday"
, "saturday"
and "sunday"
* required parameter
Example Request Show request
This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day.
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/zone_transitions"
Where the request.json
file contains:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"locations" : [
"cdf7322e-3329-11ea-8e45-80003c755d3e",
"f1cc33f2-3329-11ea-9b32-80001a18e60d"
],
"date_ranges" : [
{
"start": "2021-02-15",
"finish": "2021-02-22"
}
],
"metrics" : [
"customer"
],
"transitions" :
"direct_and_indirect",
"dwells" :
"all_traffic",
"time_ranges" : [
{
"start": "10:30",
"finish": "13:00"
}
],
"days_of_week" : [
"friday",
"saturday"
]
}
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
"metrics": [
{
"name": "customer",
"data": [
{
"floorplan": {
"uuid": "e0acd09e-2e7a-11ea-8b1a-40002569de69",
"name": "Garden Station Floorplan",
"store_uuid": "af1fd977-9e2c-11e5-9bbe-0e5ba9bee1b9",
"store_name": "Garden Station"
},
"zones": [
{
"uuid": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"name": "Entrance",
"location_uuid": "f1cc33f2-3329-11ea-9b32-80001a18e60d",
"location_name": "Entrance Zone"
},
{
"uuid": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"name": "Denim",
"location_uuid": "cdf7322e-3329-11ea-8e45-80003c755d3e",
"location_name": "Denim Zone"
}
],
"transitions": [
{
"from_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"to_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"value": 170,
"percentage": 54
},
{
"from_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"to_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"value": 147,
"percentage": 46
},
{
"from_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"to_zone_id": "a1ec24c6-2e7b-11ea-960c-8000bec20274",
"value": 42,
"percentage": 69
},
{
"from_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"to_zone_id": "a34979f4-2e7b-11ea-8dfd-c000826898db",
"value": 19,
"percentage": 31
}
]
}
]
}
]
}
FPA Zones Query FPA Zones Returns FPA floorplans and related fields.
GET https://<subscription>.api.retailnext.net/v1/fpafloorplans
The example queries all FPA floorplans within a subscription.
To query all floorplans within a specific store , use https://<subscription>.api.retailnext.net/v1/stores/<store_uuid>/fpafloorplans
To query a specific floorplan , use https://<subscription>.api.retailnext.net/v1/fpafloorplans/<floorplan_uuid>
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/fpafloorplans"
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
[
{
"id": "7ce0f10c-508f-11eb-9c50-000048e74782",
"name": "API Store Floorplan",
"store_id": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
"store_name": "API Store",
"zones": [
{
"id": "f64b51ac-546f-11eb-9441-8000514932de",
"name": "Table 1",
"type": "fpa",
"location_id": "24f99a38-5478-11eb-98ec-40002ded88bc",
"location_name": "FPA Zones",
"area": 46907.55844251474,
"dwell_time_threshold_ms": 10,
"zone_threshold_mm": 1000,
"points": [
{
"x": 1751.2620277487956,
"y": 384.9399262748038
},
{
"x": 1918.1988757176557,
"y": 383.3687429022536
},
{
"x": 1915.0491238691866,
"y": 664.610566588743
},
{
"x": 1746.5373999760916,
"y": 663.0393832161927
},
{
"x": 1751.2620277487956,
"y": 384.9399262748038
}
]
},
...
]
}
]
Response Fields Show response field descriptions
id
f64b51ac-546f-11eb-9441-8000514932de
UUID of floorplan or zone
name
API Store Floorplan
Name of floorplan or zone
store_id
aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9
UUID of store location
store_name
API Store
Name of store
type
fpa / staff / mask
Type of zone. Kinetic Map Masks are excluded.
location_id
24f99a38-5478-11eb-98ec-40002ded88bc
UUID of a zone’s parent location
location_name
Table 1
Name of a zone’s parent location
area
46907.56
Size of the zone location in square centimeters
dwell_time_threshold_ms
10
Minimum amount of time a shopper must linger in a zone before registering a dwell event, defined in milliseconds
zone_threshold_mm
1000
Size of the zone’s configurable buffer area for track detection and metrics collection, defined in millimeters
x
1751.2620277487956
X coordinate of a point of the zone relative to the overall floor plan, defined in centimeters
y
384.9399262748038
Y coordinate of a point of the zone relative to the overall floor plan, defined in centimeters
Inventory
Pagination - Inventory API queries use unique X-Page
string values, rather than an integer as described for other v1 API methods.
Query Cameras Returns camera hardware and related fields.
GET https://<subscription>.api.retailnext.net/v1/inventory/cameras
To query cameras in a specific store, use store_uuid
parameter with store location unique id, by appending the above URL with ?store_uuid=<store_location_uuid>
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/cameras"
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
"ok": true,
"next_page": "CAC:13:37:D0:86:77",
"cameras": [
{
"type": 1,
"device_id": "20:C3:13:0F:1D:2A",
"device_name": "Aisle Camera",
"store_uuid": "a434a682-30a0-11ea-896a-00005f259c6e",
"appliance_id": "",
"vendor": "RetailNext",
"model": "Aurora",
"private_ip": "10.10.10.179",
"public_ip": "162.254.19.20",
"last_heard": "2020-01-14T22:30:18.363Z",
"serial_number": "",
"network_configuration": {
"mode": 0,
"ip": "",
"gateway": "",
"dns": "",
"ntp": ""
},
"video_channel_uuids": [
"d86d75e2-3338-11ea-95e3-000071946766"
],
"video_channel_count": 1,
"configuration_summary": {},
"analytics": {
"traffic_line_count": 1,
"dwell_zone_count": 0,
"direction_line_configured": false
},
"height": 3860
},
...
]
}
Response Fields Show response field descriptions
analytics: direction_line_configured
true / false
True if a direction line is configured on the device
analytics: dwell_zone_count
0, 1, 2, ...
Number of dwell zones configured on the device
analytics: traffic_line_count
0, 1, 2, ...
Number of traffic lines configured on the device
appliance_id
97f59a38-5478-11eb-98ec-40002ded88ty
UUID of appliance to which the device is connected
configuration_summary: device_name
Entrance
Name of device (Brickstream sensors only)
configuration_summary: sensor_group
Brooklyn, NY
Name of device location (Xovis sensors only)
configuration_summary: sensor_name
Entrance
Name of device (Xovis sensors only)
configuration_summary: site_name
Brooklyn, NY
Name of device location (Brickstream sensors only)
device_id
20:C3:13:0F:1D:2A
MAC address of the device
device_name
Back Entrance
Name of device
height
3860
Configured height of device, defined in millimeters (Aurora only)
last_heard
2020-01-14T22:30:18.363Z
Timestamp of the last communication from the device to the RetailNext cloud service
model
Aurora
Model of device
network_configuration: dns
8.8.8.8
Local static configuration of device DNS
network_configuration: gateway
192.168.1.1
Local static configuration of device Gateway
network_configuration: ip
192.168.1.15
Local static configuration of device IP address
network_configuration: mode
0, 1
Local network configuration of device, DHCP (0) or Static (1)
network_configuration: ntp
pool.ntp.org
Local static configuration of device NTP
private_ip
192.168.1.15
Local Area Network IP address of device
public_ip
73.181.6.188
Public IP address of device
serial_number
15290487
Serial number of Xovis or Brickstream device
store_uuid
a434a682-30a0-11ea-896a-00005f259c6e
UUID of store location to which the device is assigned
type
0, 1, 2
Device type: (0) Monocular camera, (1) Aurora, (2) Xovis, Brickstream
vendor
RetailNext, Xovis, Brickstream, Axis
Device Vendor
video_channel_count
0, 1, 2, ...
Number of video channels configured for device
video_channel_uuids
9290bc70-3480-11ea-81c9-c000c7e8079f
UUID of video channels configured for device
Cameras Inventory API supports 3 concurrent requests per subscription. Requests exceeding this limit will receive error HTTP 429.
Query Channels Returns video channels and related fields.
GET https://<subscription>.api.retailnext.net/v1/inventory/channels
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/channels"
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"ok": true,
"next_page": "end",
"channels": [
{
"channel_uuid": "9290bc70-3480-11ea-81c9-c000c7e8079e",
"name": "Registration Desk",
"device_id": "92710a06-3480-11ea-9877-40003d3dd9a9",
"resolution": "1280x960",
"frame_rate": 10,
"record_on_motion": true,
"minimum_retention_days": 0,
"maximun_retention_days": 0,
"blur_video": false,
"recording_enabled": true,
"snapshot_enabled": true,
"snapshot_interval_secs": 300,
"snapshot_resolution": "1400x1050"
},
...
]
}
Response Fields Show response field descriptions
blur_video
true / false
True if video blurring is enabled on the device
channel_uuid
9290bc70-3480-11ea-81c9-c000c7e8079e
UUID of the video channel
device_id
92710a06-3480-11ea-9877-40003d3dd9a9
UUID of device producing the video channel
frame_rate
10
Video recording quality setting for frames per second (fps)
name
Registration Desk
Configured name of video channel
recording_enabled
true / false
True if recording is enabled for the video channel
record_on_motion
true / false
True if recording on motion is enabled for the video channel
resolution
1280x960
Video recording quality setting for resolution
snapshot_enabled
true / false
True if high resolution snapshots are enabled for the video channel
snapshot_interval_secs
300
Configured time interval between snapshots, defined in seconds
snapshot_resolution
1400x1050
Snapshot quality setting for resolution
Query Appliances Returns appliance hardware and related fields.
GET https://<subscription>.api.retailnext.net/v1/inventory/appliances
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/appliances"
Example Response Show response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"ok": true,
"next_page": "end",
"store_appliances": [
{
"appliance_id": "323231f8-6afg-11eb-8684-4000fc072082",
"store_uuid": "af21ffd8-9e2c-11e5-9bc9-0e5ba9bee1b9",
"mac_address": "00:0D:29:60:FB:CB",
"private_ip": "192.168.95.92",
"network_configuration": {
"mode": 0,
"ip": "",
"gateway": "",
"dns": "",
"ntp": ""
},
"public_ip": "104.59.220.132"
},
...
]
}
Response Fields Show response field descriptions
appliance_id
323231f8-6afg-11eb-8684-4000fc072082
UUID of appliance
mac_address
00:0D:29:60:FB:CB
MAC address of appliance
network_configuration: dns
8.8.8.8
Local static configuration of appliance DNS
network_configuration: gateway
192.168.1.1
Local static configuration of appliance Gateway
network_configuration: ip
192.168.1.15
Local static configuration of appliance IP address
network_configuration: mode
0, 1
Local network configuration of appliance, DHCP (0) and Static (1)
network_configuration: ntp
pool.ntp.org
Local static configuration of appliance NTP
private_ip
192.168.1.15
Local Area Network IP address of appliance
public_ip
73.181.6.188
Public IP address of appliance
store_uuid
af21ffd8-9e2c-11e5-9bc9-0e5ba9bee1b9
UUID of store location to which the appliance is assigned
Video Export
Start Export Starts a video export within specified parameters.
POST https://<subscription>.api.retailnext.net/v1/video/export/start
Parameters channel *
string
UUID of video channel
Provide multiple channel
parameters to include up to 16 total video channels from the same store appliance.
When multiple channels are specified, you may also provide a resolution
parameter to determine the resolution of the video. The default resolution is 1024x768.
start *
ISO 8601
Export start date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ )
end *
ISO 8601
Export end date/time in ISO 8601 format (yyyy-mm-ddThh:mm:ssZ )
analytics_overlay
boolean
default: 0
0
, 1
; where 1
enables analytics overlays (tracks, traffic lines, zones and other analytic shapes)
info_overlay
boolean
default: 0
0
, 1
; where 1
enables information overlays (video channel name and date/time)
raw
boolean
default: 0
0
, 1
; where 1
enables raw video.
Raw video exports are only necessary for troubleshooting, as they are much larger and may not work with some software.
* required parameter
Successful video export requests return a location
header in the format of /v1/video/export/task/<export_id>
that can be used to subsequently download the video clip or to query its export status, as described in the next section.
Example Request Show request
1
2
3
4
5
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XPOST "https://<subscription>.api.retailnext.net/v1/video/export/start?\
start=2021-03-17T13:00:00Z&end=2021-03-17T13:05:08Z\
&channel=f2b81aa0-8c90-11eb-9d08-c00017306bd8\
&analytics_overlay=1&raw=0&info_overlay=1"
Example Response Show response
1
2
3
4
5
6
HTTP/2 201
content-type: application/json
location: /v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2
...
<
{"ok":true}
Query Export Status and Download Returns the current status of a video export and, if ready, the download link.
GET https://<subscription>.api.retailnext.net/v1/video/export/task/<export_id>
Example Request Show request
1
2
curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2"
Example Response Show response
1
2
3
4
5
6
HTTP/2 201
content-type: application/json
location: /v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2
...
<
{"ok":true}
The export status is detailed in the HTTP response code as follows.
202
Accepted - export is in progress
302
Found - export is ready. Download the file by using the provided location
header URL.
404
Expired - export has expired
424
Failed - export has failed. The response includes the reason for failure.
Exports can be deleted by using HTTP DELETE, for example-XDELETE "https://<subscription>.api.retailnext.net/v1/video/export/task/<export_id>"
Video Stream
Generate Token Returns a token to stream a video channel over HLS .
POST https://<subscription>.api.retailnext.net/v1/hlsapitoken
Parameters location_uuid *
string
UUID of location. The generated token provides access to video channels within the specified location.
* required parameter
Example Request Show request
1
2
3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/hlsapitoken"
Where the request.json
file contains:
1
2
3
{
"location_uuid" : "22940210-f49b-11e6-944b-c0001cd78189"
}
Example Response Show response
1
2
3
{
"token": "9wTw-pk1VLsEGzmzaH9vOL-a6RU"
}
Stream Video Using a generated token value, create an HLS M3U8 playlist to stream a video channel in the URL format below.
1
https://<subscription>.api.retailnext.net/v1/hls/<video_channel_uuid>.m3u8?token=<token_value>
The URL can be opened through various video applications, such as QuickTime or VLC .