Data is usually organized around one or more geographies. A geography can be a region, such as a state, county, metropolitan area, city, or even a block group. A geography can also be a custom area, such as a radius search around a specific location, a drive time isochrone around an address, a specific list of regions to be treated as one whole region, or the regions covered by an economic development organization (EDO).

Most geographies are described using a simple syntax of type:geography. For example, a geography could be described as country:united-states or city:denver-co.

Types of Geographies

The following table describes the types of geography supported by the API. Most are self-explanatory; however, some require explanation:

A complete list of geographies can be located at [URL to be determined].

Using Geographies

Geographies are used in both the request and the response buffers. In the request buffer, the geographies are primarily shown in the criteria section. Geographies can also appear in the scope section, which is discussed later.

var request = {
  "resultset": {
    "data": {
      ... 
    },
    "criteria": {
      "geography": "county:chittenden-county-vt"
    }
  },
  "options": {
    ... 
  }
};

In the response buffer, the geographies are primarily shown before each data section, indicating which geography the data is from.

var response = {
  "resultset": {
    "geography": "county:chittenden-county-vt",
    "data": [
      ... 
    ]
  },
  "status": {
    ... 
  }
};

Geographic Contexts

When multiple datapoints are returned by the API, it is possible that there may be a change in geographic context. Geographic context refers to the specific geography for a specific set of datapoints, which may be different that the original geography. Changes in geographic context are fairly common due to the nature of the data. Many data sources are not published for all geographic regions.

For example, a request could be made for demographic data for a county, plus the corresponding state tax ranks. The geographic context of the demographic data will be the county, but the geographic context of the state tax ranks will be the state.

In another example, a request could be made for demographic data for a county, plus the corresponding Occupation Employment Statistics (OES) data. The geographic context for the OES data would switch to metropolitan areas since the OES data is not published at the county level.

Geographic contexts can also be changed as part of the API request. For example, it is possible to request datapoints at the city level; however, point-level data, such as neighboring airports, could be returned for a 100-mile radius around the population centroid for the city. This can provide a more useful view of the data since airports serve a wider area than just a single city.

Examples of changing geographic context are shown in the upcoming sections of the documentation. Geographic context should always be considered along with datapoints since this can significantly change the meaning of the datapoint.