U.S. Census Bureau

Read official U.S. population, housing and economic statistics straight from the Census Bureau, and turn addresses into the geographies they are published against. Search roughly 1,800 datasets (the American Community Survey, the Decennial Census, Population Estimates, County Business Patterns, International Trade), find the table or variable you need, and pull it for any area from the nation down to a census block. Geocode an address or a list of up to 10,000 to coordinates and to their state, county, tract and block, and go straight from a street address to the statistics for the neighbourhood around it. Public domain data, a free API key, and no third party in between.

Actions

Action	What it does
Describe a table	List every variable in one table, with the label that says what each measures.
Geocode an address	Find the latitude and longitude of a street address, together with the address as the Census Bureau standardises it and the parts it split it into.
Geocode many addresses	Geocode up to 10,000 addresses in one step and get coordinates for each, with the standardised address and whether the match was exact.
Get a whole table	Pull an entire Census table for a geography in one step: every line of it, each column labelled with what it measures.
Get data	Run a Census data query and get one record per area, with the counts converted to numbers you can add up and the codes left as codes so they still match.
Get data for an address	Go straight from a street address to the Census statistics for the area around it.
Get dataset details	Everything the Census Bureau records about one dataset: what it covers, the period it describes, when it was last published, who to contact about it, and every geography level it can be broken down by.
Get example query	The dataset's own worked example: which variables the Census Bureau suggests starting from, and a real code for every geography level it publishes: the state code for California, a county code, a tract code.
Get variable details	What one variable measures: its full label, the table and subject it belongs to, the population it covers, whether it is a count or a dollar figure, and (for a variable used as a filter) the codes it accepts and what each one means.
List dataset topics	The subjects a dataset covers, as the Census Bureau files them: income, poverty, commuting, veterans, housing.
List geocoder benchmarks	The snapshots of the Census address ranges the geocoder can match against, and which is current.
List geography codes	List the areas at one geography level with the code each is called by: every county in Texas, every place in Oregon, every congressional district.
List geography levels	Which kinds of area a dataset can be broken down by, and what each needs to be asked for: a tract has to be asked for inside a state, a state does not.
List geography vintages	The years of geography boundaries a benchmark can report against.
Look up a point's census areas	Find which census areas a latitude and longitude falls in: state, county, tract, block, districts and places.
Look up an address's census areas	Find which census areas a street address falls in: its state, county, tract and block, plus its congressional district, state legislative districts, place, ZIP Code Tabulation Area and school district.
Look up census areas for many addresses	Find the state, county, tract and block for up to 10,000 addresses at once, along with their coordinates.
Look up census areas for many points	Find the state, county, tract and block for up to 10,000 latitude/longitude points at once.
Search datasets	Search the roughly 1,800 datasets the Census Data API publishes (the American Community Survey, the Decennial Census, Population Estimates, County Business Patterns, International Trade and the rest), and get the exact path each one answers on, which every other action needs.
Search tables	Search a dataset's tables by subject: 'median household income', 'commuting', 'housing tenure'.
Search variables	Find the code for a statistic by searching a dataset's variables on the words in their labels: 'median gross rent', 'without health insurance', 'bachelor's degree'.

Describe a table

List every variable in one table, with the label that says what each measures. Use it to see what a table contains before pulling it, or to find the one line of it you want.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
TablegrouptextRequired: The table to describe. Pick from the list, or chain in a table code from 'Search tables'.

Outputs

concepttext
datasettext
grouptext
variable_countnumber
variableslist

Example output

{
  "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
  "dataset": "2023/acs/acs5",
  "group": "B19013",
  "variable_count": 6,
  "variables": [
    {
      "attributes": "",
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "group": "B19013",
      "label": "Estimate!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001E",
      "predicate_only": true,
      "predicate_type": "int",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    },
    {
      "attributes": "",
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "group": "B19013",
      "label": "Annotation of Estimate!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001EA",
      "predicate_only": true,
      "predicate_type": "string",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    },
    {
      "attributes": "",
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "group": "B19013",
      "label": "Margin of Error!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001M",
      "predicate_only": true,
      "predicate_type": "int",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    },
    {
      "attributes": "",
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "group": "B19013",
      "label": "Annotation of Margin of Error!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001MA",
      "predicate_only": true,
      "predicate_type": "string",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    },
    {
      "attributes": "",
      "concept": "",
      "group": "B19013",
      "label": "Geography",
      "name": "GEO_ID",
      "predicate_only": true,
      "predicate_type": "string",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    },
    {
      "attributes": "",
      "concept": "",
      "group": "B19013",
      "label": "Geographic Area Name",
      "name": "NAME",
      "predicate_only": true,
      "predicate_type": "string",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    }
  ]
}

Geocode an address

Find the latitude and longitude of a street address, together with the address as the Census Bureau standardises it and the parts it split it into. Free, with no usage limits and no third party involved, for any address in the United States, Puerto Rico or the island areas.

Inputs

Address (all on one line)addresstext: The whole address in one field, the simplest way in. A street plus a ZIP code, or a street plus a city and state, is enough. Fill this in or the separate fields below, not both.
Street addressstreettext: House number and street. Needed if you are not using the one-line field above.
Citycitytext: City or town. Give this and the state, or give a ZIP code.
Statestatetext: Two-letter state code, such as DC or CA. Give this and the city, or give a ZIP code.
ZIP codezip_codetext: Five-digit ZIP code. A street plus a ZIP code is enough on its own.
Urbanización (Puerto Rico only)urbanizationtext: The urbanización of a Puerto Rico address. Filling this in (or the municipio) sends the address to the geocoder's Puerto Rico route, which is the only one that understands them. Leave empty everywhere else.
Municipio (Puerto Rico only)municipiotext: The municipio of a Puerto Rico address, in place of a city. Leave empty everywhere else.
Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.

Outputs

benchmarktext
best_matchobject
inputobject
match_countnumber
matchedtrue/false
matcheslist
vintagetext

Example output

{
  "benchmark": "Public_AR_Current",
  "best_match": {
    "address_components": {
      "city": "WASHINGTON",
      "fromAddress": "4600",
      "preDirection": "",
      "preQualifier": "",
      "preType": "",
      "state": "DC",
      "streetName": "SILVER HILL",
      "suffixDirection": "",
      "suffixQualifier": "",
      "suffixType": "RD",
      "toAddress": "4700",
      "zip": "20233"
    },
    "latitude": 38.845053106269,
    "longitude": -76.928365658124,
    "matched_address": "4600 SILVER HILL RD, WASHINGTON, DC, 20233",
    "side": "L",
    "tiger_line_id": "657091557"
  },
  "input": {
    "address": {
      "address": "4600 Silver Hill Rd, Washington, DC 20233"
    },
    "benchmark": {
      "benchmarkDescription": "Public Address Ranges - Current Benchmark",
      "benchmarkName": "Public_AR_Current",
      "id": "4",
      "isDefault": true
    }
  },
  "match_count": 1,
  "matched": true,
  "matches": [
    {
      "address_components": {
        "city": "WASHINGTON",
        "fromAddress": "4600",
        "preDirection": "",
        "preQualifier": "",
        "preType": "",
        "state": "DC",
        "streetName": "SILVER HILL",
        "suffixDirection": "",
        "suffixQualifier": "",
        "suffixType": "RD",
        "toAddress": "4700",
        "zip": "20233"
      },
      "latitude": 38.845053106269,
      "longitude": -76.928365658124,
      "matched_address": "4600 SILVER HILL RD, WASHINGTON, DC, 20233",
      "side": "L",
      "tiger_line_id": "657091557"
    }
  ]
}

