There are two approaches to filtering data returned from the API – criteria and scope:

• Criteria is used to select certain geographies to be returned by the API.
• Scope limits the data returned for those geographies, such as determining the time periods for datapoints, limiting collections to certain items, or changing the geographic context of a datapoint or collection.

Criteria and scope are very similar; however, they must be treated separately to handle advanced scenarios. For example, criteria can determine that data should be returned for a specific city; however, airports can be returned beyond the scope of the city, such as a 100-mile radius. In a more complex example, criteria can be used to return all cities with a minimum population and a minimum number of establishments with a specific industry NAICS code; however, for each of those geographies, scope can be used to return datapoints on a much wider set of industry NAICS codes.

Geographies

Criteria for a single geography is accomplishing using the geography keyword. For example, a request could be made for the population of the city of Burlington, VT as follows: 

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ]
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
};

var response = {
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "periods": ["2017"],
        "source": "acs5",
        "values": [42453]
      }
    ]
  }
};

 

Filtering for multiple geographies is accomplished using the geographies keyword. For example, a request could be made for the population of the cities of Burlington, VT and South Burlington, VT as follows:

 

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ]
  },
  "criteria": {
    "geographies": ["city:burlington-vt", "city:south-burlington-vt"]
  }
};

var response = {
  "resultset": {
    "geographies": [
      {
        "geography": "city:burlington-vt",
        "data": [
          {
            "datapoint": "dem.acs.pop.total.val",
            "periods": ["2017"],
            "source": "acs5",
            "values": [42453]
          }
        ]
      },
      {
        "geography": "city:south-burlington-vt",
        "data": [
          {
            "datapoint": "dem.acs.pop.total.val",
            "periods": ["2017"],
            "source": "acs5",
            "values": [18773]
          }
        ]
      }
    ]
  }
};

 

Requesting Geographies by Address

It is possible to request a geography using a complete or partial address.  The API will determine the specific latitude and longitude for the address, and will return data for the specific region type identified in the request.  For example, if the requested region type is "county", data will be returned for the county containing the specific geographic point.

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ]
  },
  "criteria": {
    "geography": {
      "address": "123 Main Street, Burlington, VT 05401",
      "regionType": "city"
    }
  }
};

var response = {
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "period": "2018",
        "source": "acs5",
        "value": 42513
      }
    ]
  }
};

 

Requesting Geographies by Latitude/Longitude

It is possible to request a geography using a latitude and longitude coordinates.  The API will return data for the specific region type identified in the request.  For example, if the requested region type is "county", data will be returned for the county containing the specific geographic point.

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ]
  },
  "criteria": {
    "geography": {
      "latlon": "44.47588, -73.21400",
      "regionType": "city"
    }
  }
};

var response = {
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "period": "2018",
        "source": "acs5",
        "value": 42513
      }
    ]
  }
};

 

Custom Geographies

Some requests may require custom geographies, such as radius searches, drive time isochrones, drive distance isochrones, custom geometries in GeoJSON, or ad-hoc geographies combined from multiple geographies. Custom geographies are not referenced by name but are instead identified by their search characteristics.

When declaring custom geographies, it is important to identify the type of region being requested.  For example, a radius of 100 miles could be used to qualify regions as small as a block group and as large as a county.  In the examples below, the region type will be declared for each custom geography.

When declaring custom geographies, it is also important to identify whether the qualified regions should be listed individually or summarized into a single result. For example, if a radius search qualified 20 block groups, the datapoints in those block groups can be returned individually or they can be aggregated into a single result for the radius.  In the examples below, the results are always shown in a list.  See the "Summary" section to see how the results can be summarized.

When custom geographies are applied to point-level data, the results will simply include all point-level data within the outer perimeter of the custom geography.

Custom geographies can be used in most places where named geographies are used.

Radius Search

A radius search is a circle around a specific point, such as a latitude/longitude or an address.  The circle is defined using the number of miles (including fractions of miles) from the center.

The following example shows airports in a 25-mile radius around the population centroid of Burlington, VT.

 

var request = {
  "data": {
    "collections": [
      {
        "collection": "trn.airport",
        "datapoints": [
          "trn.airport.name"
        ]
      }
    ]
  },
  "criteria": {
    "geography": {
      "radius": 25,
      "address": "123 Main Street, Burlington, VT, 05401"
    }
  }
};

