• API Endpoint
• Parameters/Variables in a BDS API Call
  • Basic Settings
  • Indicators
  • Geography
  • Year
  • Metro/Micropolitan Area
  • Geography Component
  • NAICS Industry
  • Firm Size
  • Initial Firm Size
  • Establishment Size
  • Initial Establishment Size
  • Firm Age
  • Establishment Size
  • Industry Level
• Advanced Queries
• Notes/Limitations
• Related Information

• API Call: api.census.gov/data/timeseries/bds?key=YOUR_KEY_GOES_HERE
• Complete Set of Indicators, Categorical Variables, Label Fields, and Flags available at: api.census.gov/data/timeseries/bds/variables.html?key=YOUR_KEY_GOES_HERE
• Additional API Example Queries available at: api.census.gov/data/timeseries/bds/examples.html?key=YOUR_KEY_GOES_HERE

Basic Settings - Get Statement, Geography, Key

• Required: A “get” statement – this is typically used to display indicators, but categorical variables, label fields, or flags can also be added here. Categorical variables, label fields, and flags in the “get” statement will display all available values.
  • “get=JOB_CREATION”
• Required: At least one geography in the “for” statement
  • “&for=county:001&in=state:01” requests county-level data by FIPS code for Autauga County, Alabama
  • “&for=metropolitan%20statistical%20area/micropolitan%20statistical%20area:10180” requests CBSA-level data by FIPS code for Abilene, Texas
  • “&for=state:01” requests state-level data by FIPS code for Alabama
  • “&for=us:1” requests nation-level data
• All selections in the “get” statement must be separated by commas, all selections in the “for” statement must be separated by the ampersand (“&”) character.
• Default values for other categorical variables are assumed if not specified. The example below shows the minimum requirements for a fully-formed basic query:

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&key=YOUR_KEY_GOES_HERE

The following BDS API query demonstrates the key components. The query will return the count of job creation in firms with one to four employees in Maryland Metro/Micropolitan Areas in 2023. This example is repeated in each of the sections below, with the relevant statement highlighted in the query.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EMPSZFI=612&key=YOUR_KEY_GOES_HERE

• Select desired Indicators using the “get” statement.

View available Indicators. 

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EMPSZFI=612&key=YOUR_KEY_GOES_HERE

• Select the desired Geography codes as a “predicate” using “&for” statement.
• Geographies represent the geography of the firm/establishment and can be “national”, “state”, “metropolitan%20statistical%20area/micropolitan%20statistical%20area”, or “county” (use “&for=us:1” for national totals).
• View available state codes.
• View available metro/micropolitan codes.
• View available county codes.

• Select the year as a “predicate”.
• Available years are 1978-2023.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EMPSZFI=612&key=YOUR_KEY_GOES_HERE

• Select desired Metro/Non-Metro codes as a “predicate”.
• Use METRO codes to return tabulations for establishments that are inside Metro/Micropolitan Areas vs establishments outside Metro/Micropolitan Areas. As shown in this example query, GEOCOMP and METRO should always be used together.
• View available METRO codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EMPSZFI=612&key=YOUR_KEY_GOES_HERE

• Select desired GEOCOMP codes as a “predicate”.
• Use GEOCOMP codes to return tabulations for establishments that cannot be assigned to Census geography. As shown in this example query, GEOCOMP and METRO should always be used together.
• View available GEOCOMP codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EMPSZFI=612&key=YOUR_KEY_GOES_HERE

• Select desired NAICS codes as a “predicate”.
• NAICS sector, subsector, or industry group tabulations can be queried using the NAICS variable.
• View available NAICS codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EMPSZFI=612&key=YOUR_KEY_GOES_HERE

• Select desired EMPSZFI codes as a “predicate”.
• View available EMPSZFI codes.

Note: the remaining categories will use new/unique query examples, since additional crossings are not available in the BDS:

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EMPSZFII=612&key=YOUR_KEY_GOES_HERE