Geocode many addresses

Geocode up to 10,000 addresses in one step and get coordinates for each, with the standardised address and whether the match was exact. Each row can carry your own reference, which comes back with the answer so the results line up with the list you sent. No file to build: give the addresses as rows and the file is made for you.

Inputs

AddressesaddresseslistRequired: One row per address. Each needs a street, plus a ZIP code or a city and state. Up to 10,000 rows in one step.
Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.

Outputs

benchmarktext
countnumber
match_rate_percentnumber
matched_countnumber
resultslist
submittednumber
tie_countnumber
unmatched_countnumber

Example output

{
  "benchmark": "Public_AR_Current",
  "count": 2,
  "match_rate_percent": 100.0,
  "matched_count": 2,
  "results": [
    {
      "id": "wh",
      "input_address": "1600 Pennsylvania Ave NW, Washington, DC, 20500",
      "latitude": 38.89869893252,
      "longitude": -77.03518753691,
      "match_status": "Match",
      "match_type": "Exact",
      "matched": true,
      "matched_address": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500",
      "side": "L",
      "tiger_line_id": "76225813"
    },
    {
      "id": "hq",
      "input_address": "4600 Silver Hill Rd, Washington, DC, 20233",
      "latitude": 38.845053106269,
      "longitude": -76.928365658124,
      "match_status": "Match",
      "match_type": "Exact",
      "matched": true,
      "matched_address": "4600 SILVER HILL RD, WASHINGTON, DC, 20233",
      "side": "L",
      "tiger_line_id": "657091557"
    }
  ],
  "submitted": 2,
  "tie_count": 0,
  "unmatched_count": 0
}

Get a whole table

Pull an entire Census table for a geography in one step: every line of it, each column labelled with what it measures. This is the way to get a full breakdown (age by sex, income brackets, means of travel to work) without naming dozens of variables, and it is not subject to the 50-variable limit a normal query has. By default the estimates and their margins of error come back and the annotation flags are left out.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
TablegrouptextRequired: Which table to pull. Pick from the list, or chain in a code from 'Search tables'.
Geography levelgeography_leveltextRequired: What kind of area each row should be: a state, a county, a census tract, a ZIP Code Tabulation Area. The list is the levels this dataset actually publishes, and says which larger area each one sits inside.
Which areasgeography_codestext: Which areas at that level. Leave as * for all of them, or give the Census codes, separated by commas: Los Angeles County is 037. 'List geography codes' returns the code for every area at a level, so you can chain one in rather than look it up.Default: *.
Statestatetext: Narrow the result to one state. Most levels below state level need this, because a dataset will not return every census tract in the once. Leave empty for the whole country where the level allows it.One of: 01 (Alabama (01)), 02 (Alaska (02)), 60 (American Samoa (60)), 04 (Arizona (04)), 05 (Arkansas (05)), 06 (California (06)), 08 (Colorado (08)), 09 (Connecticut (09)), 10 (Delaware (10)), 11 (District of Columbia (11)), and 46 more.
Within (deeper parent areas)withintext: Only for levels that sit more than one step down: a block group needs its county and tract as well as its state. Write each parent as level:code, separated by spaces: 'county:033 tract:802405'. Leave empty otherwise; the state above is enough for a county, a place or a tract.
Geography IDs (advanced)geography_idstext: An alternative to the four fields above, for mixing levels in one query: give fully qualified Census GEO IDs, separated by commas, and they are used instead. '0400000US24,0500000US24017' returns Maryland and Charles County together. Leave empty unless you need that.
Which columnscolumnstext: How much of the table to keep. A Census table carries an estimate, a margin of error and two annotation flags for every line; most workflows want the first two.One of: estimates (Estimates only), estimates_and_margins (Estimates and margins of error), all (Everything, including annotation flags). Default: estimates_and_margins.

Outputs

annotationslist
column_labelslist
columnslist
columns_returnedtext
concepttext
datasettext
grouptext
has_annotated_valuestrue/false
numeric_columnslist
query_urltext
row_countnumber
rowslist

Example output

{
  "annotations": [],
  "column_labels": [
    {
      "concept": "",
      "label": "Geographic Area Name",
      "name": "NAME"
    },
    {
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "label": "Estimate!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001E"
    },
    {
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "label": "Margin of Error!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001M"
    },
    {
      "concept": "",
      "label": "Geography",
      "name": "GEO_ID"
    },
    {
      "concept": "",
      "label": "",
      "name": "state"
    }
  ],
  "columns": [
    "NAME",
    "B19013_001E",
    "B19013_001M",
    "GEO_ID",
    "state"
  ],
  "columns_returned": "estimates_and_margins",
  "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
  "dataset": "2023/acs/acs5",
  "group": "B19013",
  "has_annotated_values": false,
  "numeric_columns": [
    "B19013_001E",
    "B19013_001M",
    "GEO_ID",
    "NAME"
  ],
  "query_url": "https://api.census.gov/data/2023/acs/acs5?get=NAME,group(B19013)&for=state:24,51",
  "row_count": 2,
  "rows": [
    {
      "B19013_001E": 98461,
      "B19013_001M": 628,
      "GEO_ID": "0400000US24",
      "NAME": "Maryland",
      "state": "24"
    },
    {
      "B19013_001E": 89393,
      "B19013_001M": 552,
      "GEO_ID": "0400000US51",
      "NAME": "Virginia",
      "state": "51"
    }
  ]
}

Get data

