openapi: 3.1.0
info:
  title: Census Data American Community Survey API
  description: The United States Census Bureau Data API provides programmatic access to statistical data from Census Bureau surveys and datasets. The API covers demographic, economic, housing, and social data through a query-based interface. Key datasets include the American Community Survey (ACS), Decennial Census, Population Estimates, County Business Patterns, and many more. Users can query data by geographic level (national, state, county, tract, block group) and filter by hundreds of statistical variables. An API key is optional (up to 500 requests/day without one) but required for higher usage.
  version: 2.0.0
  contact:
    name: Census Developer Forum
    url: https://www.census.gov/data/developers.html
    email: cnmp.developers.list@census.gov
  x-tags:
  - Demographics
  - Federal Government
  - Open Data
  - Statistics
servers:
- url: https://api.census.gov/data
  description: Census Data API
tags:
- name: American Community Survey
  description: ACS demographic, economic, social, and housing characteristics
paths:
  /{year}/acs/acs1:
    get:
      operationId: getACS1Year
      summary: Get ACS 1-Year Data
      description: Returns American Community Survey 1-Year Estimates for geographies with populations of 65,000 or more. Covers social, economic, demographic, and housing characteristics. Data available from 2005 to present.
      tags:
      - American Community Survey
      parameters:
      - name: year
        in: path
        required: true
        description: Data year (2005-2024)
        schema:
          type: integer
          minimum: 2005
          maximum: 2024
      - name: get
        in: query
        required: true
        description: Comma-separated list of variable names to retrieve (e.g., NAME,B01003_001E for name and total population). Maximum 50 variables per query.
        schema:
          type: string
      - name: for
        in: query
        required: false
        description: Geographic level and FIPS code filter (e.g., state:01 for Alabama, county:*&in=state:06 for all CA counties)
        schema:
          type: string
      - name: in
        in: query
        required: false
        description: Parent geography constraint for sub-state geographies (e.g., state:06 to restrict to California)
        schema:
          type: string
      - name: key
        in: query
        required: false
        description: Census API key for higher usage limits (500+ requests/day)
        schema:
          type: string
      responses:
        '200':
          description: 2D JSON array where the first row contains variable names and subsequent rows contain data values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /{year}/acs/acs5:
    get:
      operationId: getACS5Year
      summary: Get ACS 5-Year Data
      description: Returns American Community Survey 5-Year Estimates for all geographies down to block group level. More reliable for small populations and small geographies. Data available from 2009 to present.
      tags:
      - American Community Survey
      parameters:
      - name: year
        in: path
        required: true
        description: End year of the 5-year period (2009-2024)
        schema:
          type: integer
          minimum: 2009
          maximum: 2024
      - name: get
        in: query
        required: true
        description: Comma-separated variable names (e.g., NAME,B01003_001E,B19013_001E for name, total population, and median household income)
        schema:
          type: string
      - name: for
        in: query
        required: false
        description: Geographic level and FIPS code filter
        schema:
          type: string
      - name: in
        in: query
        required: false
        description: Parent geography constraint
        schema:
          type: string
      - name: key
        in: query
        required: false
        description: Census API key
        schema:
          type: string
      responses:
        '200':
          description: 2D JSON array of ACS 5-Year data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  responses:
    BadRequest:
      description: Bad request — invalid parameters, missing required fields, or variable not found
      content:
        text/html:
          schema:
            type: string
  schemas:
    DataAPIResponse:
      type: array
      description: A 2D JSON array where the first element is an array of variable names (headers) and each subsequent element is an array of corresponding data values. The last elements in each row are typically geography codes.
      items:
        type: array
        description: A single data row (header row or data row)
        items:
          type: string
          nullable: true
      example:
      - - NAME
        - B01003_001E
        - state
      - - Alabama
        - '5024279'
        - '01'
      - - Alaska
        - '733391'
        - '02'
      - - Arizona
        - '7151502'
        - '04'
externalDocs:
  description: Census Data API User Guide
  url: https://www.census.gov/data/developers/guidance/api-user-guide.html