Versions Compared

Old Version 8

changes.mady.by.user Christos Hadjiyannis

Saved on

compared with

New Version Current

changes.mady.by.user Joshua Geldenhuys

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Note

The v1 methods on this page, while still supported, have been succeeded by enhanced v2 methods. Refer to the API documentation for the up-to-date API commands and examples.

Authentication

All API endpoints are authenticated using your API token over HTTP basic auth. API tokens have a unique Access Key and Secret Key that are used during API authentication.

Subscription Admins can issue and manage API tokens for their subscription from the RetailNext cloud interface in Admin Settings > System API Access Tokens. Visit /wiki/spaces/KB/pages/1764687950 to learn more.

Authentication Header

Code Block
languageactionscript3
--basic --user <AccessKey>:<SecretKey>

Pagination

All API v1 responses have a default and maximum page length limit of 100 entries. Queries with more items than the page length limit will have responses split across multiple pages.

Parameters

X-Page-Length

integer

default: 100

If included, the response page length will match the specified value. The maximum page length is 100.

X-Page-Start

integer

If included, the response will start at the specified value. This is typically used to retrieve subsequent pages for queries that exceed the page length limit.

Example Request

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

Example Response

Code Block
HTTP/2 206 
content-type: application/json
...
x-frame-options: SAMEORIGIN
x-page-next: 20
...

Example Request for Subsequent Pages

Fetch the next page by adding "X-Page-Start" to your original request header with a value that matches "X-Page-Next" from the previous response.

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

The HTTP response code indicates whether a response contains all possible entries, or if you need to fetch more pages; whereby:

  • 200: OK (no additional pages)

  • 206: Partial Content

Locations

Query Locations

Returns a list of locations and related fields.

Status
colourGreen
titleGET
https://<subscription>.api.retailnext.net/v1/location

Example Request

Code Block
languageactionscript3
curl -viL --basic --user <AccessKey>:<SecretKey> \
"https://<subscription>.api.retailnext.net/v1/location"

Example Response