Run a Census data query and get one record per area, with the counts converted to numbers you can add up and the codes left as codes so they still match. Choose a dataset, the variables you want, and the kind of area to break them down by; the parent areas a level needs are filled in from the dataset's own rules. Values the Census Bureau publishes in place of an estimate it could not compute are reported as annotations rather than passed off as numbers.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
Table (to choose variables from)tabletextRequired: Which table the variable list below is drawn from. This only narrows that list; it is not part of the query. Choose 'All variables' for a small dataset; for the ACS detailed tables, which hold tens of thousands of variables, choose a table so the list is short enough to read. 'Search tables' finds one by subject.Default: *.
VariablesvariableslistRequired: Which statistics to return, up to 50 in one query. Pick NAME to get each area's name alongside the numbers. The list holds the variables of the table chosen above; with 'All variables' chosen it stops at 3,000 entries, so pick a table (or use 'Search variables' and chain the code in) for a dataset larger than that.
Geography levelgeography_leveltextRequired: What kind of area each row should be: a state, a county, a census tract, a ZIP Code Tabulation Area. The list is the levels this dataset actually publishes, and says which larger area each one sits inside.
Which areasgeography_codestext: Which areas at that level. Leave as * for all of them, or give the Census codes, separated by commas: Los Angeles County is 037. 'List geography codes' returns the code for every area at a level, so you can chain one in rather than look it up.Default: *.
Statestatetext: Narrow the result to one state. Most levels below state level need this, because a dataset will not return every census tract in the once. Leave empty for the whole country where the level allows it.One of: 01 (Alabama (01)), 02 (Alaska (02)), 60 (American Samoa (60)), 04 (Arizona (04)), 05 (Arkansas (05)), 06 (California (06)), 08 (Colorado (08)), 09 (Connecticut (09)), 10 (Delaware (10)), 11 (District of Columbia (11)), and 46 more.
Within (deeper parent areas)withintext: Only for levels that sit more than one step down: a block group needs its county and tract as well as its state. Write each parent as level:code, separated by spaces: 'county:033 tract:802405'. Leave empty otherwise; the state above is enough for a county, a place or a tract.
Geography IDs (advanced)geography_idstext: An alternative to the four fields above, for mixing levels in one query: give fully qualified Census GEO IDs, separated by commas, and they are used instead. '0400000US24,0500000US24017' returns Maryland and Charles County together. Leave empty unless you need that.
Filtersfiltersobject: Narrow the rows by the value of a variable, as name/value pairs: HISP = 2 for the Hispanic population in Population Estimates, or PAYANN = '400000:500000' for a range. 'Get variable details' lists the codes a filter variable accepts. Leave empty for no filtering.
Time periodtime_periodtext: For time-series datasets only: which period to return. A year (2015), a month (2015-01), a quarter (2015-Q1), or a range written as 'from 1997 to 2012'. Leave empty for every period the dataset holds.

Outputs

annotationslist
columnslist
datasettext
has_annotated_valuestrue/false
numeric_columnslist
query_urltext
row_countnumber
rowslist

Example output

{
  "annotations": [
    {
      "code": -666666666,
      "column": "B19013_001E",
      "meaning": "The estimate could not be computed because there were an insufficient number of sample observations",
      "row_count": 1
    },
    {
      "code": -222222222,
      "column": "B19013_001M",
      "meaning": "The margin of error could not be computed because there were an insufficient number of sample observations",
      "row_count": 1
    }
  ],
  "columns": [
    "NAME",
    "B19013_001E",
    "B19013_001M",
    "state",
    "county"
  ],
  "dataset": "2023/acs/acs5",
  "has_annotated_values": true,
  "numeric_columns": [
    "B19013_001E",
    "B19013_001M",
    "NAME"
  ],
  "query_url": "https://api.census.gov/data/2023/acs/acs5?get=NAME,B19013_001E,B19013_001M&for=county:*&in=state:24",
  "row_count": 5,
  "rows": [
    {
      "B19013_001E": 129549,
      "B19013_001M": 3126,
      "NAME": "Howard County, Maryland",
      "county": "027",
      "state": "24"
    },
    {
      "B19013_001E": 125583,
      "B19013_001M": 1587,
      "NAME": "Montgomery County, Maryland",
      "county": "031",
      "state": "24"
    },
    {
      "B19013_001E": 97935,
      "B19013_001M": 1502,
      "NAME": "Prince George's County, Maryland",
      "county": "033",
      "state": "24"
    },
    {
      "B19013_001E": 58349,
      "B19013_001M": 1338,
      "NAME": "Baltimore city, Maryland",
      "county": "510",
      "state": "24"
    },
    {
      "B19013_001E": -666666666,
      "B19013_001M": -222222222,
      "NAME": "Somerset County, Maryland",
      "county": "039",
      "state": "24"
    }
  ]
}

Get data for an address

Go straight from a street address to the Census statistics for the area around it. The address is geocoded, the census tract (or county, or whichever level you choose) it falls in is identified, and the variables or table you asked for are returned for that area. Three steps in one, with no codes to copy between them. Use it to enrich a customer list, size up a catchment, or check the neighbourhood behind a lead.

Inputs

Address (all on one line)addresstext: The whole address in one field, the simplest way in. A street plus a ZIP code, or a street plus a city and state, is enough. Fill this in or the separate fields below, not both.
Street addressstreettext: House number and street. Needed if you are not using the one-line field above.
Citycitytext: City or town. Give this and the state, or give a ZIP code.
Statestatetext: Two-letter state code, such as DC or CA. Give this and the city, or give a ZIP code.
ZIP codezip_codetext: Five-digit ZIP code. A street plus a ZIP code is enough on its own.
DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
Table (to choose variables from)tabletextRequired: Which table the variable list below is drawn from. This only narrows that list; it is not part of the query. Choose 'All variables' for a small dataset; for the ACS detailed tables, which hold tens of thousands of variables, choose a table so the list is short enough to read. 'Search tables' finds one by subject.Default: *.
Variablesvariableslist: Which statistics to return for the area. Leave empty if you are pulling a whole table below instead.
Whole table (instead of variables)grouptext: Pull an entire table for the area instead of picking variables. Leave empty if you chose variables above.
Area typegeography_leveltext: How big an area around the address to report on. A census tract is roughly a neighbourhood of 4,000 people and is the default; a county or a place is wider; a block is the smallest area published.One of: block, block group, congressional district, county, county subdivision, place, public use microdata area, state, tract, zip code tabulation area. Default: tract.
Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.
Geography vintagevintagetext: Which year's geography boundaries to report. Tracts and districts are redrawn, so a 2019 address falls in a different tract under a 2019 vintage than under the current one. Match this to the dataset you will query: ACS 2023 data goes with the ACS2023 vintage.Default: Current_Current.

Outputs

dataobject
datasettext
geographyobject
geography_codetext
geography_leveltext
latitudenumber
longitudenumber
matched_addresstext
rowobject

Example output

{
  "data": {
    "annotations": [],
    "columns": [
      "NAME",
      "B01003_001E",
      "B19013_001E",
      "state",
      "county",
      "tract"
    ],
    "dataset": "2023/acs/acs5",
    "has_annotated_values": false,
    "numeric_columns": [
      "B01003_001E",
      "B19013_001E",
      "NAME"
    ],
    "query_url": "https://api.census.gov/data/2023/acs/acs5?get=NAME,B01003_001E,B19013_001E&for=tract:802405&in=state:24+county:033",
    "row_count": 1,
    "rows": [
      {
        "B01003_001E": 4184,
        "B19013_001E": 104427,
        "NAME": "Census Tract 8024.05; Prince George's County; Maryland",
        "county": "033",
        "state": "24",
        "tract": "802405"
      }
    ]
  },
  "dataset": "2023/acs/acs5",
  "geography": {
    "block": "2004",
    "block_geoid": "240338024052004",
    "block_group": "2",
    "block_group_geoid": "240338024052",
    "combined_statistical_area": "Washington-Baltimore-Arlington, DC-MD-VA-WV-PA",
    "congressional_district": "4",
    "congressional_district_geoid": "2404",
    "county_fips": "033",
    "county_geoid": "24033",
    "county_name": "Prince George's County",
    "county_subdivision_fips": "90524",
    "county_subdivision_name": "District 6, Spauldings",
    "metropolitan_statistical_area": "Washington-Arlington-Alexandria, DC-VA-MD-WV",
    "place_fips": "75725",
    "place_name": "Suitland CDP",
    "public_use_microdata_area": "01107",
    "school_district": "Prince George's County Public Schools",
    "state_abbreviation": "MD",
    "state_fips": "24",
    "state_legislative_district_lower": "24",
    "state_legislative_district_upper": "24",
    "state_name": "Maryland",
    "tract": "802405",
    "tract_geoid": "24033802405",
    "urban_area": "Washington--Arlington, DC--VA--MD",
    "zip_code_tabulation_area": "20746"
  },
  "geography_code": "802405",
  "geography_level": "tract",
  "latitude": 38.845053106269,
  "longitude": -76.928365658124,
  "matched_address": "4600 SILVER HILL RD, WASHINGTON, DC, 20233",
  "row": {
    "B01003_001E": 4184,
    "B19013_001E": 104427,
    "NAME": "Census Tract 8024.05; Prince George's County; Maryland",
    "county": "033",
    "state": "24",
    "tract": "802405"
  }
}

