Data

Intro

The Datafy API is provided as a convenience and an alternative to receiving a scheduled report directly from the Datafy Team. This API is still in beta, and therefore it is expected to have bugs and you may experience slowdowns or unexpected behavior. Please alert the team if you experience any challenges with data retrieval, syntax, error messaging etc. We will respond to your challenges and address the issue and update the documentation as quickly as possible. Additional datasets, including spending analysis, advertising results, and vehicle geolocation data will be added over time.

Requesting an API Token

Reach out to your CX representative to gain visibility to our API Access Page. Once your access has been confirmed, login using your username at portal.datafy.com and navigate to the API Access page to generate an API token.

The token has the format of <Bearer token-string>, and the entire string including 'Bearer' is required. The token is user-specific and should not be shared. Unauthorized sharing of tokens may result in revoking of access. Tokens will expire every 30 days and a refreshed token can be requested at the api access page within 6 days of the prior token's expiration.

API Request Syntax

The Datafy API is designed to handle both the generation and retrieval of datasets using a unified request format. When submitting a request, you may receive one of two possible responses. If the requested data has been previously processed and is ready for retrieval, the API will return a JSON array of objects. However, if the data has not been requested before, the API will place the request in a queue and process the request once resources become available. In this case, the API will return a status message to inform you that the request has been received and is awaiting processing. In most cases, it only takes a few seconds for the data to get processed and you can resend the same request after a short delay and retrieve the processed data. For requests that cover densely visited POIs and cover large date ranges, the processing may take longer.

The basic request is structured as follows:

The JSON response will include the data at the specified level of detail and will most often include four standard KPIs: Total Trips, Visitor Days, Unique Visitors, and Avg Trip Length. To ensure both internal and external privacy guidelines, filtering will occur to prevent analysis of behavior patterns of small group of people at granular levels of detail. Additionally, weighted averaging occurs differently depending on the requested level of detail. As a result of these two elements, the overall aggregate (no level of detail specified) will vary from the results of summing a value across a more granular level of detail. In most cases the variance is in the low single digit percentage range, but may increase at very high levels of granularity due to filtering.

Multiple Destinations

For most users, this parameter is not required. If you do have access to multiple destinations, you can get a list of authorized destination names from the options endpoint.

If a required destination name is missing from the authorized list, please contact us.

Levels

This parameter is an array of strings that determines the level of detail of the data. The order is not important and multiple levels of detail can be included in the same request, such as breaking down the data by State and Year (see example below). Other common use cases might include requesting Cluster and Month, DMA and Month, Cluster and MSA, etc. You can get a list of available levels from the options endpoint. If you have access to multiple destinations, level availability may vary across destinations.

Filters

This parameter is a nested array of objects that determines how the data is filtered. The request must include a level which will indicate the type of filter that is being applied, and an array of 'values' that specifies which elements of that level should be included. The order is not important. You can get the available items from the options endpoint.

The following example will return overall KPIs for visitors from the state of California and Arizona

To return data for visitors from the states of California and Arizona broken down by each state, the levels and filters should be used simultaneously as follows:

There are special filters available called range filters for dates and distance in miles. The levels available are "Start Date", "End Date", "Minimum Distance", and "Maximum Distance". Order is not important, and multiple filters can be included within the same request to, for example, filter visitors that traveled at least 50 miles, but no more than 500.

Limits

This parameter is a nested array of objects. The primary use case of limits is to reduce the number of rows returned when the requested level of detail will return hundreds, if not hundreds of thousands of rows. In each item, specify the level and the number of items to return. The api will perform the logic necessary to return the top rows for the specified level.

The following example will return data for the top 100 Cities:

You can use this parameter without a matching level in the levels array, but this is not a common use case. The result is to filter out visitors that are not in the top items from that level.