var response = {
  "resultset": {
    "geography": "custom:custom01",
    "data": [
      {
        "collection": "trn.airport",
        "items": [
          {
            "item": "BTV",
            "period": "2017",
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Burlington Intl"
              }
            ]
          },
          {
            "item": "PBG",
            "period": "2017",
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Plattsburgh Intl"
              }
            ]
          }
        ]
      }
    ]
  }
};

 

Drive Time Search

A drive time search is an isochrone (an irregular shape representing driving time) around a specific point, such as a latitude/longitude or an address.  The isochrone is defined using the number minutes from the centroid.

The following example shows a 60-minute drive time isochrone around the population centroid of Burlington, VT.  Due to Lake Champlain, the Plattsburgh International Airport shown in the radius search example above no longer is returned.

 

var request = {
  "data": {
    "collections": [
      {
        "collection": "trn.airport",
        "datapoints": [
          "trn.airport.name"
        ]
      }
    ]
  },
  "criteria": {
    "geography": {
      "drivetime": 60,
      "address": "123 Main Street, Burlington, VT, 05401"
    }
  }
};

var response = {
  "resultset": {
    "geography": "custom:custom01",
    "data": [
      {
        "collection": "trn.airport",
        "items": [
          {
            "item": "BTV",
            "period": "2017",
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Burlington Intl"
              }
            ]
          }
        ]
      }
    ]
  }
};

 

Drive Distance Search

A drive distance search is an isochrone (an irregular shape representing driving distance) around a specific point, such as a latitude/longitude or an address. The isochrone is defined using the number miles from the centroid.

The following example shows a 50-mile drive distance isochrone around the population centroid of Burlington, VT.

 

var request = {
  "data": {
    "collections": [
      {
        "collection": "trn.airport",
        "datapoints": [
          "trn.airport.name"
        ]
      }
    ]
  },
  "criteria": {
    "geography": {
      "drivedistance": 50,
      "address": "123 Main Street, Burlington, VT, 05401"
    }
  }
};

var response = {
  "resultset": {
    "geography": "custom:custom01",
    "data": [
      {
        "collection": "trn.airport",
        "items": [
          {
            "item": "BTV",
            "periods": ["2017"],
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Burlington Intl"
              }
            ]
          }
        ]
      }
    ]
  }
};

  

GeoJSON Object

GeoJSON is an industry-standard language for describing custom geographies. GeoJSON allows a user to describe a custom neighborhood or any other geographic perimeter for a search.

The following example shows user-provided geoJSON object.  Note that geoJSON can be provide with just the "geometry" section as shown below, or also the more comprehensive "feature collection" section.

var request = {
  "data": {
    "collections": [
      {
        "collection": "trn.airport",
        "datapoints": [
          "trn.airport.name"
        ]
      }
    ]
  },
  "criteria": {
    "geography": {
      "geojson": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.27091217041016, 44.4299798500283],
            [-73.12551498413086, 44.4299798500283],
            [-73.12551498413086, 44.52086677372567],
            [-73.27091217041016, 44.52086677372567],
            [-73.27091217041016, 44.4299798500283]
          ]
        ]
      }
    }
  }
};

var response = {
  "resultset": {
    "geography": "custom:custom01",
    "data": [
      {
        "collection": "trn.airport",
        "items": [
          {
            "item": "BTV",
            "periods": ["2017"],
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Burlington Intl"
              }
            ]
          }
        ]
      }
    ]
  }
};

 

Combined geographies

A combined geography is an ad-hoc grouping of multiple geographies into a single geography, such as a geography of several counties or states.

The following example shows Chittenden and Franklin counties in Vermont, combined into a single, ad-hoc, geographic region.

 

var request = {
  "data": {
    "collections": [
      {
        "collection": "trn.airport",
        "datapoints": [
          "trn.airport.name"
        ]
      }
    ]
  },
  "criteria": {
    "geography": {
      "combined": ["county:chittenden-county-vt", 
                   "county:franklin-county-vt"]
    }
  }
};

var response = {
  "resultset": {
    "geography": "custom:custom01",
    "data": [
      {
        "collection": "trn.airport",
        "items": [
          {
            "item": "BTV",
            "periods": ["2017"],
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Burlington Intl"
              }
            ]
          }
        ]
      }
    ]
  }
};