# 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. App · Misc References · 21 actions. Web page: https://docs.lodol.com/docs/integrations/us-census ## Actions ### 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** - Dataset (`dataset`, text, required): 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 (`group`, text, required): The table to describe. Pick from the list, or chain in a table code from 'Search tables'. **Outputs** - `concept` (text) - `dataset` (text) - `group` (text) - `variable_count` (number) - `variables` (list) **Example output** ```json { "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) (`address`, text): 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 address (`street`, text): House number and street. Needed if you are not using the one-line field above. - City (`city`, text): City or town. Give this and the state, or give a ZIP code. - State (`state`, text): Two-letter state code, such as DC or CA. Give this and the city, or give a ZIP code. - ZIP code (`zip_code`, text): Five-digit ZIP code. A street plus a ZIP code is enough on its own. - Urbanización (Puerto Rico only) (`urbanization`, text): 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) (`municipio`, text): The municipio of a Puerto Rico address, in place of a city. Leave empty everywhere else. - Benchmark (`benchmark`, text): 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** - `benchmark` (text) - `best_match` (object) - `input` (object) - `match_count` (number) - `matched` (true/false) - `matches` (list) - `vintage` (text) **Example output** ```json { "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** - Addresses (`addresses`, list, required): 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. - Benchmark (`benchmark`, text): 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** - `benchmark` (text) - `count` (number) - `match_rate_percent` (number) - `matched_count` (number) - `results` (list) - `submitted` (number) - `tie_count` (number) - `unmatched_count` (number) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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 (`group`, text, required): Which table to pull. Pick from the list, or chain in a code from 'Search tables'. - Geography level (`geography_level`, text, required): 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 areas (`geography_codes`, text): 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: `*`. - State (`state`, text): 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) (`within`, text): 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_ids`, text): 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 columns (`columns`, text): 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** - `annotations` (list) - `column_labels` (list) - `columns` (list) - `columns_returned` (text) - `concept` (text) - `dataset` (text) - `group` (text) - `has_annotated_values` (true/false) - `numeric_columns` (list) - `query_url` (text) - `row_count` (number) - `rows` (list) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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) (`table`, text, required): 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: `*`. - Variables (`variables`, list, required): 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 level (`geography_level`, text, required): 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 areas (`geography_codes`, text): 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: `*`. - State (`state`, text): 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) (`within`, text): 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_ids`, text): 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. - Filters (`filters`, object): 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 period (`time_period`, text): 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** - `annotations` (list) - `columns` (list) - `dataset` (text) - `has_annotated_values` (true/false) - `numeric_columns` (list) - `query_url` (text) - `row_count` (number) - `rows` (list) **Example output** ```json { "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) (`address`, text): 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 address (`street`, text): House number and street. Needed if you are not using the one-line field above. - City (`city`, text): City or town. Give this and the state, or give a ZIP code. - State (`state`, text): Two-letter state code, such as DC or CA. Give this and the city, or give a ZIP code. - ZIP code (`zip_code`, text): Five-digit ZIP code. A street plus a ZIP code is enough on its own. - Dataset (`dataset`, text, required): 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) (`table`, text, required): 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: `*`. - Variables (`variables`, list): Which statistics to return for the area. Leave empty if you are pulling a whole table below instead. - Whole table (instead of variables) (`group`, text): Pull an entire table for the area instead of picking variables. Leave empty if you chose variables above. - Area type (`geography_level`, text): 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`. - Benchmark (`benchmark`, text): 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 vintage (`vintage`, text): 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** - `data` (object) - `dataset` (text) - `geography` (object) - `geography_code` (text) - `geography_level` (text) - `latitude` (number) - `longitude` (number) - `matched_address` (text) - `row` (object) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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_url` (text) - `api_path` (text) - `contact_email` (text) - `contact_name` (text) - `dataset` (text) - `description` (text) - `documentation_url` (text) - `examples_url` (text) - `geography_levels` (list) - `geography_url` (text) - `groups_url` (text) - `is_aggregate` (true/false) - `is_available` (true/false) - `is_microdata` (true/false) - `is_timeseries` (true/false) - `modified` (text) - `spatial` (text) - `tags_url` (text) - `temporal` (text) - `title` (text) - `variables_url` (text) - `vintage` (number) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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** - `count` (number) - `dataset` (text) - `example_variables` (list) - `geographies` (list) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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. - Variable (`variable`, text, required): The variable code to look up, such as B19013_001E. **Outputs** - `attributes` (text) - `concept` (text) - `dataset` (text) - `group` (text) - `label` (text) - `name` (text) - `predicate_only` (true/false) - `predicate_type` (text) - `required` (true/false) - `universe` (text) - `value_count` (number) - `values` (object) - `values_truncated` (true/false) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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** - `count` (number) - `dataset` (text) - `tags` (list) **Example output** ```json { "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** - `benchmarks` (list) - `count` (number) - `default_benchmark` (text) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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 level (`geography_level`, text, required): 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. - State (`state`, text): 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) (`within`, text): 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. - Search (`search`, text): Narrow the list to entries containing every word you type. Leave empty to list everything. - How many to return (`limit`, number): 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** - `areas` (list) - `count` (number) - `dataset` (text) - `geography_level` (text) - `query_url` (text) - `total_matches` (number) - `truncated` (true/false) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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** - `count` (number) - `dataset` (text) - `geography_levels` (list) - `level_names` (list) **Example output** ```json { "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** - Benchmark (`benchmark`, text): 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** - `benchmark` (text) - `count` (number) - `default_vintage` (text) - `vintages` (list) **Example output** ```json { "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** - Longitude (`longitude`, number, required): Longitude in decimal degrees. Negative everywhere in the United States, so -77.0352 is Washington, DC. From -180 to 180. - Latitude (`latitude`, number, required): Latitude in decimal degrees, such as 38.8987. From -90 to 90. - Benchmark (`benchmark`, text): 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 vintage (`vintage`, text): 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 layers (`layers`, list): 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** - `benchmark` (text) - `geography` (object) - `geography_layers` (object) - `latitude` (number) - `longitude` (number) - `matched` (true/false) - `vintage` (text) **Example output** ```json { "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) (`address`, text): 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 address (`street`, text): House number and street. Needed if you are not using the one-line field above. - City (`city`, text): City or town. Give this and the state, or give a ZIP code. - State (`state`, text): Two-letter state code, such as DC or CA. Give this and the city, or give a ZIP code. - ZIP code (`zip_code`, text): Five-digit ZIP code. A street plus a ZIP code is enough on its own. - Urbanización (Puerto Rico only) (`urbanization`, text): 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) (`municipio`, text): The municipio of a Puerto Rico address, in place of a city. Leave empty everywhere else. - Benchmark (`benchmark`, text): 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 vintage (`vintage`, text): 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 layers (`layers`, list): 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** - `benchmark` (text) - `best_match` (object) - `input` (object) - `match_count` (number) - `matched` (true/false) - `matches` (list) - `vintage` (text) **Example output** ```json { "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** - Addresses (`addresses`, list, required): 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. - Benchmark (`benchmark`, text): 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 vintage (`vintage`, text): 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** - `benchmark` (text) - `count` (number) - `match_rate_percent` (number) - `matched_count` (number) - `results` (list) - `submitted` (number) - `tie_count` (number) - `unmatched_count` (number) - `vintage` (text) **Example output** ```json { "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** - Points (`coordinates`, list, required): One row per point, each with a longitude and a latitude in decimal degrees. Up to 10,000 rows in one step. - Benchmark (`benchmark`, text): 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 vintage (`vintage`, text): 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** - `benchmark` (text) - `count` (number) - `match_rate_percent` (number) - `matched_count` (number) - `results` (list) - `submitted` (number) - `tie_count` (number) - `unmatched_count` (number) - `vintage` (text) **Example output** ```json { "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** - Search (`search`, text): Narrow the list to entries containing every word you type. Leave empty to list everything. - Year (`vintage`, text): 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 dataset (`dataset_type`, text): 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 return (`limit`, number): How many results to return in one step, up to 500. From 1 to 500. Default: `50`. - Skip (`offset`, number): 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** - `count` (number) - `datasets` (list) - `has_more` (true/false) - `next_offset` (number) - `offset` (number) - `total_matches` (number) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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. - Search (`search`, text): Narrow the list to entries containing every word you type. Leave empty to list everything. - How many to return (`limit`, number): How many results to return in one step, up to 500. From 1 to 500. Default: `50`. - Skip (`offset`, number): 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** - `count` (number) - `dataset` (text) - `groups` (list) - `has_more` (true/false) - `next_offset` (number) - `offset` (number) - `total_matches` (number) **Example output** ```json { "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** - Dataset (`dataset`, text, required): 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. - Search (`search`, text): Narrow the list to entries containing every word you type. Leave empty to list everything. - Table (`group`, text): Search inside one table only. Leave empty to search the whole dataset. - How many to return (`limit`, number): How many results to return in one step, up to 500. From 1 to 500. Default: `50`. - Skip (`offset`, number): 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** - `count` (number) - `dataset` (text) - `group` (text) - `has_more` (true/false) - `next_offset` (number) - `offset` (number) - `total_matches` (number) - `variables` (list) **Example output** ```json { "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 } ] } ```