Code Block
languagejson
{
    "locations": [
        {
            "id": "451a0868-db27-11e0-8e18-cdb59fa2239e",
            "name": "RetailNext",
            "type": "region",
            "parent_id": null,
            "attributes": []
        },
        {
            "id": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
            "name": "Caspar City Plaza",
            "type": "store",
            "parent_id": "22940210-f49b-11e6-944b-c0001cd87189",
            "time_zone": "America/Los_Angeles",
            "current_utc_offset": "UTC-08:00",
            "time_zone_abbrev": "PST",
            "comp_start_date": "2015-01-01",
            "address": {
                "street_address": "Los Angeles, CA 90012"
            },
            "attributes": [
                {
                    "name": "Store Type",
                    "value": "Traditional Mall"
                },
                {
                    "name": "Currency Type",
                    "value": "USD"
                }
            ],
            "currency": "USD"
        },
        {
            "id": "aec5c815-9e2c-11e5-9bb6-0e5ba9bee1b9",
            "name": "Main Entrance",
            "type": "entrance",
            "parent_id": "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9",
            "attributes": []
        },
...
}

Datamine

Query Metrics

Returns a list of metrics within specified parameters.

Status
colourBlue
titlePOST
https://<subscription>.api.retailnext.net/v1/datamine

Parameters

locations*

string

UUID of the location

metrics*

string

See Metrics Glossary for API identifiers

date_ranges*

string

"first_day" and "last_day" in yyyy-mm-dd

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 further below

* required parameter

Info

Traffic metrics validity - When querying traffic metrics the response will include an additional "validity" fields with the possible values being: "complete", "incomplete" and "imputed". An "incomplete" or "imputed" response indicates that there was a problem collecting traffic data during the queried range (e.g. power not supplied to sensor). Learn more about these values on the Knowledge Base page, Imputing Missing Traffic Data.

Example Request

This example queries Traffic In & Out metrics from February 20, 2021 to February 27, 2021 during store hours, with the response grouped by one day.

Code Block
languageactionscript3
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
languagejson
{
   "metrics" : [
      "traffic_in",
      "traffic_out"
   ],
   "date_ranges" : [
      {
      "first_day": "2021-02-20",
      "last_day": "2021-02-27"
      }
    ],
    "time_ranges" : [
      {
         "type": "store_hours"
      }
   ],
   "group_bys" : [
      {
      "group": "date",
      "unit": "days",
      "value": 1
      }
   ],
   "locations" : [
      "aec3dc7e-9e2c-11e5-9bb4-0e5ba9bee1b9"
   ]
}

Example Response

Code Block
languagejson
{
    "ok": true,
    "metrics": [
        {
            "name": "traffic_in",
            "ok": true,
            "data": [
                {
                    "value": 262,
                    "validity": "complete",
                    "group": {
                        "start": "2021-02-20",
                        "finish": "2021-02-20",
                        "type": "date"
                    },
                    "index": 0
                },
...
            ]
        },
        {
            "name": "traffic_out",
            "ok": true,
            "data": [
                {
                    "value": 261,
                    "validity": "complete",
                    "group": {
                        "start": "2021-02-20",
                        "finish": "2021-02-20",
                        "type": "date"
                    },
                    "index": 0
                },
...
            ]
        }
    ]
}

More Details on Group Bys

The "group_bys" option determines how the data is sliced, or grouped, in the response. It supports one or more of the following "group" keys: "time", "date", "location", "day_of_week". Each group is further associated with a "unit" and "value" key for additional flexibility.

Example Requests

Code Block
languageactionscript3
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
languagejson
{
...
    "group_bys" : [
      {
      "group": "date",
      "unit": "days",
      "value": 1
      }
    ],
...
}

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

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

Supported Options

Code Block
languagejson
"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 Current Occupancy

Returns the current occupancy at a location.

Status
colourBlue
titlePOST
https://<subscription>.api.retailnext.net/v1/datamine

Example Request

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

Code Block
languageactionscript3
curl -viL --basic --user <AccessKey>:<SecretKey> \
-H "Accept: application/json" -d "@request.json" \
-POST "https://<subscription>.api.retailnext.net/v1/datamine"

Where the request.json file contains:

Code Block
languagejson
{
    "date_ranges" : [
      {
        "first_day" : "2020-04-21",
        "last_day" : "2020-04-21"
      }
    ],
    "group_bys" : [
      {
        "group" : "date",
        "unit" : "days",
        "value" : 1
      }
    ],
    "locations" : [
        "dace69f6-b307-11e9-819d-0000698cf233"
    ],
    "metrics" : [
        "traffic_in",
        "traffic_out",
        "total_occupancy"
    ],
    "time_ranges" : [
      {
        "type" : "store_hours"
      }
    ]
}

Example Response

The query results in a traffic_out of 26 and traffic_in of 34, so the total_occupancy is 8.

Code Block
languagejson
{
   "metrics" : [
      {
         "data" : [
            {
               "group" : {
                  "finish" : "2020-04-21",
                  "start" : "2020-04-21",
                  "type" : "date"
               },
               "index" : 0,
               "validity" : "complete",
               "value" : 34
            }
         ],
         "name" : "traffic_in",
         "ok" : true
      },
      {
         "data" : [
            {
               "group" : {
                  "finish" : "2020-04-21",
                  "start" : "2020-04-21",
                  "type" : "date"
               },
               "index" : 0,
               "validity" : "complete",
               "value" : 26
            }
         ],
         "name" : "traffic_out",
         "ok" : true
      },
      {
         "data" : [
            {
               "group" : {
                  "finish" : "2020-04-21",
                  "start" : "2020-04-21",
                  "type" : "date"
               },
               "index" : 0,
               "validity" : "complete",
               "value" : 8
            }
         ],
         "name" : "total_occupancy",
         "ok" : true
      }
   ],
   "ok" : true
}

On This Page

Table of Contents
maxLevel3
exclude(On This Page|Related Pages).*