Get dataset details

Everything the Census Bureau records about one dataset: what it covers, the period it describes, when it was last published, who to contact about it, and every geography level it can be broken down by.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.

Outputs

access_urltext
api_pathtext
contact_emailtext
contact_nametext
datasettext
descriptiontext
documentation_urltext
examples_urltext
geography_levelslist
geography_urltext
groups_urltext
is_aggregatetrue/false
is_availabletrue/false
is_microdatatrue/false
is_timeseriestrue/false
modifiedtext
spatialtext
tags_urltext
temporaltext
titletext
variables_urltext
vintagenumber

Example output

{
  "access_url": "https://api.census.gov/data/2023/acs/acs5",
  "api_path": "2023/acs/acs5",
  "contact_email": "acso.users.support@census.gov",
  "contact_name": "American Community Survey Office",
  "dataset": "acs/acs5",
  "description": "The American Community Survey (ACS) is an ongoing survey that provides data every year -- giving communities the current information they need to plan investments and services. The ACS covers a broad range of topics about social, economic, demographic, and housing characteristics of the U.S. population. Summary files include the following geographies: nation, all states (including DC and Puerto Rico), all metropolitan areas, all congressional districts, all counties, all places, and all tracts and block groups. Summary files contain the most detailed cross-tabulations, many of which are published down to block groups. The data are population and housing counts. There are over 64,000 variables in this dataset.",
  "documentation_url": "https://www.census.gov/developer/",
  "examples_url": "https://api.census.gov/data/2023/acs/acs5/examples.json",
  "geography_levels": [
    {
      "name": "us",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "010",
      "wildcard_allowed": []
    },
    {
      "name": "state",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "040",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "state",
      "reference_date": "2023-01-01",
      "requires": [
        "state"
      ],
      "summary_level": "050",
      "wildcard_allowed": [
        "state"
      ]
    },
    {
      "name": "tract",
      "optional_with_wildcard_for": "county",
      "reference_date": "2023-01-01",
      "requires": [
        "state",
        "county"
      ],
      "summary_level": "140",
      "wildcard_allowed": [
        "county"
      ]
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "metropolitan statistical area/micropolitan statistical area",
        "state (or part)"
      ],
      "summary_level": "313",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "metropolitan statistical area/micropolitan statistical area",
        "metropolitan division",
        "state (or part)"
      ],
      "summary_level": "316",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "state",
        "metropolitan statistical area/micropolitan statistical area (or part)"
      ],
      "summary_level": "322",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "state",
        "metropolitan statistical area/micropolitan statistical area (or part)",
        "metropolitan division (or part)"
      ],
      "summary_level": "324",
      "wildcard_allowed": []
    }
  ],
  "geography_url": "https://api.census.gov/data/2023/acs/acs5/geography.json",
  "groups_url": "https://api.census.gov/data/2023/acs/acs5/groups.json",
  "is_aggregate": true,
  "is_available": true,
  "is_microdata": false,
  "is_timeseries": false,
  "modified": "2024-09-06 17:27:47.0",
  "spatial": "US",
  "tags_url": "https://api.census.gov/data/2023/acs/acs5/tags.json",
  "temporal": "2023/2023",
  "title": "ACS 5-Year Detailed Tables",
  "variables_url": "https://api.census.gov/data/2023/acs/acs5/variables.json",
  "vintage": 2023
}

Get example query

The dataset's own worked example: which variables the Census Bureau suggests starting from, and a real code for every geography level it publishes: the state code for California, a county code, a tract code. The quickest way to see a valid value for each level before writing a query.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.

Outputs

countnumber
datasettext
example_variableslist
geographieslist

Example output

{
  "count": 65,
  "dataset": "2023/acs/acs5",
  "example_variables": [
    "NAME",
    "B01001_001E"
  ],
  "geographies": [
    {
      "example_value": "1",
      "name": "us",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "010",
      "wildcard_allowed": []
    },
    {
      "example_value": "06",
      "name": "state",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "040",
      "wildcard_allowed": []
    },
    {
      "example_value": "037",
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "050",
      "wildcard_allowed": []
    },
    {
      "example_value": "018700",
      "name": "tract",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "140",
      "wildcard_allowed": []
    },
    {
      "example_value": "037",
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "313",
      "wildcard_allowed": []
    },
    {
      "example_value": "037",
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "316",
      "wildcard_allowed": []
    },
    {
      "example_value": "037",
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "322",
      "wildcard_allowed": []
    },
    {
      "example_value": "037",
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "324",
      "wildcard_allowed": []
    }
  ]
}

Get variable details

What one variable measures: its full label, the table and subject it belongs to, the population it covers, whether it is a count or a dollar figure, and (for a variable used as a filter) the codes it accepts and what each one means.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
VariablevariabletextRequired: The variable code to look up, such as B19013_001E.

Outputs

attributestext
concepttext
datasettext
grouptext
labeltext
nametext
predicate_onlytrue/false
predicate_typetext
requiredtrue/false
universetext
value_countnumber
valuesobject
values_truncatedtrue/false

Example output

{
  "attributes": "B19013_001EA,B19013_001M,B19013_001MA",
  "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
  "dataset": "2023/acs/acs5",
  "group": "B19013",
  "label": "Estimate!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
  "name": "B19013_001E",
  "predicate_only": false,
  "predicate_type": "int",
  "required": false,
  "universe": "",
  "value_count": 0,
  "values": {},
  "values_truncated": false
}

List dataset topics

The subjects a dataset covers, as the Census Bureau files them: income, poverty, commuting, veterans, housing. A quick way to see whether a dataset holds the kind of thing you are after before searching its variables.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.

Outputs

countnumber
datasettext
tagslist

Example output

{
  "count": 44,
  "dataset": "2023/acs/acs5",
  "tags": [
    "aian",
    "ancestry",
    "black",
    "children",
    "citizenship",
    "class of worker",
    "commuting",
    "disability",
    "earnings",
    "educational attainment",
    "employment",
    "enrollment",
    "experience",
    "family",
    "fertility",
    "food",
    "grandparents",
    "heating",
    "household",
    "income",
    "inequality",
    "labor",
    "language",
    "marriage",
    "men",
    "native hawaiian",
    "nativity",
    "nonfamily",
    "pacific islander",
    "parents",
    "plumbing",
    "population",
    "poverty",
    "race",
    "responsibility",
    "rooms",
    "sex",
    "subfamily",
    "transportation",
    "travel",
    "vehicle",
    "veteran",
    "women",
    "workers"
  ]
}

