/
Getting Started with the API

Getting Started with the API

This page defines various terminology and processes associated with APIs in the context of RetailNext API documentation, along with additional usage tips to help you get started.

While this page is written primarily to aid human interaction with the RetailNext API, the API is mainly intended to be used for programmed machine-to-machine interactions and human involvement should merely be once-off in order to create and test API commands.

What’s an API?

API is an acronym for Application Programming Interface. It is a set of programming code that allows software applications to communicate with each other by transmitting and exchanging data.

An API is effectively another user interface, or “window”, of a software application. Machines are generally adept at reading and using programming code within API requests and responses; while people are more adept at reading and using a graphical user interface, like the web-based RetailNext cloud interface you see and interact with through your browser. Although both forms of the interface typically interact with the same set of data, each has its own set of rules and functionality.

The RetailNext API sends and receives data in JSON format and can be interfaced with using a variety of programming languages. Our examples are documented in the context of using cURL, a command-line based tool.

API Examples

Extracting traffic data from RetailNext for integration with internal systems is one of the most common use cases of the API through the Datamine method. Below are some examples to help get you started.

Traffic Data, Store Hours

Example Request

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:

{ "metrics" : [ "traffic_in", "traffic_out" ], "date_ranges" : [ { "from": { "gregorian": "2021-02-27T00:00:00Z" }, "to": { "gregorian": "2021-02-28T00:00:00Z" } } ], "time_ranges" : [ { "type": "store_hours" } ], "group_bys" : [ { "group": "time", "unit": "hours", "value": 1 } ], "locations" : [ "<location_uuid>" ] }

Example Response

{ "ok": true, "metrics": [ { "name": "traffic_in", "ok": true, "data": [ { "value": 53, "validity": "complete", "group": { "start": "09:00", "finish": "10:00", "type": "time" }, "index": 0 }, { "value": 62, "validity": "complete", "group": { "start": "10:00", "finish": "11:00", "type": "time" }, "index": 1 }, { "value": 91, "validity": "complete", "group": { "start": "11:00", "finish": "12:00", "type": "time" }, "index": 2 }, { "value": 105, "validity": "complete", "group": { "start": "12:00", "finish": "13:00", "type": "time" }, "index": 3 }, { "value": 148, "validity": "complete", "group": { "start": "13:00", "finish": "14:00", "type": "time" }, "index": 4 }, { "value": 132, "validity": "complete", "group": { "start": "14:00", "finish": "15:00", "type": "time" }, "index": 5 }, { "value": 121, "validity": "complete", "group": { "start": "15:00", "finish": "16:00", "type": "time" }, "index": 6 }, { "value": 103, "validity": "complete", "group": { "start": "16:00", "finish": "17:00", "type": "time" }, "index": 7 }, { "value": 103, "validity": "complete", "group": { "start": "17:00", "finish": "18:00", "type": "time" }, "index": 8 }, { "value": 74, "validity": "complete", "group": { "start": "18:00", "finish": "19:00", "type": "time" }, "index": 9 }, { "value": 53, "validity": "complete", "group": { "start": "19:00", "finish": "20:00", "type": "time" }, "index": 10 }, { "value": 40, "validity": "complete", "group": { "start": "20:00", "finish": "21:00", "type": "time" }, "index": 11 } ] }, { "name": "traffic_out", "ok": true, "data": [ { "value": 53, "validity": "complete", "group": { "start": "09:00", "finish": "10:00", "type": "time" }, "index": 0 }, ... ] } ] }

Traffic Data, Full Day

Example Request

Where the request.json file contains:

Example Response

Traffic Data, Multiple Stores

Example Request

Where the request.json file contains:

Example Response

Traffic Data, Yesterday

Example Request

Where the request.json file contains:

Example Response

Traffic Data, Last 24 Hours

Example Request

Where the request.json file contains:

Example Response

Finding a store’s timezone

Some API methods require that you include a timezone in order to correctly resolve the date range. For example, including the store’s local timezone in v2/datamine queries when using name or relative date range specifications - such as name: now - ensures that the system knows to interpret the time now according to store local time.

You can get the timezone of a store by querying v2/locations and specifying extra fields.

In the example request below, dace69f6-b307-11e9-819d-0000698cf233 is the UUID of the store location:

The response then includes a time_zone key with an associated value. In this example, the timezone of store dace69f6-b307-11e9-819d-0000698cf233 is America/Los_Angeles.

Finding a store’s POS ID

By default, v2/location queries only include the name and UUID and some other attributes of locations.

You can get the store_id of a store; and if enabled, the store_pos_id and store_pos_division_id; by specifying extra fields in your query.

See API > Locations > Extra Fields and Filtering for more information.

Finding and setting occupancy limits

To get the occupancy limit of a store location, issue a v2/location query including an extra field of store.occupancy_limit. See