Page Comparison

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.

Authentication Header

Code Block

language	actionscript3

--basic --user <AccessKey>:<SecretKey>

Table of Contents

minLevel	3
maxLevel	3
include	(Version 1 API\|Version 2 API).*
indent	30px
type	flat
separator	pipe

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

Expand

title	Show example

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "X-Page-Length: 20" \
"https://<subscription>.api.retailnext.net/v1/location"

Example Response

Expand

title	Show response

Code Block

language	json

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:

200: OK (no additional pages)
206: Partial Content

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.

Expand

title	Show example

Code Block

language	actionscript3

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

Table of Contents

minLevel	3
maxLevel	3
include	(Query Locations\|Create Locations\|Update Locations).*
type	flat
separator	pipe

Query Locations

Returns locations and related fields.

Status

colour	Blue
title	POST

https://<subscription>.api.retailnext.net/v2/location

Example Request

Expand

title	Show request

This example filters for only store type locations and includes extra fields for store_id and occupancy_limit

Code Block

language	actionscript3

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:

Code Block
{ "extra_fields": [ "store.store_id", "store.occupancy_limit" ], "where": { "and": [ { "location_types": [ "store" ] } ] } }

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Blue
title	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}

Info
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

Expand

title	Show request

This example creates a new Display sublocation type within a store.

Code Block

language	actionscript3

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:

