Standard Locations

The Standard Locations API allows you to programmatically access our metrics for standard locations: Places and Neighborhoods. This API is currently in BETA. If you're interested in testing it, please contact us here.

Quick Start

To get started with the Query API, you'll need an API token. If you don't have it, please contact us here.

Test the API by running the following command.

curl -X POST https://unacastapis.com/v3/catalog/listRecords \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data_reference_name": "ml_visitation.places",
  "filters": [
    {
      "fieldName": "placekey",
      "operator": "==",
      "value": "223-223@5q6-7pq-dd9"
    }
  ]
}'

Data Reference

The Data Reference endpoints allow you to retrieve metadata about the Datasets you have access to.

There are two ways of fetching the Data Reference. One is to get the full list, the other is to get only a specific one you already know the name of.

Get Full List

To get the full list of Data References, use the following endpoint:

curl -X POST https://unacastapis.com/v3/catalog/listDataReferences \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Get Specific One

To get a specific Data Reference, use the following endpoint:

curl -X POST https://unacastapis.com/v3/catalog/getDataReference \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "ml_visitation.places"
}'

Retrieving Data

curl -X POST https://unacastapis.com/v3/catalog/listRecords \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data_reference_name": "ml_visitation.places"
}'

Field Selection

You can select specific fields to include in the response. Here are some examples:

Field Selection Example

Get specific fields only

curl -X POST https://unacastapis.com/v3/catalog/listRecords \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data_reference_name": "ml_visitation.places",
  "fields": [
    {
      "name": "placekey"
    },
    {
      "name": "location_name"
    },
    {
      "name": "street_address"
    }
  ]
}'

Finding Field Values

Use the searchFieldValues endpoint to find distinct values for a field:

curl -X POST https://unacastapis.com/v3/catalog/searchFieldValues \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data_reference_name": "ml_visitation.places",
  "field": {
    "name": "city"
  },
  "term": "Boul"
}'

Filters

You can use filters to narrow down your data. Here are some examples:

Date Filter Example

Filter records by date

curl -X POST https://unacastapis.com/v3/catalog/listRecords \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data_reference_name": "ml_visitation.foot_traffic_month",
  "filters": [
    {
      "fieldName": "observation_start_date",
      "operator": ">=",
      "value": "2023-01-01"
    }
  ]
}'

Location Filter Example

Filter records by state

curl -X POST https://unacastapis.com/v3/catalog/listRecords \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data_reference_name": "ml_visitation.places",
  "filters": [
    {
      "fieldName": "region",
      "operator": "==",
      "value": "NY"
    }
  ]
}'

Bounding Box Example

Filter records by geographic area

curl -X POST https://unacastapis.com/v3/catalog/listRecords \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data_reference_name": "ml_visitation.places",
  "trimToPeriodOfExistence": 0,
  "boundingBox": {
    "minLng": -105.3014,
    "minLat": 39.964,
    "maxLng": -105.178,
    "maxLat": 40.078
  }
}'