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

Some data may require geographic filtering that is different from the primary geography. For example, a request could be made for the population of the city of Burlington, VT, along with all commercial airports in the Burlington VT Metro Area. This request requires that the geographic scope for the airports be different than the primary criteria of the city of Burlington.

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ],
    "collections": [
      {
        "collection": "trn.airport",
        "datapoints": [
          "trn.airport.name"
        ],
        "scope": {
          "geography": "cbsa:burlington-south-burlington-vt-metro-area"
        }
      }
    ]
  },
  "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]
      },
      {
        "collection": "trn.airport",
        "geography": "cbsa:burlington-south-burlington-vt-metro-area",
        "items": [
          {
            "item": "BTV",
            "periods": ["2017"],
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Burlington Intl"
              }
            ]
          }
        ]
      }
    ]
  }
};

Time Periods

Data is often available for multiple time periods, usually expressed in years. By default, data will be returned for the most recent time period; however, it is possible to request different time periods or more than one time period. This is done using the period filter. For example, a request could be made for the population of Burlington, VT for the years 2016 and 2017 as follows:

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

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

Datapoints from different sources may be have independent time periods. For example, the US Census ACS 5-year data is released on a different schedule than the State Tax Ranks. This may require providing independent time period filters for datapoints.

  
var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val",
      {
        "datapoint": "tax.str.ovrl",
        "periods": ["2015", "2016", "2017"]
      }
    ],
    "scope": {
      "periods": ["2016", "2017"]
    }
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
};

var response = {
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "source": "acs5",
        "periods": ["2016", "2017"],
        "values": [42556, 42453]
      },
      {
        "datapoint": "tax.str.ovrl",
        "geography": "state:vermont",
        "periods": ["2015", "2016", "2017"],
        "values": [46, 47, 47]
      }
    ]
  }
};

It is also possible to use tokens for time periods rather than specific years. The following tokens are supported:

Filtering Collections

Collections can be quite large and it is often desirable to limit scope to certain items. For example, a request could be made for County Business Patterns (CBP) industry data for just one NAICS code for specific time periods, as follows:

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ],
    "collections": [
      {
        "collection": "ind.cbp.naics",
        "datapoints": [
          "ind.cbp.naics.desc",
          "ind.cbp.naics.emp.val"
        ],
        "scope": {
          "periods": ["2015", "2016"],
          "datapoints": {
            "ind.cbp.naics.code": ["541511"]
          }
        }
      }
    ],
    "scope": {
      "periods": ["2016", "2017"]
    }
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
};

var response = {
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "source": "acs5",
        "periods": ["2016", "2017"],
        "values": [42556, 42453]
      },
      {
        "collection": "ind.cbp.naics",
        "items": [
          {
            "item": "541511",
            "periods": ["2015", "2016"],
            "data": [
              {
                "datapoint": "ind.cbp.naics.desc",
                "values": [
                  "Custom Computer Programming Services",
                  "Custom Computer Programming Services"
                ]
              },
              {
                "datapoint": "ind.cbp.naics.emp.val",
                "values": [1126, 956]
              }
            ]
          }
        ]
      }
    ]
  }
};

It is also possible to filter based on other datapoints in a collection using relational and logical operators.  For example, this request shows the population of Burlington, VT plus the airports that have a runway of at least 6,000 feet:

var request = {
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ],
    "collections": [
      {
        "collection": "trn.airport",
        "datapoints": [
          "trn.airport.name",
          "trn.airport.runway"
        ],
        "scope": {
          "datapoints": {
            "sql": {
              ">": ["trn.airport.runway", 6000]
            }
          }
        }
      }
    ]
  },
  "criteria": {
    "geography": "cbsa:burlington-south-burlington-vt-metro-area"
    }
  }
};

var response = {
  "resultset": {
    "geography": "cbsa:burlington-south-burlington-vt-metro-area",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "source": "acs5",
        "periods": ["2017"],
        "values": [42453]
      },
      {
        "collection": "trn.airport",
        "periods": ["2017"],
        "items": [
          {
            "item": "BTV",
            "data": [
              {
                "datapoint": "trn.airport.name",
                "value": "Burlington Intl"
              },
              {
                "datapoint": "trn.airport.runway",
                "values": [8319]
              }
            ]
          }
        ]
      }
    ]
  }
};

The scope can be limited using an assortment of operators, such as relational operators (> >= < <= <>) and string operators (like and ilike). In the absence of a specific operator, filters are always equalities. Arrays can be used to filter on a larger set of values.