Overview
The Dor API provides an interface for developers to access Foot Traffic, Sales, and related metrics for existing Locations and Teams. Our API is designed to adhere to REST principles and returns JSON encoded data using standard HTTP response codes and verbs.
Base URL
https://api.getdor.com/v2/
This documentation provides information about each endpoint in the API. The right-hand pane of this page shows example requests and responses for each endpoint using cURL.
Authentication
Dor uses API keys to authenticate requests. You can find your API key and Team ID in your Dor Dashboard in the Administration section.
Basic Auth
Basic Auth Request using cURL
curl https://api.getdor.com/v2/locations \
-u tm_8hHhG7gf9shhd:0ShG8gLReppO9Vm74PUSyesec87EhH;
Or...
curl https://tm_8hHhG7gf9shhd:0ShG8gLReppO9Vm74PUSyesec87EhH@api.getdor.com/v2/locations
The Dor API requires authentication on every endpoint using HTTP Basic Auth over HTTPS.
Basic auth credentials should be sent in the format of Team_ID:API_Key
in place of Username:Password
. Credentials must be sent with every request.
Manually Creating Basic Auth Headers
Basic Auth Header Example
Authorization: Basic dG1fOGhIaEc3Z2Y5c2hoZDowU2hHOGdMUmVwcE85Vm03NFBVU3llc2VjODdFaEg=
Many development frameworks support basic auth out-of-the-box (e.g. cURL) but you can also easily create the necessary headers yourself. Send an Authorization
header with the value Basic Team_ID:API_Key
, replacing your own values for Team_ID and API_Key. The Team_ID:API_Key
portion should be base64 encoded.
For example:
If your Team ID is tm_8hHhG7gf9shhd
and your API key is 0ShG8gLReppO9Vm74PUSyesec87EhH
you would send the header in the example on the right because tm_8hHhG7gf9shhd:0ShG8gLReppO9Vm74PUSyesec87EhH
base64 encoded is dG1fOGhIaEc3Z2Y5c2hoZDowU2hHOGdMUmVwcE85Vm03NFBVU3llc2VjODdFaEg
.
Making a request with an invalid Team ID or API Key will result in a 403 response code. See Errors for more info.
Response Format
Dor uses HTTP response codes to indicate whether a request succeeded or failed. Codes in the 2XX range indicate that the request was handled successfully while codes in the 4XX and 5XX range indicate that the request failed.
Successful Responses
Response
{
"data": [
{...},
{...}
],
"meta": {
...
}
}
All API endpoints respond in a standard JSON response format for 2xx range HTTP responses. The root response object is split into two keys, data
and meta
.
The data
key will contain an array of objects for plural endpoints or a single object for singular endpoints.
The meta
key will contain information related to your request including any information required for paginating the response.
Error Responses
Errors in the 4xx and 5xx range return a standard JSON format indicating the reason for the error and along with additional contextual information.
For requests that fail with a response code of 400, the invalid
key will have more information about which parameter(s) caused the request to fail.
The Error Object
{
"code": "400",
"type": "INVALID_REQUEST_ERROR",
"message": "The request was invalid.",
"invalid": [{
"name": "limit",
"reason": "Limit must be less than 500."
}]
}
Error Codes
Code | Type | Reason |
---|---|---|
400 | INVALID_REQUEST_ERROR | The request was invalid. Check the invalid key for information about which parameters caused the error. |
402 | PAYMENT_REQUIRED_ERROR | The credentials used are valid but the account is canceled or unpaid. Contact support for more info. |
403 | AUTHENTICATION_ERROR | Your credentials are invalid. See Authentication for more info. |
404 | NOT_FOUND_ERROR | The requested URI was not found. Check the request and try again. |
429 | RATE_LIMIT_ERROR | You have exceeded the allowed number of requests. See Rate Limiting for more info. |
500 | SERVER_ERROR | An unexpected error occurred on the server. Please try again later. |
Pagination
Response
"data": [
{...},
{...}
],
"meta": {
"limit": 100,
"next": "https://api.getdor.com/v2/locations?next=2lkj23jf2fljf29"
}
Endpoints that return a list of resources are paginated if results exceed the maximum length defined for the endpoint. Dor uses a cursor-based pagination strategy for all list endpoints.
The next
key in the meta
response object will either be NULL or contain a link. If it is NULL, there are no additional results available for your query. If it contains a link, follow the link for the next page of results for your query. Continue following the next
link returned with each subsequent request to fetch all available results.
See the Meta object.
Datetimes
All datetimes in query parameters must be formatted in ISO 8601 datetime format: YYYY-MM-DDThh:mm:ss
Datetime Formats
The Dor API uses both datetimes with time zone information attached as well as datetimes that are aggregated by local time and contain no time zone information.
Some endpoints allow you to query for data bounded by a datetime range. The following options are provided.
Query parameters
Name | Type | Format | Example | Description |
---|---|---|---|---|
datetime_start | Date-time String | YYYY-MM-DDThh:mm:ss | 2020-02-14T00:00:00 | The lower bound datetime (inclusive) for querying data, relative to local time zone |
datetime_end | Date-time String | YYYY-MM-DDThh:mm:ss | 2020-02-14T00:00:00 | The upper bound datetime (exclusive) for querying data, relative to local time zone |
updated_at_start | Date-time String | YYYY-MM-DDThh:mm:ssZ | 2020-02-14T00:00:00+00:00 | Datetime for querying data that has been updated since that datetime, UTC datetime |
Datetimes Grouped by Local Time Zone
Metrics returned from the API are sometimes aggregated across multiple locations and multiple timezones (e.g. the Team Metrics endpoint). In order to make this data easy to compare, metric datetimes are grouped based on the time zone in which they were recorded. The results returned do not include time zone information because the data could represent multiple time zones.
For example:
Example Request
curl "https://api.getdor.com/v2/team-metrics?datetime_start=2019-01-01T14:00:00&datetime_end=2019-01-01T15:00:00&interval=hour" \
-u tm_8hHhG7gf9shhd:0ShG8gLReppO9Vm74PUSyesec87EhH;
Location 1 is in PST and records a foot traffic event at 2pm PST (10pm UTC). Location 2 is located in EST and records a foot traffic event at 2pm EST (7pm UTC).
If a request is made with the following parameters:
Parameter | Value |
---|---|
datetime_start | 2019-01-01T14:00:00 |
datetime_end | 2019-01-01T15:00:00 |
interval | hour |
Since both events were recorded during the same hour, relative to the time zone of the location where the sensor was installed, the foot traffic events recorded at each location will be included for a total count of 2 foot traffic events.
Rate Limiting
To ensure that our API remains stable and performant, the Dor API is rate limited.
While most implementations are likely to never hit a rate limit, developers are expected to use techniques such as caching results, limiting requests, and implementing exponential backoffs to limit load on the API.
When a rate limit is triggered, all subsequent requests will receive a 429 HTTP response (too many requests) until the end of the rate limiting period as defined in the response.
Syncing Data
Asynchronous Data
Due to the asynchronous nature of how Dor's battery operated sensors purge their data to Dor's servers, foot traffic events are not available on a real-time basis as each sensor records events. Sensors attempt to check in with Dor servers on a fixed interval based on your account configuration. The default interval is 1 hour when there are foot traffic events that need to be purged from a sensor. During periods where no new foot traffic events have been generated, Dor sensors may move to a slower update interval to preserve battery life.
Occasionally there are instances where Dor sensors may be delayed in purging their foot traffic data when they have poor connectivity. During a loss of connectivity, Dor sensors continue recording foot traffic events and store them locally. When connectivity is restored the Dor sensor will purge these events to the server. During this time the API may not have the most up-to-date representation of foot traffic at any given location. The Dor API was designed with this asynchronous nature in mind as described below.
Data in the API can only be as up to date as the most recent check in from each sensor. Sensors may check in with data recorded in the past (hours or possibly even days old). This makes simple implementations such as querying every hour for the previous hour's data problematic.
Querying by Update Timestamp
In order to properly sync all data that has changed on Dor's server, we provide the updated_at_start
query parameter. The query parameter allows API users to query for any records that have been updated since a given timestamp regardless of when that data was recorded on a sensor.
Using this method of querying for data will ensure that all new data is synced, even if it was recorded several hours or days in the past. If any metric has been updated since the last time the user synced (via the provided updated_at_start
timestamp), that resource will be included in the response.
See a full example in Syncing Hourly Data on a Schedule.
Data Validity
In order to give API users more information about the state of their foot traffic data, we provide two useful keys within the Foot Traffic resource: completeness
and validity
. These values allow API users to identify data that is incomplete and likely to update in the future, as well as data that may be incomplete or inaccurate due to detected sensor issues.
This additional information can be used to better inform decisions on how to use your foot traffic data. You may choose to exclude invalid
or incomplete
data during statistical analysis, for example.
Validity
The validity
key provides additional context around the measured state of foot traffic data for a given interval. The vast majority of your data will be in a valid
state. This means that Dor has detected that all sensors associated to a location were measuring data for the timeframe and no sensor issues were detected. Some data may be in an invalid
state, indicating that an issue was detected during the timeframe for all sensors associated to a location. If an interval includes both valid and invalid data, it will be marked as degraded
.
For example, if Dor detects that the batteries have been removed from a sensor for a 15 minute period, data for that 15 minute period will be marked as invalid
. Data for the hour will be marked as degraded
because the hour includes periods of both valid and invalid data.
Validity Definitions
Value | Description |
---|---|
valid | No sensor issues have been detected for the interval. |
degraded | Due to an unrecoverable sensor issue, some portions of the interval contain invalid or unmeasured data. |
invalid | Due to an unrecoverable sensor issue, the entire interval contains invalid or unmeasured data. |
Completeness
The completeness
key indicates whether additional data is expected for the given interval or if all data has been received. Data is marked incomplete
if the interval hasn't closed yet or if any sensors have yet to send their data after the close of the interval.
For example, if hourly data is queried at 12:10pm for the 12:00 - 1:00pm hour the data will be incomplete
because the interval includes the current time and therefore hasn't closed yet. Similarly, if the same 12:00 - 1:00pm hour is queried at 1:05pm, it will still be incomplete
until all sensors have sent data after the close of the interval at 1:00pm. Once all sensors have purged their data, the interval will be updated to complete
.
Completeness Definitions
Value | Description |
---|---|
complete | The interval has closed and all sensors associated to the location have purged their data for the interval. |
incomplete | One or more sensors associated to the location have not fully purged their data to the server for the interval. Metrics for this interval will likely update in the future. |
Endpoints
Locations
GET /locations
This endpoint returns a list of the user's locations and their associated Dor devices.
The returned list of locations are ordered by location created_at
datetime in ascending order.
You may filter the locations returned by passing a tag
in the query parameters.
By default, all locations are returned.
The updated_at_start
query parameter may be used to query for all locations that have been updated since that point in time. See Syncing.
Example Request
curl https://api.getdor.com/v2/locations?tag=West%20Coast \
-u TEAM_ID:API_KEY;
Query Parameters
Name | Type | Description |
---|---|---|
limit | integer | Max number of results returned per request. Default 200. |
tag | string | Tag name for filtering locations in a query |
updated_at_start | string | Datetime in UTC to query based on the last time data was updated. |
Response
{
"data": [
{
"id": "loc_kdOOHP70NUwPFIK8",
"name": "Store 1",
"phone_number": "555-978-5243",
"address": {
"name": "Jane's Clothing Shop",
"attn": "Jane Smith",
"address_1": "123 Main st.",
"address_2": "Unit C",
"locality": "Los Angeles",
"administrative_area": "CA",
"postal_code": "94102",
"country_code": "US",
"timezone_name": "America/Los_Angeles"
},
"shipping_address": {
"name": "Jane's Clothing Shop",
"attn": "Jane Smith",
"address_1": "123 Main st.",
"address_2": "Unit C",
"locality": "Los Angeles",
"administrative_area": "CA",
"postal_code": "94102",
"country_code": "US",
"timezone_name": "America/Los_Angeles"
},
"created_at": "2016-08-24T19:19:48+00:00",
"updated_at": "2020-03-20T03:22:43+00:00"
}
],
"meta": {
"limit": 200,
"next": null
}
}
Response Schema
Name | Type | Description |
---|---|---|
data | array | |
id | string | Unique identifier for this location assigned by Dor |
name | string | A human readable name of the location. |
phone_number | string | Location phone number |
name | string | A name associated with the address. Usually this is the name of the Location or your company |
attn | string | The ATTN field for shipments |
address_1 | string | Address line 1 |
address_2 | string | Address line 2 |
locality | string | City or other regional identifier based on country |
administrative_area | string | State, Province, or local region code based on country |
postal_code | string | Zip code or regional postal code |
country_code | string | Two digit ISO 3166-1 country code |
timezone_name | string | Descriptive time zone name, i.e. America/Chicago |
name | string | A name associated with the address. Usually this is the name of the Location or your company |
attn | string | The ATTN field for shipments |
address_1 | string | Address line 1 |
address_2 | string | Address line 2 |
locality | string | City or other regional identifier based on country |
administrative_area | string | State, Province, or local region code based on country |
postal_code | string | Zip code or regional postal code |
country_code | string | Two digit ISO 3166-1 country code |
timezone_name | string | Descriptive time zone name, i.e. America/Chicago |
updated_at | string UTC Datetime |
UTC datetime representing the most recent time this object was updated. |
created_at | string UTC Datetime |
UTC datetime representing when this object was created. |
meta | object | Contains pagination metadata for the response. See Pagination. |
limit | integer | The max number of results returned, i.e. the page size. Defaults to 200 for all list endpoints. |
next | string Nullable |
A URL for retrieving the next page of results |
GET /locations/{location_id}
Returns a Location resource given a location_id
.
Example Request
curl https://api.getdor.com/v2/locations/loc_1nm2123 \
-u TEAM_ID:API_KEY;
Response
{
"data": {
"id": "loc_X51hRSCsIksxdu9b",
"name": "East Hanover",
"phone_number": "1(555)324-6332",
"address": {
"name": "Jane's Clothing Shop",
"attn": "Jane Smith",
"address_1": "123 Main st.",
"address_2": "Unit C",
"locality": "Los Angeles",
"administrative_area": "CA",
"postal_code": "94102",
"country_code": "US",
"timezone_name": "America/Los_Angeles"
},
"shipping_address": {
"name": "Jane's Clothing Shop",
"attn": "Jane Smith",
"address_1": "PO Box 9601",
"address_2": "",
"locality": "Los Angeles",
"administrative_area": "CA",
"postal_code": "94102",
"country_code": "US",
"timezone_name": "America/Los_Angeles"
},
"updated_at": "2020-02-21T18:00:00T+00:00",
"created_at": "2020-02-14T12:00:00T+00:00"
},
"meta": {}
}
Response Schema
Name | Type | Description |
---|---|---|
data | object | |
id | string | Unique identifier for this location assigned by Dor |
name | string | A human readable name of the location. |
phone_number | string | Location phone number |
name | string | A name associated with the address. Usually this is the name of the Location or your company |
attn | string | The ATTN field for shipments |
address_1 | string | Address line 1 |
address_2 | string | Address line 2 |
locality | string | City or other regional identifier based on country |
administrative_area | string | State, Province, or local region code based on country |
postal_code | string | Zip code or regional postal code |
country_code | string | Two digit ISO 3166-1 country code |
timezone_name | string | Descriptive time zone name, i.e. America/Chicago |
name | string | A name associated with the address. Usually this is the name of the Location or your company |
attn | string | The ATTN field for shipments |
address_1 | string | Address line 1 |
address_2 | string | Address line 2 |
locality | string | City or other regional identifier based on country |
administrative_area | string | State, Province, or local region code based on country |
postal_code | string | Zip code or regional postal code |
country_code | string | Two digit ISO 3166-1 country code |
timezone_name | string | Descriptive time zone name, i.e. America/Chicago |
updated_at | string UTC Datetime |
UTC datetime representing the most recent time this object was updated. |
created_at | string UTC Datetime |
UTC datetime representing when this object was created. |
meta | object |
Tags
GET /tags
Returns a list of Tags belonging to a user's Team.
Example Request
curl https://api.getdor.com/v2/tags \
-u TEAM_ID:API_KEY;
Query Parameters
Name | Type | Description |
---|---|---|
limit | integer | |
updated_at_start | string | Datetime in UTC to query based on the last time data was updated. |
Response
{
"data": [
{
"name": "NW region",
"location_count": 2,
"updated_at": "2020-02-14 02:13:02+00:00"
},
{
"name": "NW Region",
"location_count": 2,
"updated_at": "2019-12-23 19:15:08+00:00"
}
],
"meta": {
"limit": 200,
"next": null
}
}
Response Schema
Name | Type | Description |
---|---|---|
data | array | |
name | string | |
location_count | integer | |
updated_at | string UTC Datetime |
|
meta | object | Contains pagination metadata for the response. See Pagination. |
limit | integer | The max number of results returned, i.e. the page size. Defaults to 200 for all list endpoints. |
next | string | A URL for retrieving the next page of results |
GET /tags/{tag}
Returns a single Tag and an array of Locations associated to the Tag.
Example Request
curl https://api.getdor.com/v2/tags/West%20Coast \
-u TEAM_ID:API_KEY;
Response Schema
Name | Type | Description |
---|---|---|
data | object | |
name | string | Name of tag to describe grouping of locations |
location_count | integer | Number of associated locations |
updated_at | string UTC Datetime Nullable |
UTC datetime representing the most recent time this object was updated. |
id | string | |
name | string | |
meta | object |
Metrics
GET /location-metrics
The Location Metrics endpoint returns data aggregated by location. The results returned from this endpoint can be used to gain insight into individual locations or to compare locations against each other.
To retrieve data that is aggregated over all locations on your team or a Tag, refer to the Team Metrics endpoint.
Returned data is aggregated by location so that one result is returned for each interval
of time at each location. The interval
can be one of: 15m, hour, day, week, month, year. For example, if the hour interval
is used, a result will be returned for each hour and location in the requested range. If your team has two locations and requested 24 hours worth of hour intervals, a total of 48 (2 x 24) Location Metrics would be returned.
By default, Location Metrics for all of your locations are returned. You may optionally choose to filter results to only a subset of your locations. Results can be filtered using the tag
or location_ids
query parameters. For example, if the “West Coast” tag is chosen and interval
is day, one result will be returned for each location in the "West Coast" Tag for each day in the range.
There are two ways to query for results:
- The
datetime_start
(inclusive) anddatetime_end
(exclusive) parameters can be used to query for data recorded within the specified datetime range. Note that these parameters are grouped by local timezone. - The
updated_at_start
UTC datetime parameter can be used to fetch all records that have changed since the specified point in time. This may include metrics recorded prior to the requestedupdated_at_start
datetime. See Syncing for more detail.
Example Request
curl https://api.getdor.com/v2/location-metrics?datetime_start=2019-01-01T00%3A00%3A00&datetime_end=2019-02-01T00%3A00%3A00&interval=day \
-u TEAM_ID:API_KEY;
Query Parameters
Name | Type | Description |
---|---|---|
limit | integer | Max number of results returned per request. Default 200. |
tag | string | Tag name for filtering locations in a query |
datetime_start | string | The lower boundary (inclusive) of a date range. |
datetime_end | string | The upper boundary (exclusive) of a datetime range. |
interval | string | The interval of time by which to group results. |
updated_at_start | string | Datetime in UTC to query based on the last time data was updated. |
location_ids | array | Location ids for which to filter locations to query |
Response
{
"data": [
{
"datetime_start": "2019-01-01T00:00:00",
"datetime_end": "2019-01-02T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 225,
"validity": "complete",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"sales": {
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"weather": {
"date": "2020-02-12",
"min_temperature_f": 53,
"max_temperature_f": 67,
"probability_precipitation": "0.40",
"summary": "Sunny",
"weather_type": null
},
"location": {
"id": "loc_X51hRSCsIksxdu9b",
"name": "East Hanover"
}
},
{
"datetime_start": "2019-01-01T00:00:00",
"datetime_end": "2019-01-02T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 225,
"validity": "complete",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"sales": {
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"weather": {
"date": "2020-02-12",
"min_temperature_f": 53,
"max_temperature_f": 67,
"probability_precipitation": "0.40",
"summary": "Sunny",
"weather_type": null
},
"location": {
"id": "loc_RlcVuYajBhMUAnuI",
"name": "West Springfield"
}
},
{
"datetime_start": "2019-01-02T00:00:00",
"datetime_end": "2019-01-01T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 225,
"validity": "complete",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"sales": {
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"weather": {
"date": "2020-02-12",
"min_temperature_f": 53,
"max_temperature_f": 67,
"probability_precipitation": "0.40",
"summary": "Sunny",
"weather_type": null
},
"location": {
"id": "loc_X51hRSCsIksxdu9b",
"name": "East Hanover"
}
}
],
"meta": {
"limit": 4,
"next": "https://api.getdor.com/v2/location-metrics?next=3234234234"
}
}
Response Schema
Name | Type | Description |
---|---|---|
data | array | |
interval | string Enum: 15m, hour, day, week, month, year |
The interval of time by which to group results. |
datetime_start | string Local Datetime |
Datetime representing the beginning of the interval. Inclusive. |
datetime_end | string Local Datetime |
Datetime representing the end of the interval. Exclusive. |
count | integer | The total count of foot traffic for the interval |
validity | string Enum: valid, degraded, invalid |
Indicates the validity state of the data. See Data Validity and Completeness. |
completeness | string Enum: complete, incomplete |
Indicates whether the data is complete for the interval. See Data Validity and Completeness |
updated_at | string UTC Datetime |
UTC datetime representing the most recent time this object was updated. |
transactions | integer Nullable |
Number of transactions during the interval |
revenue | string Nullable |
Revenue from transactions in base currency |
conversion_rate | string Nullable |
Transactions / Foot traffic count |
atv | string Nullable |
Average transaction value for the interval |
currency_code | string | ISO 4217 currency code |
updated_at | string UTC Datetime Nullable |
UTC datetime representing the most recent time this object was updated |
date | string Date |
Date that the weather was recorded. |
min_temperature_f | integer Nullable |
Minimum recorded temperature in fahrenheit |
max_temperature_f | integer Nullable |
Maximum recorded temperature in fahrenheit |
probability_precipitation | string Nullable |
Probability that it rained on that date. |
summary | string Nullable |
Short summary of the weather conditions. |
weather_type | string Nullable |
Weather type category. |
id | string | Unique identifier for the Location |
name | string | Name of the Location |
updated_at | string UTC Datetime |
UTC datetime representing the most recent time this object was updated. |
meta | object | Contains pagination metadata for the response. See Pagination. |
limit | integer | The max number of results returned, i.e. the page size. Defaults to 200 for all list endpoints. |
next | string | A URL for retrieving the next page of results |
GET /team-metrics
The Team Metrics endpoint returns data aggregated over all locations belonging to your team or over tag if the tag
query parameter is provided. The results returned from this endpoint can be used to get an overview of all of your locations or to compare subsets of locations using tags.
To retrieve metrics that are aggregated by location, refer to the Location Metrics endpoint.
Returned data is aggregated across locations so that one result is returned for each interval of time. The interval
can be one of: "15m", "hour", "day", "week", "month", "year".
By default, Team Metrics aggregated over all of your locations are returned. You may optionally choose to filter results to only a subset of your locations using the tag
query parameter. For example, if “West Coast” is passed as the tag
parameter and interval
is "day", one result will be returned for each day in the range with data aggregated across all locations included in the “West Coast” tag.
There are two ways to query for results:
- The
datetime_start
(inclusive) anddatetime_end
(exclusive) parameters can be used to query for data recorded within the specified datetime range. Note that these parameters are grouped by local timezone. The `updated_at_start UTC datetime parameter can be used to fetch all records that have changed since the specified point in time. This may include metrics recorded prior to the requested updated_at_start datetime. See Syncing for more detail.
Example Request
curl https://api.getdor.com/v2/team-metrics?datetime_start=2019-01-01T00%3A00%3A00&datetime_end=2019-02-01T00%3A00%3A00&interval=day \
-u TEAM_ID:API_KEY;
Query Parameters
Name | Type | Description |
---|---|---|
datetime_start | string | The lower boundary (inclusive) of a date range. |
datetime_end | string | The upper boundary (exclusive) of a datetime range. |
limit | integer | Max number of results returned per request. |
tag | string | Tag name for filtering locations in a query |
interval | string | The interval of time by which to group results. |
updated_at_start | string | Datetime in UTC to query based on the last time data was updated. |
Response
{
"data": [
{
"datetime_start": "2019-01-01T00:00:00",
"datetime_end": "2019-01-02T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 225,
"validity": "complete",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"sales": {
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-14T13:00:00+00:00"
}
},
{
"datetime_start": "2019-01-02T00:00:00",
"datetime_end": "2019-01-03T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 311,
"validity": "complete",
"updated_at": "2020-02-16T11:25:01+00:00"
},
"sales": {
"transactions": 121,
"revenue": "1198.93",
"conversion_rate": "13.43",
"atv": "9.91",
"currency_code": "USD",
"updated_at": "2020-02-18T22:25:59+00:00"
}
},
{
"datetime_start": "2019-01-03T00:00:00",
"datetime_end": "2019-01-04T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 276,
"validity": "incomplete",
"updated_at": "2020-02-18T19:33:14+00:00"
},
"sales": {
"transactions": 201,
"revenue": "1813.44",
"conversion_rate": "21.31",
"atv": "9.02",
"currency_code": "USD",
"updated_at": "2020-02-18T22:25:11+00:00"
}
}
],
"meta": {
"limit": 200,
"next": "https://api.getdor.com/v2/team-metrics?next=k29dso102lkg2i342"
}
}
Response Schema
Name | Type | Description |
---|---|---|
data | array | |
datetime_start | string Local Datetime |
Datetime representing the beginning of the interval. Inclusive. |
datetime_end | string Local Datetime |
Datetime representing the end of the interval. Exclusive. |
interval | string Enum: 15m, hour, day, week, month, year |
The interval of time by which to group results. |
count | integer | The total count of foot traffic for the interval |
validity | string Enum: valid, degraded, invalid |
Indicates the validity state of the data. See Data Validity and Completeness. |
completeness | string Enum: complete, incomplete |
Indicates whether the data is complete for the interval. See Data Validity and Completeness |
updated_at | string UTC Datetime |
UTC datetime representing the most recent time this object was updated. |
transactions | integer | Number of transactions during the interval |
revenue | string | Revenue from transactions in base currency |
conversion_rate | string | Transactions / Foot traffic count |
atv | string | Average transaction value for the interval |
currency_code | string | ISO 4217 currency code |
updated_at | string UTC Datetime |
UTC datetime representing the most recent time this object was updated |
updated_at | string UTC Datetime |
UTC datetime representing the most recent time this object was updated. |
meta | object | Contains pagination metadata for the response. See Pagination. |
limit | integer | The max number of results returned, i.e. the page size. Defaults to 200 for all list endpoints. |
next | string | A URL for retrieving the next page of results |
Schemas
Address
Information about a physical address. Used in shipping and for determining the time zone of a Location.
The Address Object
{
"name": "Jane's Clothing Shop",
"attn": "Jane Smith",
"address_1": "123 Main st.",
"address_2": "Unit C",
"locality": "Los Angeles",
"administrative_area": "CA",
"postal_code": "94102",
"country_code": "US",
"timezone_name": "America/Los_Angeles"
}
Properties
Name | Type | Description |
---|---|---|
name | string | A name associated with the address. Usually this is the name of the Location or your company |
attn | string | The ATTN field for shipments |
address_1 | string | Address line 1 |
address_2 | string | Address line 2 |
locality | string | City or other regional identifier based on country |
administrative_area | string | State, Province, or local region code based on country |
postal_code | string | Zip code or regional postal code |
country_code | string | Two digit ISO 3166-1 country code |
timezone_name | string | Descriptive time zone name, i.e. America/Chicago |
Foot Traffic
Contains information about foot traffic measured during an interval.
The Foot Traffic Object
{
"count": 225,
"validity": "complete",
"updated_at": "2020-02-14T13:00:00+00:00"
}
Properties
Name | Type | Description |
---|---|---|
count | integer | The total count of foot traffic for the interval |
validity | string | Indicates the validity state of the data. See Data Validity and Completeness. |
completeness | string | Indicates whether the data is complete for the interval. See Data Validity and Completeness |
updated_at | string | UTC datetime representing the most recent time this object was updated. |
Location
Represents a physical location where foot traffic is being measured such as a store or office building.
The Location Object
{
"id": "loc_X51hRSCsIksxdu9b",
"name": "East Hanover",
"phone_number": "1(555)324-6332",
"address": {
"name": "Jane's Clothing Shop",
"attn": "Jane Smith",
"address_1": "123 Main st.",
"address_2": "Unit C",
"locality": "Los Angeles",
"administrative_area": "CA",
"postal_code": "94102",
"country_code": "US",
"timezone_name": "America/Los_Angeles"
},
"shipping_address": {
"name": "Jane's Clothing Shop",
"attn": "Jane Smith",
"address_1": "PO Box 9601",
"address_2": "",
"locality": "Los Angeles",
"administrative_area": "CA",
"postal_code": "94102",
"country_code": "US",
"timezone_name": "America/Los_Angeles"
},
"updated_at": "2020-02-21T18:00:00T+00:00",
"created_at": "2020-02-14T12:00:00T+00:00"
}
Properties
Name | Type | Description |
---|---|---|
id | string | Unique identifier for this location assigned by Dor |
name | string | A human readable name of the location. |
phone_number | string | Location phone number |
address | object | Information about a physical address. Used in shipping and for determining the time zone of a Location. |
shipping_address | object | Information about a physical address. Used in shipping and for determining the time zone of a Location. |
updated_at | string | UTC datetime representing the most recent time this object was updated. |
created_at | string | UTC datetime representing when this object was created. |
Location Metric
Foot traffic, Sales, and Weather data aggregated per Location over an interval.
The Location Metric Object
{
"interval": "hour",
"datetime_start": "2020-02-14T13:00:00",
"datetime_end": "2020-02-14T14:00:00",
"foot_traffic": {
"count": 225,
"validity": "complete",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"sales": {
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"weather": {
"date": "2020-02-12",
"min_temperature_f": 53,
"max_temperature_f": 67,
"probability_precipitation": "0.40",
"summary": "Sunny",
"weather_type": null
},
"location": {
"id": "loc_l1j1lk3jj4",
"name": "Jane's Clothing Store"
},
"updated_at": "2020-02-14T12:00:00T+00:00"
}
Properties
Name | Type | Description |
---|---|---|
interval | string | The interval of time by which to group results. |
datetime_start | string | Datetime representing the beginning of the interval. Inclusive. |
datetime_end | string | Datetime representing the end of the interval. Exclusive. |
foot_traffic | object | Contains information about foot traffic measured during an interval. |
sales | object | Information about sales during an interval. |
weather | object | Weather information for a date at a Location. |
location | object | Shortened version of a Location object |
updated_at | string | UTC datetime representing the most recent time this object was updated. |
Meta
Contains pagination metadata for the response. See Pagination.
The Meta Object
{
"limit": 200,
"next": "https://api.getdor.com/v2/locations?next=laf32lkjfl2kjf"
}
Properties
Name | Type | Description |
---|---|---|
limit | integer | The max number of results returned, i.e. the page size. Defaults to 200 for all list endpoints. |
next | string,null | A URL for retrieving the next page of results |
Sales
Information about sales during an interval.
The Sales Object
{
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-14T13:00:00+00:00"
}
Properties
Name | Type | Description |
---|---|---|
transactions | integer,null | Number of transactions during the interval |
revenue | string,null | Revenue from transactions in base currency |
conversion_rate | string,null | Transactions / Foot traffic count |
atv | string,null | Average transaction value for the interval |
currency_code | string | ISO 4217 currency code |
updated_at | string,null | UTC datetime representing the most recent time this object was updated |
Tag
Resource for describing a grouping of locations. Returns location id and name for all locations associated to the tag.
Tags can only be created in the Tag Manager section of the Dor dashboard.
The Tag Object
{
"name": "West Coast",
"location_count": 2,
"locations": [
{
"id": "loc_1lkj414l2j2",
"name": "West Hanover"
},
{
"id": "loc_12lkj3hhlh3",
"name": "Southside"
}
],
"updated_at": "2020-02-14T12:09:21T+00:00"
}
Properties
Name | Type | Description |
---|---|---|
name | string | Name of tag to describe grouping of locations |
location_count | integer | Number of associated locations |
updated_at | string,null | UTC datetime representing the most recent time this object was updated. |
locations | array | Array of associated locations |
Team Metric
Contains data aggregated over all locations belonging to your team or over a tag if the tag
query parameter is provided.
The Team Metric Object
{
"datetime_start": "2020-02-14T13:00:00",
"interval": "hour",
"datetime_end": "2020-02-14T14:00:00",
"foot_traffic": {
"count": 225,
"validity": "complete",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"sales": {
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-14T13:00:00+00:00"
},
"updated_at": "2020-02-14T22:09:02+00:00"
}
Properties
Name | Type | Description |
---|---|---|
datetime_start | string | Datetime representing the beginning of the interval. Inclusive. |
datetime_end | string | Datetime representing the end of the interval. Exclusive. |
interval | string | The interval of time by which to group results. |
foot_traffic | object | Contains information about foot traffic measured during an interval. |
sales | object | Information about sales during an interval. |
updated_at | string | UTC datetime representing the most recent time this object was updated. |
Weather
Weather information for a date at a Location.
The Weather Object
{
"date": "2020-02-12",
"min_temperature_f": 53,
"max_temperature_f": 67,
"probability_precipitation": "0.40",
"summary": "Sunny",
"weather_type": null
}
Properties
Name | Type | Description |
---|---|---|
date | string | Date that the weather was recorded. |
min_temperature_f | integer,null | Minimum recorded temperature in fahrenheit |
max_temperature_f | integer,null | Maximum recorded temperature in fahrenheit |
probability_precipitation | string,null | Probability that it rained on that date. |
summary | string,null | Short summary of the weather conditions. |
weather_type | string,null | Weather type category. |
Quick Start
Example Patterns
Get Data for a Single Location
This example shows the workflow necessary to make a basic request to retrieve data for a single Location.
Step 1
If location_id
is not known, make a GET request to /v2/locations
to get a list of all locations. Search through the list to find the id
key of the desired location.
Step 2
Make a GET request to /location-metrics
with following query parameters
Query Parameters
Parameter | Value |
---|---|
location_ids | loc_12a9df3asf2f |
datetime_start | 2020-01-01T00:00:00 |
datetime_end | 2020-04-01T00:00:00 |
interval | day |
Example Request
curl https://api.getdor.com/v2/location-metrics?location_ids[]=loc_12a9df3asf2f&datetime_start=2020-01-01T00%3A00%3A00&datetime_end=2020-04-01T00%3A00%3A00&interval=day \
-u TEAM_ID:API_KEY
Response
{
"data": [
{
"interval": "day",
"datetime_start": "2020-01-01T00:00:00+00:00",
"datetime_end": "2020-02-01T00:00:00+00:00",
"location": {
"id": "loc_12a9df3asf2f",
"name": "A09 - Sentry Blvd"
},
"foot_traffic": {
"count": 23,
"validity": "complete",
"updated_at": "2020-02-01T02:13:44+00:00"
},
"sales": {
"transactions": 6,
"revenue": "323.21",
"conversion_rate": "0.26",
"atv": "53.87",
"updated_at": "2020-02-01T01:44:12+00:00"
},
"weather": {
"date": "2020-01-01",
"min_temperature_f": 43,
"max_temperature_f": 59,
"probability_precipitation": "0.18",
"summary": "Slight chance rain",
"weather_type": "rain showers"
}
},
{...}
],
"meta": {
"limit": 200,
"next": null
}
}
Sync hourly data on a schedule
In this example we'll step through the process of setting up a scheduled syncing integration with the API. This is a common workflow for users that want to keep an internal system or database in sync with the most up to date Dor data available for their account. This example focuses on hourly data but would work similarly for other timescales.
The Initial Sync
The first task in setting up a scheduled sync system is to get your local database up to date with the data available through Dor's API. The steps below focus on Location Metrics but would work similarly for Team Metrics as well.
Step 1
Make a GET request to /location-metrics
with the updated_at_start
query parameter set to the earliest date any of your locations began measuring foot traffic or an arbitrary time in the past before that date. This will allow you to sync all existing data.
Example Request
curl https://api.getdor.com/v2/location-metrics?updated_at_start=2016-01-01T00%3A00%3A00&interval=day \
-u TEAM_ID:API_KEY
Response
{
"data": [
{
"interval": "day",
"datetime_start": "2020-01-01T00:00:00+00:00",
"datetime_end": "2020-02-01T00:00:00+00:00",
"location": {
"id": "loc_12a9df3asf2f",
"name": "A09 - Sentry Blvd"
},
"foot_traffic": {
"count": 23,
"validity": "complete",
"updated_at": "2020-02-01T02:13:44+00:00"
},
"sales": {
"transactions": 6,
"revenue": "323.21",
"conversion_rate": "0.26",
"atv": "53.87",
"updated_at": "2020-02-01T01:44:12+00:00"
},
"weather": {
"date": "2020-01-01",
"min_temperature_f": 43,
"max_temperature_f": 59,
"probability_precipitation": "0.18",
"summary": "Slight chance rain",
"weather_type": "rain showers"
}
},
{...}
],
"meta": {
"limit": 200,
"next": "https://api.getdor.com/v2/location-metrics?next=bmV4dD17dXBkYXRlZF9hdDoyMDIwLTAyLTIyIDAwOjAxOjEyfQ=="
}
}
Step 2
Continue to make GET requests using the next
url provided in the meta
response object as long as it is present. When a response is returned with a null next
url, syncing is now up to date with the most recent data in your account.
Example Request 2
curl https://api.getdor.com/v2/location-metrics?next=bmV4dD17dXBkYXRlZF9hdDoyMDIwLTAyLTIyIDAwOjAxOjEyfQ== \
-u TEAM_ID:API_KEY
Scheduled Syncs
After your internal database has caught up to the data available through Dor's API, the next step will be to sync regularly with Dor's API. Common syncing frequencies are hourly, daily, or weekly.
Keep in mind that Dor sensor data is not available in real time. Sensors send their data to the server on a schedule determined by their configured update frequency. Unless your devices have been set to a custom update frequency, update frequency is set to once per hour. If no foot traffic events are detected (over night for example) the sensor will check in with the server once every four hours to conserve battery life.
Please see Syncing Data for more information.
Step 1
Make a GET request to /location-metrics
with the updated_at_start
query parameter set to the timestamp of the last time you synced data for the updated_at_start
parameter. A common way to do this is to save an internal updated_at
timestamp along with the data returned from the API. The most recent updated_at
timestamp can be used for the updated_at_start
parameter.
Step 2
Continue to make GET requests using the next
url provided in the meta
response object as long as it is present. When a response is returned with a null next
url, syncing is now up to date with the most recent data in your account.
Comparing Metrics Across Tags
This example will show how to compare metrics between two different tags. Tags allow you to simplify the management of your locations by categorizing them into logical groupings that can be queried for easily.
In this example, we have two tags already set up: "West Coast" and "East Coast". Visit your Dor dashboard to create or edit tags.
In order to compare the two tags we'll need to make two requests to the /team-metrics
endpoint. This uses day interval but would work with any timescale.
Step 1
Make a GET request to /team-metrics
with the following parameters
Query Parameters
Parameter | Value |
---|---|
tag | West Coast |
datetime_start | 2019-05-01T00:00:00 |
datetime_end | 2019-06-01T00:00:00 |
interval | day |
Example Request 1
curl https://api.getdor.com/v2/team-metrics?tag=West%20Coast&datetime_start=2020-01-01T00%3A00%3A00&datetime_end=2020-02-01T00%3A00%3A00&interval=day \
-u TEAM_ID:API_KEY
Response
{
"data": [
{
"datetime_start": "2020-02-01T00:00:00",
"datetime_end": "2020-02-02T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 225,
"validity": "complete",
"updated_at": "2020-02-12T13:00:00T+00:00"
},
"sales": {
"transactions": 92,
"revenue": "1200.31",
"conversion_rate": "13.43",
"atv": "13.05",
"currency_code": "USD",
"updated_at": "2020-02-02T15:03:01+00:00"
}
},
{...},
{...}
],
"meta": {
"limit": 100,
"next": null
}
}
Step 2
Make the same GET request to /team-metrics
for the "East Coast" tag.
Query Parameters
Parameter | Value |
---|---|
tag | East Coast |
datetime_start | 2019-05-01T00:00:00 |
datetime_end | 2019-06-01T00:00:00 |
interval | day |
Example Request 2
curl https://api.getdor.com/v2/team-metrics?tag=East%20Coast&datetime_start=2020-01-01T00%3A00%3A00&datetime_end=2020-02-01T00%3A00%3A00&interval=day \
-u TEAM_ID:API_KEY
Response
{
"data": [
{
"datetime_start": "2020-02-01T00:00:00",
"datetime_end": "2020-02-02T00:00:00",
"interval": "day",
"foot_traffic": {
"count": 476,
"validity": "complete",
"updated_at": "2020-02-02T02:10:08+00:00"
},
"sales": {
"transactions": 46,
"revenue": "896.31",
"conversion_rate": "10.34",
"atv": "19.49",
"currency_code": "USD",
"updated_at": "2020-02-02T15:03:01+00:00"
}
},
{...},
{...}
],
"meta": {
"limit": 100,
"next": null
}
}
Step 3
Compare the two results.
Comparing Locations YoY
This example will show how to compare metrics between YoY for the month of January at a single location.
In order to compare the two tags we'll need to make two requests to the /location-metrics
endpoint. This uses month interval
but would work the same with any timescale.
Step 1
Make a GET request to /location-metrics
with the following parameters to get data for 2019.
Query Parameters
Parameter | Value |
---|---|
location_ids | [ 'loc_j29f923j22' ] |
datetime_start | 2019-01-01T00:00:00 |
datetime_end | 2019-02-01T00:00:00 |
interval | month |
Example Request 1
curl https://api.getdor.com/v2/location-metrics?location_ids[]=loc_j29f923j22&datetime_start=2019-01-01T00%3A00%3A00&datetime_end=2019-02-01T00%3A00%3A00&interval=month \
-u TEAM_ID:API_KEY
Response
{
"data": [
{
"interval": "month",
"datetime_start": "2019-01-01T00:00:00",
"datetime_end": "2019-02-01T00:00:00",
"location": {
"id": "loc_12a9df3asf2f",
"name": "A09 - Sentry Blvd"
},
"foot_traffic": {
"count": 23469,
"validity": "complete",
"updated_at": "2019-02-01T02:13:44+00:00"
},
"sales": {
"transactions": 1258,
"revenue": "69885.21",
"conversion_rate": "0.05",
"atv": "55.55",
"updated_at": "2019-02-01T02:13:44+00:00"
}
}
],
"meta": {
"limit": 200,
"next": null
}
}
Step 2
Make a GET request to /location-metrics
with the following parameters to get data for 2020.
Query Parameters
Parameter | Value |
---|---|
location_ids | [ 'loc_j29f923j22' ] |
datetime_start | 2020-01-01T00:00:00 |
datetime_end | 2020-02-01T00:00:00 |
interval | month |
Example Request 2
curl https://api.getdor.com/v2/location-metrics?location_ids[]=loc_j29f923j22&datetime_start=2020-01-01T00%3A00%3A00&datetime_end=2020-02-01T00%3A00%3A00&interval=month \
-u TEAM_ID:API_KEY
Response
{
"data": [
{
"interval": "month",
"datetime_start": "2020-01-01T00:00:00",
"datetime_end": "2020-02-01T00:00:00",
"location": {
"id": "loc_12a9df3asf2f",
"name": "A09 - Sentry Blvd"
},
"foot_traffic": {
"count": 45977,
"validity": "complete",
"updated_at": "2020-02-02T04:56:32+00:00"
},
"sales": {
"transactions": 3844,
"revenue": "133885.21",
"conversion_rate": "0.08",
"atv": "34.83",
"updated_at": "2020-02-02T02:15:55+00:00"
}
}
],
"meta": {
"limit": 200,
"next": null
}
}
Step 3
Compare the two results.