• Select desired EMPSZFII codes as a “predicate”.
• View available EMPSZFII codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&EMPSZES=212&key=YOUR_KEY_GOES_HERE

• Select desired EMPSZES codes as a “predicate”.
• View available EMPSZES codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&EMPSZESI=212&key=YOUR_KEY_GOES_HERE

• Select desired EMPSZESI codes as a “predicate”.
• View available EMPSZESI codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&FAGE=010&key=YOUR_KEY_GOES_HERE

• Select desired FAGE codes as a “predicate”.
• View available FAGE codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION&for=state:24&YEAR=2023&METRO=M&GEOCOMP=A0&NAICS=21&EAGE=010&key=YOUR_KEY_GOES_HERE

• Select desired EAGE codes as a “predicate”.
• View available EAGE codes.

api.census.gov/data/timeseries/bds?get=JOB_CREATION,NAICS&for=state:24&YEAR=2023&INDLEVEL=2&key=YOUR_KEY_GOES_HERE

• Select desired Industry Level characteristic as a “predicate”.
• Use Industry Level in combination with NAICS in the “get” statement to return all industries at the sector, subsector, or industry group level.
• View available INDLEVEL codes.

• Get data for all characteristics in a Category Variable: api.census.gov/data/timeseries/bds?get=JOB_CREATION,YEAR,METRO,NAICS,GEOCOMP,EMPSZFI&for=state:24&key=YOUR_KEY_GOES_HERE
• Get data for multiple indicators and multiple States: api.census.gov/data/timeseries/bds?get=JOB_CREATION,JOB_CREATION_RATE,JOB_DESTRUCTION,JOB_DESTRUCTION_RATE,FIRM&for=state:06,28,54&YEAR=2023&key=YOUR_KEY_GOES_HERE

• Wildcards can be used to return tabulations for all characteristics in a particular geography or categorical variable (i.e. “&for=state:*” or “&YEAR=*”).
• The “get” statement can hold categorical variable names, labels, and flags in addition to indicator names. Adding a categorical variable to the “get” statement will include that column in the query results and returns all of its characteristics.
• All counties in the country can be queried with a wildcard (i.e. “&for=county:*”). Otherwise, county codes must be entered as three digits and include a state using an “in” statement (i.e. “&for=county:001&in=state:01”).
• Commas can be used to select multiple indicators, multiple geographies, and multiple graduation cohorts. Multiples for other categories can be requested via the “get” statement or using the complete parameter string in the “for” statement (i.e. “&NAICS=11&NAICS=54&NAICS=22”).
• Users can view industry hierarchies using SECTOR or SUBSECTOR in the “predicate” in combination with NAICS in the “for” statement. For example, "get=FIRM,NAICS&for=us:1&SECTOR=22" will return tabulations for all 2/3/4 industries that start with "22". Similarly, "get=FIRM,NAICS&for=us:1&SUBSECTOR=333", will return tabulations for all industries that start with “333”.
• The GEOCOMP and METRO variables should always be used together in an API query. These variables can be used to distinguish between nationwide, statewide, in-metro, and not-in-metro tabulations.  
• Labels exist for all categorical variables – simply add “_LABEL” to the end of a categorical variable (i.e. NAICS_LABEL).
• Flags exist for all indicators – simply add “_F” to the end of an indicator (i.e. JOB_CREATION_F). The flag will return “null”, “D”, "N", “S”, or “X”. A “null” value means the cell is not suppressed. Cells suppressed due to containing too few firms will return a “D” flag. Rate cells that cannot be calculated will return a “N” flag. Cells suppressed due to data quality concerns will return a “S” flag. Cells that are unavailable due to structural missingness will return a “X” flag. Note that the data value will always return “0” when there is a “D”, "N", “S”, or “X” flag.
• Not all interactions are available in the data. See census.gov/data/datasets/time-series/econ/bds/bds-datasets to view the available crossings.