List geocoder benchmarks

The snapshots of the Census address ranges the geocoder can match against, and which is current. A benchmark fixes the vintage of the address data itself, which is useful when a result that was produced against an earlier one.

Inputs

None.

Outputs

benchmarkslist
countnumber
default_benchmarktext

Example output

{
  "benchmarks": [
    {
      "description": "Public Address Ranges - Current Benchmark",
      "id": "4",
      "is_default": true,
      "name": "Public_AR_Current"
    },
    {
      "description": "Public Address Ranges - ACS2025 Benchmark",
      "id": "8",
      "is_default": false,
      "name": "Public_AR_ACS2025"
    },
    {
      "description": "Public Address Ranges - LUCA Benchmark",
      "id": "11",
      "is_default": true,
      "name": "Public_AR_LUCA"
    },
    {
      "description": "Public Address Ranges - Census 2020 Benchmark",
      "id": "2020",
      "is_default": false,
      "name": "Public_AR_Census2020"
    }
  ],
  "count": 4,
  "default_benchmark": "Public_AR_Current"
}

List geography codes

List the areas at one geography level with the code each is called by: every county in Texas, every place in Oregon, every congressional district. This is how the 'Which areas' field elsewhere gets filled in without looking codes up by hand: run this, then chain the code you want into a query.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
Geography levelgeography_leveltextRequired: What kind of area each row should be: a state, a county, a census tract, a ZIP Code Tabulation Area. The list is the levels this dataset actually publishes, and says which larger area each one sits inside.
Statestatetext: Narrow the result to one state. Most levels below state level need this, because a dataset will not return every census tract in the once. Leave empty for the whole country where the level allows it.One of: 01 (Alabama (01)), 02 (Alaska (02)), 60 (American Samoa (60)), 04 (Arizona (04)), 05 (Arkansas (05)), 06 (California (06)), 08 (Colorado (08)), 09 (Connecticut (09)), 10 (Delaware (10)), 11 (District of Columbia (11)), and 46 more.
Within (deeper parent areas)withintext: Only for levels that sit more than one step down: a block group needs its county and tract as well as its state. Write each parent as level:code, separated by spaces: 'county:033 tract:802405'. Leave empty otherwise; the state above is enough for a county, a place or a tract.
Searchsearchtext: Narrow the list to entries containing every word you type. Leave empty to list everything.
How many to returnlimitnumber: How many areas to return, up to 5,000. There are 3,143 counties and 85,000 census tracts, so narrow tracts and block groups to a state.From 1 to 5000. Default: 1000.

Outputs

areaslist
countnumber
datasettext
geography_leveltext
query_urltext
total_matchesnumber
truncatedtrue/false

Example output

{
  "areas": [
    {
      "code": "001",
      "name": "Allegany County, Maryland",
      "parents": {
        "state": "24"
      }
    },
    {
      "code": "003",
      "name": "Anne Arundel County, Maryland",
      "parents": {
        "state": "24"
      }
    },
    {
      "code": "005",
      "name": "Baltimore County, Maryland",
      "parents": {
        "state": "24"
      }
    },
    {
      "code": "510",
      "name": "Baltimore city, Maryland",
      "parents": {
        "state": "24"
      }
    },
    {
      "code": "009",
      "name": "Calvert County, Maryland",
      "parents": {
        "state": "24"
      }
    }
  ],
  "count": 5,
  "dataset": "2023/acs/acs5",
  "geography_level": "county",
  "query_url": "https://api.census.gov/data/2023/acs/acs5?get=NAME&for=county:*&in=state:24",
  "total_matches": 24,
  "truncated": false
}

List geography levels

Which kinds of area a dataset can be broken down by, and what each needs to be asked for: a tract has to be asked for inside a state, a state does not. Not every dataset publishes every level: the ACS 1-year estimates stop at areas of 65,000 people, while the 5-year estimates reach block groups.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.

Outputs

countnumber
datasettext
geography_levelslist
level_nameslist

Example output

{
  "count": 65,
  "dataset": "2023/acs/acs5",
  "geography_levels": [
    {
      "name": "us",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "010",
      "wildcard_allowed": []
    },
    {
      "name": "state",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [],
      "summary_level": "040",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "state",
      "reference_date": "2023-01-01",
      "requires": [
        "state"
      ],
      "summary_level": "050",
      "wildcard_allowed": [
        "state"
      ]
    },
    {
      "name": "tract",
      "optional_with_wildcard_for": "county",
      "reference_date": "2023-01-01",
      "requires": [
        "state",
        "county"
      ],
      "summary_level": "140",
      "wildcard_allowed": [
        "county"
      ]
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "metropolitan statistical area/micropolitan statistical area",
        "state (or part)"
      ],
      "summary_level": "313",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "metropolitan statistical area/micropolitan statistical area",
        "metropolitan division",
        "state (or part)"
      ],
      "summary_level": "316",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "state",
        "metropolitan statistical area/micropolitan statistical area (or part)"
      ],
      "summary_level": "322",
      "wildcard_allowed": []
    },
    {
      "name": "county",
      "optional_with_wildcard_for": "",
      "reference_date": "2023-01-01",
      "requires": [
        "state",
        "metropolitan statistical area/micropolitan statistical area (or part)",
        "metropolitan division (or part)"
      ],
      "summary_level": "324",
      "wildcard_allowed": []
    }
  ],
  "level_names": [
    "county",
    "state",
    "tract",
    "us"
  ]
}

List geography vintages

The years of geography boundaries a benchmark can report against. Tracts, districts and place limits are redrawn over time, so an address can sit in a different tract under a 2019 vintage than under the current one, so match the vintage to data you are joining to.

Inputs

Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.

Outputs

benchmarktext
countnumber
default_vintagetext
vintageslist

Example output

{
  "benchmark": "Public_AR_Current",
  "count": 11,
  "default_vintage": "Current_Current",
  "vintages": [
    {
      "description": "Current Vintage - Current Benchmark",
      "id": "4",
      "is_default": true,
      "name": "Current_Current"
    },
    {
      "description": "Census2010 Vintage - Current Benchmark",
      "id": "410",
      "is_default": false,
      "name": "Census2010_Current"
    },
    {
      "description": "ACS2017 Vintage - Current Benchmark",
      "id": "417",
      "is_default": false,
      "name": "ACS2017_Current"
    },
    {
      "description": "ACS2018 Vintage - Current Benchmark",
      "id": "418",
      "is_default": false,
      "name": "ACS2018_Current"
    },
    {
      "description": "ACS2019 Vintage - Current Benchmark",
      "id": "419",
      "is_default": false,
      "name": "ACS2019_Current"
    },
    {
      "description": "Census2020 Vintage - Current Benchmark",
      "id": "420",
      "is_default": false,
      "name": "Census2020_Current"
    },
    {
      "description": "ACS2021 Vintage - Current Benchmark",
      "id": "421",
      "is_default": false,
      "name": "ACS2021_Current"
    },
    {
      "description": "ACS2022 Vintage - Current Benchmark",
      "id": "422",
      "is_default": false,
      "name": "ACS2022_Current"
    },
    {
      "description": "ACS2023 Vintage - Current Benchmark",
      "id": "423",
      "is_default": false,
      "name": "ACS2023_Current"
    },
    {
      "description": "ACS2024 Vintage - Current Benchmark",
      "id": "424",
      "is_default": false,
      "name": "ACS2024_Current"
    },
    {
      "description": "ACS2025 Vintage - Current Benchmark",
      "id": "425",
      "is_default": false,
      "name": "ACS2025_Current"
    }
  ]
}

