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