Navigation

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 the foot traffic data that is returned, we provide the validity key within the Foot Traffic resource. This value gives you more information about the state of your data so that you can make informed choices about how to use it. You may decide to throw out invalid or degraded data during statistical analysis, for example.

The validity key can be in one of four possible states: complete, incomplete, degraded, or invalid. The vast majority of your data will be complete.

Validity State Definitions

Value Description
complete All sensors associated to the location have purged all their data for the queried timeframe to the server. No data gap or other data degradation is detected.
incomplete One or more sensors associated to the location have not fully purged their data for the queried timeframe to the server. This indicates that metrics for this queried timeframe will likely update in the future.
degraded Due to an unrecoverable sensor issue, it is possible that some metrics for this queried timeframe may be invalid or unmeasured.
invalid Due to an unrecoverable sensor issue, metrics for this queried timeframe are invalid or unmeasured.

Endpoints

Locations

GET /locations

List 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

NameTypeDescription
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

address object

Information about a physical address. Used in shipping and for determining the time zone of a Location.

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

shipping_address object

Information about a physical address. Used in shipping and for determining the time zone of a Location.

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}

Location Detail

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

NameTypeDescription
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

address object

Information about a physical address. Used in shipping and for determining the time zone of a Location.

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

shipping_address object

Information about a physical address. Used in shipping and for determining the time zone of a Location.

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

List 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

NameTypeDescription
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}

Tag Detail

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

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

locations array

Array of associated locations

id string
name string
meta object

Metrics

GET /location-metrics

List 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) and datetime_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/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

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

foot_traffic object

Contains information about foot traffic measured during an interval.

count integer

The total count of foot traffic for the interval

validity string
Enum: complete, incomplete, degraded, invalid

Indicates completeness and validity of the data. See Data Validity.

updated_at string
UTC Datetime

UTC datetime representing the most recent time this object was updated.

sales object

Information about sales during an interval.

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

weather object

Weather information for a date at a Location.

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.

location object

Shortened version of a Location object

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

List 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) and datetime_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

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

foot_traffic object

Contains information about foot traffic measured during an interval.

count integer

The total count of foot traffic for the interval

validity string
Enum: complete, incomplete, degraded, invalid

Indicates completeness and validity of the data. See Data Validity.

updated_at string
UTC Datetime

UTC datetime representing the most recent time this object was updated.

sales object

Information about sales during an interval.

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 completeness and validity of the data. See Data Validity.
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

ParameterValue
location_idsloc_12a9df3asf2f
datetime_start2020-01-01T00:00:00
datetime_end2020-04-01T00:00:00
intervalday

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

ParameterValue
tagWest Coast
datetime_start2019-05-01T00:00:00
datetime_end2019-06-01T00:00:00
intervalday

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

ParameterValue
tagEast Coast
datetime_start2019-05-01T00:00:00
datetime_end2019-06-01T00:00:00
intervalday

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

ParameterValue
location_ids[ 'loc_j29f923j22' ]
datetime_start2019-01-01T00:00:00
datetime_end2019-02-01T00:00:00
intervalmonth

 

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

ParameterValue
location_ids[ 'loc_j29f923j22' ]
datetime_start2020-01-01T00:00:00
datetime_end2020-02-01T00:00:00
intervalmonth

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.