Look up a point's census areas

Find which census areas a latitude and longitude falls in: state, county, tract, block, districts and places. Use it for a point that came from a map, a phone, a fleet log or another geocoder, where there is no address to look up.

Inputs

LongitudelongitudenumberRequired: Longitude in decimal degrees. Negative everywhere in the United States, so -77.0352 is Washington, DC.From -180 to 180.
LatitudelatitudenumberRequired: Latitude in decimal degrees, such as 38.8987.From -90 to 90.
Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.
Geography vintagevintagetext: Which year's geography boundaries to report. Tracts and districts are redrawn, so a 2019 address falls in a different tract under a 2019 vintage than under the current one. Match this to the dataset you will query: ACS 2023 data goes with the ACS2023 vintage.Default: Current_Current.
Geography layerslayerslist: Which kinds of area to report. Leave empty for the geocoder's own default set (state, county, tract, block, districts and places), or choose 'All layers' to get everything this vintage publishes.

Outputs

benchmarktext
geographyobject
geography_layersobject
latitudenumber
longitudenumber
matchedtrue/false
vintagetext

Example output

{
  "benchmark": "Public_AR_Current",
  "geography": {
    "block": "",
    "block_geoid": "",
    "block_group": "",
    "block_group_geoid": "",
    "combined_statistical_area": "",
    "congressional_district": "",
    "congressional_district_geoid": "",
    "county_fips": "001",
    "county_geoid": "11001",
    "county_name": "District of Columbia",
    "county_subdivision_fips": "",
    "county_subdivision_name": "",
    "metropolitan_statistical_area": "",
    "place_fips": "",
    "place_name": "",
    "public_use_microdata_area": "",
    "school_district": "",
    "state_abbreviation": "DC",
    "state_fips": "11",
    "state_legislative_district_lower": "",
    "state_legislative_district_upper": "",
    "state_name": "District of Columbia",
    "tract": "980000",
    "tract_geoid": "11001980000",
    "urban_area": "",
    "zip_code_tabulation_area": ""
  },
  "geography_layers": {
    "Census Tracts": [
      {
        "AREALAND": "6514231",
        "AREAWATER": "4996397",
        "BASENAME": "9800",
        "CENTLAT": "+38.8801546",
        "CENTLON": "-077.0352173",
        "COUNTY": "001",
        "FUNCSTAT": "S",
        "GEOID": "11001980000",
        "INTPTLAT": "+38.8809933",
        "INTPTLON": "-077.0363219",
        "LSADC": "CT",
        "MTFCC": "G5020",
        "NAME": "Census Tract 9800",
        "OBJECTID": 35043,
        "OID": "2079015504267431",
        "STATE": "11",
        "TRACT": "980000"
      }
    ]
  },
  "latitude": 38.89869,
  "longitude": -77.03518,
  "matched": true,
  "vintage": "Current_Current"
}

Look up an address's census areas

Find which census areas a street address falls in: its state, county, tract and block, plus its congressional district, state legislative districts, place, ZIP Code Tabulation Area and school district. These codes are what every Census statistic is published against, so this is the bridge from an address in a spreadsheet to the data about where it is.

Inputs

Address (all on one line)addresstext: The whole address in one field, the simplest way in. A street plus a ZIP code, or a street plus a city and state, is enough. Fill this in or the separate fields below, not both.
Street addressstreettext: House number and street. Needed if you are not using the one-line field above.
Citycitytext: City or town. Give this and the state, or give a ZIP code.
Statestatetext: Two-letter state code, such as DC or CA. Give this and the city, or give a ZIP code.
ZIP codezip_codetext: Five-digit ZIP code. A street plus a ZIP code is enough on its own.
Urbanización (Puerto Rico only)urbanizationtext: The urbanización of a Puerto Rico address. Filling this in (or the municipio) sends the address to the geocoder's Puerto Rico route, which is the only one that understands them. Leave empty everywhere else.
Municipio (Puerto Rico only)municipiotext: The municipio of a Puerto Rico address, in place of a city. Leave empty everywhere else.
Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.
Geography vintagevintagetext: Which year's geography boundaries to report. Tracts and districts are redrawn, so a 2019 address falls in a different tract under a 2019 vintage than under the current one. Match this to the dataset you will query: ACS 2023 data goes with the ACS2023 vintage.Default: Current_Current.
Geography layerslayerslist: Which kinds of area to report. Leave empty for the geocoder's own default set (state, county, tract, block, districts and places), or choose 'All layers' to get everything this vintage publishes.

Outputs

benchmarktext
best_matchobject
inputobject
match_countnumber
matchedtrue/false
matcheslist
vintagetext

Example output

