Census.gov Getting Started: API Access and First Request (2026)

Getting started overview

To begin programmatic access to data from the U.S. Census Bureau, developers need to follow a series of steps that include requesting an API key and understanding the basic structure of Census Bureau API calls. The Census Bureau API offers access to a wide range of public datasets, including the Decennial Census, American Community Survey (ACS), and economic data. All data available through the API is free to access and use, requiring only registration for an API key to manage usage and prevent abuse.

The process generally involves navigating the Census Bureau's developer portal, where documentation for different API endpoints and datasets is provided. Once an API key is obtained, it must be included in requests to authenticate and retrieve data. The API supports standard web protocols and typically returns data in JSON format, facilitating integration with various programming languages and applications. The Census Bureau API user guide serves as the primary resource for detailed technical specifications and examples.

Create an account and get keys

Accessing the majority of Census Bureau API endpoints requires an API key. This key helps the Census Bureau monitor usage and ensures fair access for all users. The process for obtaining a key is straightforward and does not involve any fees.

Key acquisition steps

1. Navigate to the Census API Key Request Page: Go to the official Census Bureau Developers page.
2. Locate the API Key Request Form: Look for a section titled "Request a Key" or similar. You may need to scroll down or follow a specific link on the developer guidance page.
3. Submit Your Information: The form typically asks for basic contact information, such as your name, organization (optional), and email address. You may also be asked to agree to terms of service regarding API usage.
4. Receive Your API Key: After submitting the form, your API key will usually be sent to the email address you provided. This process is generally automated and should deliver the key within a few minutes. Check your spam folder if you do not receive it promptly.
5. Store Your Key Securely: Treat your API key like a password. Do not hardcode it directly into client-side code, and consider using environment variables or a secure configuration management system for server-side applications.

The Census Bureau does not impose strict rate limits for most general use cases, but fair use policies apply. Your API key helps the Bureau track usage patterns and manage the service. For applications requiring very high request volumes, contact the Census Bureau support for guidance.

Your first request

After obtaining your API key, you can make your first request. This example demonstrates how to query a common dataset, the American Community Survey (ACS), for basic demographic information.

Example: American Community Survey (ACS) data

The ACS provides detailed demographic, social, economic, and housing characteristics for various geographic areas. We'll fetch the median household income for all counties in a specific state.

Request structure

Census API requests follow a common structure:

https://api.census.gov/data/<year>/<dataset>/<variable_group>?get=<variables>&for=<geography>&in=<parent_geography>&key=<YOUR_API_KEY>

• <year>: The year of the dataset (e.g., 2022).
• <dataset>: The specific dataset (e.g., acs/acs5 for the 5-year ACS estimates).
• <variable_group>: Often omitted for direct variable queries, or used for specific topics.
• <variables>: Comma-separated list of data variables to retrieve (e.g., NAME,B19013_001E for median household income and geographic name).
• <geography>: The target geography (e.g., county:* for all counties).
• <parent_geography>: The containing geography (e.g., state:06 for California).
• <YOUR_API_KEY>: Your personal API key.

Example data definitions:

• Dataset: acs/acs5 (2022 American Community Survey 5-year estimates)
• Variable: B19013_001E (Estimate for Median Household Income)
• Geography: county:* (All counties)
• Parent Geography: state:06 (California)
• Year: 2022

Full example request URL (replace YOUR_API_KEY):

https://api.census.gov/data/2022/acs/acs5?get=NAME,B19013_001E&for=county:*&in=state:06&key=YOUR_API_KEY

Using curl to make the request:

curl "https://api.census.gov/data/2022/acs/acs5?get=NAME,B19013_001E&for=county:*&in=state:06&key=YOUR_API_KEY"

Expected JSON response structure:

The API returns a JSON array. The first element of the array is an array of column headers. Subsequent elements are arrays of data rows.

[
  ["NAME", "B19013_001E", "state", "county"],
  ["Los Angeles County, California", "84947", "06", "037"],
  ["Orange County, California", "109919", "06", "059"],
  // ... more counties
]

This response provides the county name, median household income estimate, state FIPS code, and county FIPS code. For more information on FIPS codes, refer to the Census Bureau's FIPS code documentation.

Common next steps

Once you've made your first successful API call, consider these next steps to deepen your engagement with Census Bureau data:

Troubleshooting the first call

If your initial API call isn't returning data as expected, consider these common troubleshooting steps:

• Verify your API Key: Ensure your API key is correctly included in the request URL and that it hasn't expired or been revoked. Double-check for typos.
• Check the Base URL: Confirm that you're using the correct base URL (https://api.census.gov/data/) and the appropriate year and dataset segments.
• Correct Variable Names: Census Bureau variables are case-sensitive and specific. Consult the Census API variables documentation to ensure you're using the exact variable identifiers (e.g., B19013_001E, not medianincome).
• Valid Geography: Ensure your geographic parameters (for and in) are correctly formatted and correspond to valid FIPS codes or geographic specifications. For instance, state:06 is for California, and county:* requests all counties within the specified parent geography.
• Review Documentation for Dataset Specifics: Some datasets may have unique requirements for parameters or available years. Always refer to the specific dataset documentation.
• Network Issues: Temporarily disable any VPNs or firewalls to rule out local network restrictions preventing access to the Census API domain.
• Rate Limiting: While generally generous, excessive rapid requests could trigger temporary rate limits. If you suspect this, wait a few minutes and try again.
• Error Messages: Pay close attention to any error messages returned in the API response. These messages often provide specific clues about what went wrong (e.g., "invalid API key," "bad geography parameter"). Reference the Census API error codes for explanations.
• Use a Browser: Paste your full API request URL (with your API key) directly into a web browser. This can often reveal immediate error messages or show the JSON response, helping to debug syntax.