Code Block
{ "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

Expand

title	Show response

Code Block

language	json

{
  "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.

Status

colour	Yellow
title	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)

Info
Changing the `location_type` to or from “store” or “region” is not supported (in other words, you can only change the `location_type` of sublocations).

Example Request

Expand

title	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.

Code Block

language	actionscript3

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:

Code Block

language	json

{
  "name": "Willow Glen Updated",
  "parent_uuid": "286b1000-f8b1-11e7-9337-c0009584d333",
  "area": 270.8,
  "occupancy_limit": 20
}

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Expand

title	Show bulk update occupancy limit example

This example updates the respective occupancy limit parameter of multiple store locations.

Code Block

language	actionscript3

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:

Code Block
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.

Status

colour	Blue
title	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

Expand

title	Show request

Code Block

language	actionscript3

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:

Code Block

language	json

{
    "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

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Blue
title	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}

Info

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 /wiki/spaces/KB/pages/143785991.
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

Expand

title	Show request

This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day.

Code Block

language	actionscript3

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:

Code Block

language	json

{
   "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

Expand

title	Show response

Code Block

language	json

{
    "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.

Info

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

Expand

title	Show date_ranges options

Name

The name key supports simple named date values, such as now and today.

Info
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

Code Block

language	actionscript3

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:

Code Block

language	json

{
...
    "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

Code Block

language	actionscript3

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:

Code Block

language	json

{
...
    "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

Code Block

language	actionscript3

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:

Code Block

language	json

{
...
    "date_ranges" : [
      {
      "from": {
         "absolute": {
            "year": 2021,
            "week": 2,
            "day": 4 }
          },
      "to": {
         "absolute": {
            "year": 2021,
            "week": 3 }
          }
      }
    ],
...
}

Supported Options

Code Block

{
"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

Code Block

// 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

Code Block

language	actionscript3

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:

Code Block

language	json

{
...
    "date_ranges" : [
      {
      "from": {
        "relative": {
          "base": {
            "gregorian": "2021-02-27T00:00:00Z" }
          }
        },
      "to": {
        "relative": {
          "add_days": 5 }
        }
      }
    ],
...
}

Supported Options

Code Block

{
  "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
  }
}

Info

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

Code Block

language	actionscript3

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:

Code Block

language	json

{
...
    "date_ranges" : [
      {
      "from": {
        "absolute": {
          "year": 2020,
          "month": 6 }
        },
      "to": {
        "relative": {
          "add_months": 4 }
        }
      }
    ],
...
}

Date range for last week - the request.json file contains:

Code Block

language	json

{
...
    "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:

Code Block

language	json

{
...
    "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:

Code Block

{
...
   "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.

Expand

title	Show group_bys options

Example Requests

Code Block

language	actionscript3

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:

Code Block

language	json

{
...
    "group_bys" : [
      {
      "group": "date",
      "unit": "days",
      "value": 1
      }
    ],
...
}

Layered Grouping by location, then time - the request.json file contains:

Code Block

language	json

{
...
    "group_bys" : [
      {
      "group": "location",
      "unit": "",
      "value": 1
      },
      {
      "group": "time",
      "unit": "hours",
      "value": 1
      }
    ],
...
}

Supported Options

Code Block

language	json

"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

Table of Contents

minLevel	3
maxLevel	3
include	(Query Occupancy\|Update Occupancy).*
type	flat
separator	pipe

Query Occupancy

Returns current occupancy metrics.

Status

colour	Blue
title	POST

https://<subscription>.api.retailnext.net/v2/datamine

Example Request

Expand

title	Show request

This example queries for the current occupancy of the store location dace69f6-b307-11e9-819d-0000698cf233.

Code Block

language	actionscript3

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:

Code Block

language	json

{
    "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"
}

Info

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

Expand

title	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.

Code Block

language	json

{
   "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.

Expand

title	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.

Code Block
{ "extra_fields" : [ "store.time_zone" ], "where" : { "uuids" : [ "dace69f6-b307-11e9-819d-0000698cf233" ] } }

Example Response

Code Block

{
   "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.

Code Block

{
      "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

Code Block

language	json

{
   "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.

Status

colour	Blue
title	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}

Info
Occupancy updates are only accepted within store hours and when the store’s occupancy limit is defined.

Example Request

Expand

title	Show request

Code Block

language	actionscript3

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:

Code Block

language	json

{
      "store_uuid" : "813737be-9f9d-11ea-8372-000008adea78",
      "adjustment_time" : "2021-03-16T12:00:00+00:00",
      "adjustment_count" : 5
}

Users

Table of Contents

minLevel	3
maxLevel	3
include	(Query Users\|Create Users\|Update Users).*
type	flat
separator	pipe

Query Users

Returns users and related fields.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/users

Example Request

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/users"

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Expand

title	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.

Code Block

language	actionscript3

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

Code Block

language	actionscript3

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.

Status

colour	Blue
title	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}

Info

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

Expand

title	Show request

Code Block

language	actionscript3

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:

Code Block

language	json

{
   "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

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Yellow
title	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.

Info
Updating the user or location profile of another user requires that the requestor's user account has the same or higher permissions.

Example Request

Expand

title	Show request

Code Block

language	actionscript3

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:

Code Block

language	json

{
    "user_profile_id" :
       "74178848-bbf4-11e8-8fcb-40000e637ca2",
    "location_profile_id" :
       "93334489-6d6a-11eb-9ec3-00000d9c1e4f"
}

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Expand

title	Show custom locations example

Example Request

Code Block

language	actionscript3

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:

Code Block

language	json

{
    "location_ids": [
        "3749e26c-a7da-11e8-9eae-40007c493637",
        "64b13bf4-35af-11e7-9c1c-c000609b0f52"
    ]
}

Example Response

Code Block

language	json

{
    "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.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/user_profiles

Info
To query a specific user profile, append the above URL with `/<user_profile_uuid>`

Example Request

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/user_profiles"

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/location_profiles

Info
To query a specific location profile, append the above URL with `/<location_profile_uuid>`

Example Request

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/location_profiles"

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Blue
title	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

Expand

title	Show request

Code Block

language	actionscript3

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:

Code Block

language	json

{
      "start_time" : "2021-01-22T00:00:00Z"
}

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Blue
title	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}

Info

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 /wiki/spaces/KB/pages/3005349996 to learn more about the traffic prediction model

Example Request

Expand

title	Show request

Code Block

language	actionscript3

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:

Code Block

language	json

{
      "store_uuid" : "aec5c886-9e2c-11e5-9bb7-0e5ba9bee1b9",
      "first_day" : "2021-03-17",
      "last_day" : "2021-03-23"
}

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Blue
title	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

Expand

title	Show request

This example queries Traffic In & Out metrics for last week during store hours, with the response grouped by one day.

Code Block

language	actionscript3

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:

Code Block

language	json

{
    "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

Expand

title	Show response

Code Block

language	json

{
    "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.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/fpafloorplans

Info

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

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/fpafloorplans"

Example Response

Expand

title	Show response

Code Block

language	json

[
    {
        "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

Expand

title	Show response field descriptions

Field	Sample Values	Description
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

Table of Contents

minLevel	3
maxLevel	3
include	(Query Cameras\|Query Channels\|Query Appliances).*
type	flat
separator	pipe

Info
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.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/inventory/cameras

Example Request

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/cameras"

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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

Expand

title	Show response field descriptions

Field	Sample Values	Description
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

Query Channels

Returns video channels and related fields.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/inventory/channels

Example Request

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/channels"

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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

Expand

title	Show response field descriptions

Field	Sample Values	Description
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.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/inventory/appliances

Example Request

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/inventory/appliances"

Example Response

Expand

title	Show response

Code Block

language	json

{
    "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

Expand

title	Show response field descriptions

Field	Sample Values	Description
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

Table of Contents

minLevel	3
maxLevel	3
include	(Start Export\|Query Export Status and Download).*
type	flat
separator	pipe

Start Export

Starts a video export within specified parameters.

Status

colour	Blue
title	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}

Info
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

Expand

title	Show request

Code Block

language	actionscript3

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

Expand

title	Show response

Code Block

language	json

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.

Status

colour	Green
title	GET

https://<subscription>.api.retailnext.net/v1/video/export/task/<export_id>

Example Request

Expand

title	Show request

Code Block

language	actionscript3

curl -viL --basic --user <AccessKey>:<SecretKey> \
-XGET "https://<subscription>.api.retailnext.net/v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2"

Example Response

Expand

title	Show response

Code Block

language	json

HTTP/2 201
content-type: application/json
location: /v1/video/export/task/3ba9d435-8c91-11eb-9c23-0000d53335d2
...
< 
{"ok":true}

Info

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>"
- By default, exports are deleted after 7 days

Video Stream

Table of Contents

minLevel	3
maxLevel	3
include	(Generate Token\|Stream Video).*
type	flat
separator	pipe

Generate Token

Returns a token to stream a video channel over HLS.

Status

colour	Blue
title	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

Expand

title	Show request

Code Block

language	actionscript3

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:

Code Block

language	json

{
      "location_uuid" : "22940210-f49b-11e6-944b-c0001cd78189"
}

Example Response

Expand

title	Show response

Code Block

language	json

{
    "token": "9wTw-pk1VLsEGzmzaH9vOL-a6RU"
}

Info
See this example for step-by-step instructions to fetch parent location UUIDs (for token generation) and video channel UUIDs (for streaming) using location API queries Tokens expire after 24 hours

Stream Video

Using a generated token value, create an HLS M3U8 playlist to stream a video channel in the URL format below.

Code Block

language	actionscript3

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.

Page Comparison

Versions Compared

Old Version 89

New Version 90

Key

Authentication

Authentication Header

Pagination

Version 1 API

Parameters

Example Request

Example Response

Example Request: Subsequent Pages

Version 2 API

Locations

Query Locations

Example Request

Example Response

Extra Fields and Filtering

Create Locations

Parameters

Example Request

Example Response

Update Locations

Parameters

Example Request

Example Response

Updating Locations in Bulk

Store Hours

Query Store Hours

Parameters

Example Request

Example Response

Datamine

Query Metrics

Parameters

Example Request

Example Response

More Details on Date Ranges

Name

Example Request

Gregorian

Example Request

Absolute

Example Request

Supported Options

Date Examples

Relative

Example Request

Supported Options

Mixed Options

Example Requests

More Details on Group Bys

Example Requests

Supported Options

Occupancy

Query Occupancy

Example Request

Example Response

Time Zones

With Time Zone

Example Request

Example Response

Without Timezone

Example Request

Example Response

Update Occupancy

Parameters

Example Request

Users

Query Users

Example Request

Example Response

Filtering

Type

Email

Create Users

Parameters

email*

type*

email^*

type^*