{
  "benchmark": "Public_AR_Current",
  "best_match": {
    "address_components": {
      "city": "WASHINGTON",
      "fromAddress": "4600",
      "preDirection": "",
      "preQualifier": "",
      "preType": "",
      "state": "DC",
      "streetName": "SILVER HILL",
      "suffixDirection": "",
      "suffixQualifier": "",
      "suffixType": "RD",
      "toAddress": "4700",
      "zip": "20233"
    },
    "geography": {
      "block": "",
      "block_geoid": "",
      "block_group": "",
      "block_group_geoid": "",
      "combined_statistical_area": "",
      "congressional_district": "",
      "congressional_district_geoid": "",
      "county_fips": "033",
      "county_geoid": "24033",
      "county_name": "Prince George's County",
      "county_subdivision_fips": "",
      "county_subdivision_name": "",
      "metropolitan_statistical_area": "",
      "place_fips": "",
      "place_name": "",
      "public_use_microdata_area": "",
      "school_district": "",
      "state_abbreviation": "MD",
      "state_fips": "24",
      "state_legislative_district_lower": "",
      "state_legislative_district_upper": "",
      "state_name": "Maryland",
      "tract": "802405",
      "tract_geoid": "24033802405",
      "urban_area": "",
      "zip_code_tabulation_area": ""
    },
    "geography_layers": {
      "Census Tracts": [
        {
          "AREALAND": "3974772",
          "AREAWATER": "8728",
          "BASENAME": "8024.05",
          "CENTLAT": "+38.8553715",
          "CENTLON": "-076.9365872",
          "COUNTY": "033",
          "FUNCSTAT": "S",
          "GEOID": "24033802405",
          "INTPTLAT": "+38.8582393",
          "INTPTLON": "-076.9347941",
          "LSADC": "CT",
          "MTFCC": "G5020",
          "NAME": "Census Tract 8024.05",
          "OBJECTID": 48647,
          "OID": "20790286332785",
          "STATE": "24",
          "TRACT": "802405"
        }
      ]
    },
    "latitude": 38.845053106269,
    "longitude": -76.928365658124,
    "matched_address": "4600 SILVER HILL RD, WASHINGTON, DC, 20233",
    "side": "L",
    "tiger_line_id": "657091557"
  },
  "input": {
    "address": {
      "address": "4600 Silver Hill Rd, Washington, DC 20233"
    },
    "benchmark": {
      "benchmarkDescription": "Public Address Ranges - Current Benchmark",
      "benchmarkName": "Public_AR_Current",
      "id": "4",
      "isDefault": true
    },
    "vintage": {
      "id": "4",
      "isDefault": true,
      "vintageDescription": "Current Vintage - Current Benchmark",
      "vintageName": "Current_Current"
    }
  },
  "match_count": 1,
  "matched": true,
  "matches": [
    {
      "address_components": {
        "city": "WASHINGTON",
        "fromAddress": "4600",
        "preDirection": "",
        "preQualifier": "",
        "preType": "",
        "state": "DC",
        "streetName": "SILVER HILL",
        "suffixDirection": "",
        "suffixQualifier": "",
        "suffixType": "RD",
        "toAddress": "4700",
        "zip": "20233"
      },
      "geography": {
        "block": "",
        "block_geoid": "",
        "block_group": "",
        "block_group_geoid": "",
        "combined_statistical_area": "",
        "congressional_district": "",
        "congressional_district_geoid": "",
        "county_fips": "033",
        "county_geoid": "24033",
        "county_name": "Prince George's County",
        "county_subdivision_fips": "",
        "county_subdivision_name": "",
        "metropolitan_statistical_area": "",
        "place_fips": "",
        "place_name": "",
        "public_use_microdata_area": "",
        "school_district": "",
        "state_abbreviation": "MD",
        "state_fips": "24",
        "state_legislative_district_lower": "",
        "state_legislative_district_upper": "",
        "state_name": "Maryland",
        "tract": "802405",
        "tract_geoid": "24033802405",
        "urban_area": "",
        "zip_code_tabulation_area": ""
      },
      "geography_layers": {
        "Census Tracts": [
          {
            "AREALAND": "3974772",
            "AREAWATER": "8728",
            "BASENAME": "8024.05",
            "CENTLAT": "+38.8553715",
            "CENTLON": "-076.9365872",
            "COUNTY": "033",
            "FUNCSTAT": "S",
            "GEOID": "24033802405",
            "INTPTLAT": "+38.8582393",
            "INTPTLON": "-076.9347941",
            "LSADC": "CT",
            "MTFCC": "G5020",
            "NAME": "Census Tract 8024.05",
            "OBJECTID": 48647,
            "OID": "20790286332785",
            "STATE": "24",
            "TRACT": "802405"
          }
        ]
      },
      "latitude": 38.845053106269,
      "longitude": -76.928365658124,
      "matched_address": "4600 SILVER HILL RD, WASHINGTON, DC, 20233",
      "side": "L",
      "tiger_line_id": "657091557"
    }
  ],
  "vintage": "Current_Current"
}

Look up census areas for many addresses

Find the state, county, tract and block for up to 10,000 addresses at once, along with their coordinates. This is how a customer or patient list gets the tract codes that Census statistics are published against, in one step rather than one per row.

Inputs

AddressesaddresseslistRequired: One row per address. Each needs a street, plus a ZIP code or a city and state. Up to 10,000 rows in one step.
Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.
Geography vintagevintagetext: Which year's geography boundaries to report. Tracts and districts are redrawn, so a 2019 address falls in a different tract under a 2019 vintage than under the current one. Match this to the dataset you will query: ACS 2023 data goes with the ACS2023 vintage.Default: Current_Current.

Outputs

benchmarktext
countnumber
match_rate_percentnumber
matched_countnumber
resultslist
submittednumber
tie_countnumber
unmatched_countnumber
vintagetext

Example output

{
  "benchmark": "Public_AR_Current",
  "count": 1,
  "match_rate_percent": 100.0,
  "matched_count": 1,
  "results": [
    {
      "block": "2004",
      "county_fips": "033",
      "id": "hq",
      "input_address": "4600 Silver Hill Rd, Washington, DC, 20233",
      "latitude": 38.845053106269,
      "longitude": -76.928365658124,
      "match_status": "Match",
      "match_type": "Exact",
      "matched": true,
      "matched_address": "4600 SILVER HILL RD, WASHINGTON, DC, 20233",
      "side": "L",
      "state_fips": "24",
      "tiger_line_id": "657091557",
      "tract": "802405"
    }
  ],
  "submitted": 1,
  "tie_count": 0,
  "unmatched_count": 0,
  "vintage": "Current_Current"
}

Look up census areas for many points

Find the state, county, tract and block for up to 10,000 latitude/longitude points at once. For points that came from a map, a device, a fleet log or another geocoder, where there are no addresses to send.

Inputs

PointscoordinateslistRequired: One row per point, each with a longitude and a latitude in decimal degrees. Up to 10,000 rows in one step.
Benchmarkbenchmarktext: Which snapshot of the Census address ranges to match against. Leave on the current one unless you are reproducing an older result.Default: Public_AR_Current.
Geography vintagevintagetext: Which year's geography boundaries to report. Tracts and districts are redrawn, so a 2019 address falls in a different tract under a 2019 vintage than under the current one. Match this to the dataset you will query: ACS 2023 data goes with the ACS2023 vintage.Default: Current_Current.

Outputs

benchmarktext
countnumber
match_rate_percentnumber
matched_countnumber
resultslist
submittednumber
tie_countnumber
unmatched_countnumber
vintagetext

Example output

{
  "benchmark": "Public_AR_Current",
  "count": 1,
  "match_rate_percent": 100.0,
  "matched_count": 1,
  "results": [
    {
      "block": "1034",
      "county_fips": "001",
      "id": "wh",
      "latitude": 38.89869,
      "longitude": -77.03518,
      "match_status": "Match",
      "matched": true,
      "state_fips": "11",
      "tract": "980000"
    }
  ],
  "submitted": 1,
  "tie_count": 0,
  "unmatched_count": 0,
  "vintage": "Current_Current"
}

Search datasets

Search the roughly 1,800 datasets the Census Data API publishes (the American Community Survey, the Decennial Census, Population Estimates, County Business Patterns, International Trade and the rest), and get the exact path each one answers on, which every other action needs. Filter by year, by keyword, or by whether a dataset holds published totals, individual records or a run of years.

Inputs

Searchsearchtext: Narrow the list to entries containing every word you type. Leave empty to list everything.
Yearvintagetext: Limit to one year of data, such as 2023, or to 'timeseries' for the datasets that span years. Leave empty to search every dataset.
Kind of datasetdataset_typetext: Limit to one kind. Aggregate datasets publish totals for an area and are what most workflows want; microdata publishes one record per person or household.One of: aggregate (Aggregate: published totals for an area), microdata (Microdata: one record per person or household), timeseries (Time series: one dataset spanning many years).
How many to returnlimitnumber: How many results to return in one step, up to 500.From 1 to 500. Default: 50.
Skipoffsetnumber: How many results to skip before returning any; chain the previous step's 'next offset' here to walk a long list.From 0 to 1000000. Default: 0.

