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.

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

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

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

{
  "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.

{
    "code": "400",
    "type": "INVALID_REQUEST_ERROR",
    "message": "The request was invalid.",
    "invalid": [{
        "name": "limit",
        "reason": "Limit must be less than 500."
    }]
}

Pagination

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

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:

 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:

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.

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.

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.

curl https://api.getdor.com/v2/locations?tag=West%20Coast \ 
 -u TEAM_ID:API_KEY;

{
  "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
  }
}

GET /locations/{location_id}

Returns a Location resource given a location_id.

curl https://api.getdor.com/v2/locations/loc_1nm2123 \ 
 -u TEAM_ID:API_KEY;

{
  "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": {}
}

Tags

GET /tags

Returns a list of Tags belonging to a user's Team.

curl https://api.getdor.com/v2/tags \ 
 -u TEAM_ID:API_KEY;

{
  "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
  }
}

GET /tags/{tag}

Returns a single Tag and an array of Locations associated to the Tag.

curl https://api.getdor.com/v2/tags/West%20Coast \ 
 -u TEAM_ID:API_KEY;

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

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;

{
  "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"
  }
}

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

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;

{
  "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"
  }
}

Schemas

Address

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

{
  "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"
}

Foot Traffic

Contains information about foot traffic measured during an interval.

{
  "count": 225,
  "validity": "complete",
  "updated_at": "2020-02-14T13:00:00+00:00"
}

Location

Represents a physical location where foot traffic is being measured such as a store or office building.

{
  "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"
}

Location Metric

Foot traffic, Sales, and Weather data aggregated per Location over an interval.

{
  "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"
}

Meta

Contains pagination metadata for the response. See Pagination.

{
  "limit": 200,
  "next": "https://api.getdor.com/v2/locations?next=laf32lkjfl2kjf"
}

Sales

Information about sales during an interval.

{
  "transactions": 92,
  "revenue": "1200.31",
  "conversion_rate": "13.43",
  "atv": "13.05",
  "currency_code": "USD",
  "updated_at": "2020-02-14T13:00:00+00:00"
}

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.

{
  "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"
}

Team Metric

Contains data aggregated over all locations belonging to your team or over a tag if the tag query parameter is provided.

{
  "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"
}

Weather

Weather information for a date at a Location.

{
  "date": "2020-02-12",
  "min_temperature_f": 53,
  "max_temperature_f": 67,
  "probability_precipitation": "0.40",
  "summary": "Sunny",
  "weather_type": null
}

Quick Start

Example Patterns