Outputs

countnumber
datasetslist
has_moretrue/false
next_offsetnumber
offsetnumber
total_matchesnumber

Example output

{
  "count": 1,
  "datasets": [
    {
      "access_url": "https://api.census.gov/data/2023/acs/acs5",
      "api_path": "2023/acs/acs5",
      "contact_email": "acso.users.support@census.gov",
      "contact_name": "American Community Survey Office",
      "dataset": "acs/acs5",
      "description": "The American Community Survey (ACS) is an ongoing survey that provides data every year -- giving communities the current information they need to plan investments and services. The ACS covers a broad range of topics about social, economic, demographic, and housing characteristics of the U.S. population. Summary files include the following geographies: nation, all states (including DC and Puerto Rico), all metropolitan areas, all congressional districts, all counties, all places, and all tracts and block groups. Summary files contain the most detailed cross-tabulations, many of which are published down to block groups. The data are population and housing counts. There are over 64,000 variables in this dataset.",
      "documentation_url": "https://www.census.gov/developer/",
      "examples_url": "https://api.census.gov/data/2023/acs/acs5/examples.json",
      "geography_url": "https://api.census.gov/data/2023/acs/acs5/geography.json",
      "groups_url": "https://api.census.gov/data/2023/acs/acs5/groups.json",
      "is_aggregate": true,
      "is_available": true,
      "is_microdata": false,
      "is_timeseries": false,
      "modified": "2024-09-06 17:27:47.0",
      "spatial": "US",
      "tags_url": "https://api.census.gov/data/2023/acs/acs5/tags.json",
      "temporal": "2023/2023",
      "title": "ACS 5-Year Detailed Tables",
      "variables_url": "https://api.census.gov/data/2023/acs/acs5/variables.json",
      "vintage": 2023
    }
  ],
  "has_more": false,
  "next_offset": 1,
  "offset": 0,
  "total_matches": 1
}

Search tables

Search a dataset's tables by subject: 'median household income', 'commuting', 'housing tenure'. Get each one's code and the population it describes. A table is the unit the Census Bureau publishes in, so finding the right one is usually the fastest route to the right numbers.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
Searchsearchtext: Narrow the list to entries containing every word you type. Leave empty to list everything.
How many to returnlimitnumber: How many results to return in one step, up to 500.From 1 to 500. Default: 50.
Skipoffsetnumber: How many results to skip before returning any; chain the previous step's 'next offset' here to walk a long list.From 0 to 1000000. Default: 0.

Outputs

countnumber
datasettext
groupslist
has_moretrue/false
next_offsetnumber
offsetnumber
total_matchesnumber

Example output

{
  "count": 2,
  "dataset": "2023/acs/acs5",
  "groups": [
    {
      "description": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "name": "B19013",
      "universe": "Households",
      "variables_url": "https://api.census.gov/data/2023/acs/acs5/groups/B19013.json"
    },
    {
      "description": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars) (White Alone Householder)",
      "name": "B19013A",
      "universe": "Households with a householder who is White alone",
      "variables_url": "https://api.census.gov/data/2023/acs/acs5/groups/B19013A.json"
    }
  ],
  "has_more": true,
  "next_offset": 2,
  "offset": 0,
  "total_matches": 37
}

Search variables

Find the code for a statistic by searching a dataset's variables on the words in their labels: 'median gross rent', 'without health insurance', 'bachelor's degree'. Returns each code with its label, the table it belongs to and the population it is measured over. Every data query is written in these codes, and this is how you find them.

Inputs

DatasetdatasettextRequired: Which Census dataset to read. Pick from the list; it is every dataset the API publishes, newest first. The American Community Survey's 5-year detailed tables are the usual choice for anything below state level, because they are the only ones published for small areas.
Searchsearchtext: Narrow the list to entries containing every word you type. Leave empty to list everything.
Tablegrouptext: Search inside one table only. Leave empty to search the whole dataset.
How many to returnlimitnumber: How many results to return in one step, up to 500.From 1 to 500. Default: 50.
Skipoffsetnumber: How many results to skip before returning any; chain the previous step's 'next offset' here to walk a long list.From 0 to 1000000. Default: 0.

Outputs

countnumber
datasettext
grouptext
has_moretrue/false
next_offsetnumber
offsetnumber
total_matchesnumber
variableslist

Example output

{
  "count": 2,
  "dataset": "2023/acs/acs5",
  "group": "B19013",
  "has_more": true,
  "next_offset": 2,
  "offset": 0,
  "total_matches": 4,
  "variables": [
    {
      "attributes": "",
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "group": "B19013",
      "label": "Estimate!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001E",
      "predicate_only": true,
      "predicate_type": "int",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    },
    {
      "attributes": "",
      "concept": "Median Household Income in the Past 12 Months (in 2023 Inflation-Adjusted Dollars)",
      "group": "B19013",
      "label": "Annotation of Estimate!!Median household income in the past 12 months (in 2023 inflation-adjusted dollars)",
      "name": "B19013_001EA",
      "predicate_only": true,
      "predicate_type": "string",
      "required": false,
      "universe": "Households",
      "value_count": 0,
      "values": {},
      "values_truncated": false
    }
  ]
}

ActionsCopy Anchor Link

Describe a tableCopy Anchor Link

Inputs

Outputs

Geocode an addressCopy Anchor Link

Inputs

Outputs

Geocode many addressesCopy Anchor Link

Inputs

Outputs

Get a whole tableCopy Anchor Link

Inputs

Outputs

Get dataCopy Anchor Link

Inputs

Outputs

Get data for an addressCopy Anchor Link

Inputs

Outputs

Get dataset detailsCopy Anchor Link

Inputs

Outputs

Get example queryCopy Anchor Link

Inputs

Outputs

Get variable detailsCopy Anchor Link

Inputs

Outputs

List dataset topicsCopy Anchor Link

Inputs

Outputs

List geocoder benchmarksCopy Anchor Link

Inputs

Outputs

List geography codesCopy Anchor Link

Inputs

Outputs

List geography levelsCopy Anchor Link

Inputs

Outputs

List geography vintagesCopy Anchor Link

Inputs

Outputs

Look up a point's census areasCopy Anchor Link

Inputs

Outputs

Look up an address's census areasCopy Anchor Link

Inputs

Outputs

Look up census areas for many addressesCopy Anchor Link

Inputs

Outputs

Look up census areas for many pointsCopy Anchor Link

Inputs

Outputs

Search datasetsCopy Anchor Link

Inputs

Outputs

Search tablesCopy Anchor Link

Inputs

Outputs

Search variablesCopy Anchor Link

Inputs

Outputs

On this page

Actions

Describe a table

Geocode an address

Geocode many addresses

Get a whole table

Get data

Get data for an address

Get dataset details

Get example query

Get variable details

List dataset topics

List geocoder benchmarks

List geography codes

List geography levels

List geography vintages

Look up a point's census areas

Look up an address's census areas

Look up census areas for many addresses

Look up census areas for many points

Search datasets

Search tables

Search variables