naftiko: 1.0.0-alpha2
info:
  label: Census Bureau Demographic Research
  description: Unified workflow capability for accessing U.S. Census Bureau statistical data for demographic research, economic
    analysis, geographic enrichment, and population studies. Combines the Census Data API, Geocoding Services, and TIGERweb
    geographic data into workflows for researchers, analysts, and application developers.
  tags:
  - Demographics
  - Federal Government
  - Open Data
  - Statistics
  - Population
  - Economics
  - Geography
  created: '2026-05-03'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: census
    baseUri: https://api.census.gov/data
    description: U.S. Census Bureau Data API
    resources:
    - name: acs5
      path: /{year}/acs/acs5
      description: American Community Survey 5-Year Estimates
      operations:
      - name: get-acs5
        method: GET
        description: Returns ACS 5-Year demographic, economic, social, and housing data
        inputParameters:
        - name: year
          in: path
          type: integer
          required: true
          description: ACS 5-Year end year (2009-2024)
        - name: get
          in: query
          type: string
          required: true
          description: Comma-separated variable names to retrieve (max 50)
        - name: for
          in: query
          type: string
          required: false
          description: Geography filter (e.g., state:06, county:*&in=state:06)
        - name: in
          in: query
          type: string
          required: false
          description: Parent geography constraint for sub-state geographies
        - name: key
          in: query
          type: string
          required: false
          description: Census API key for higher usage limits
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
    - name: acs1
      path: /{year}/acs/acs1
      description: American Community Survey 1-Year Estimates
      operations:
      - name: get-acs1
        method: GET
        description: Returns ACS 1-Year data for geographies with 65,000+ population
        inputParameters:
        - name: year
          in: path
          type: integer
          required: true
          description: ACS 1-Year year (2005-2024)
        - name: get
          in: query
          type: string
          required: true
          description: Comma-separated variable names to retrieve
        - name: for
          in: query
          type: string
          required: false
          description: Geography filter
        - name: in
          in: query
          type: string
          required: false
          description: Parent geography constraint
        - name: key
          in: query
          type: string
          required: false
          description: Census API key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
    - name: decennial
      path: /{year}/dec/pl
      description: Decennial Census Redistricting Data
      operations:
      - name: get-decennial
        method: GET
        description: Returns Decennial Census population counts by race/ethnicity
        inputParameters:
        - name: year
          in: path
          type: integer
          required: true
          description: Census year (2020 or 2010)
        - name: get
          in: query
          type: string
          required: true
          description: Variable names to retrieve
        - name: for
          in: query
          type: string
          required: false
          description: Geography filter
        - name: key
          in: query
          type: string
          required: false
          description: Census API key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
    - name: population-estimates
      path: /{year}/pep/population
      description: Annual Population Estimates
      operations:
      - name: get-population-estimates
        method: GET
        description: Returns annual population estimates for states and counties
        inputParameters:
        - name: year
          in: path
          type: integer
          required: true
          description: Estimates vintage year
        - name: get
          in: query
          type: string
          required: true
          description: Variable names (e.g., NAME,POP,DATE_DESC)
        - name: for
          in: query
          type: string
          required: false
          description: Geography filter
        - name: key
          in: query
          type: string
          required: false
          description: Census API key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
    - name: cbp
      path: /{year}/cbp
      description: County Business Patterns
      operations:
      - name: get-county-business-patterns
        method: GET
        description: Returns business establishment, employment, and payroll data
        inputParameters:
        - name: year
          in: path
          type: integer
          required: true
          description: Data year (1986-2022)
        - name: get
          in: query
          type: string
          required: true
          description: Variable names (e.g., NAME,NAICS2017,ESTAB,EMP,PAYANN)
        - name: for
          in: query
          type: string
          required: false
          description: Geography filter
        - name: key
          in: query
          type: string
          required: false
          description: Census API key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: census-research-api
    description: Unified REST API for Census Bureau demographic and economic data access.
    resources:
    - path: /v1/demographics/{year}/acs5
      name: acs5-demographics
      description: ACS 5-Year demographic, economic, social, and housing estimates
      operations:
      - method: GET
        name: get-acs5-demographics
        description: Get ACS 5-Year estimates for any US geography down to block group
        call: census.get-acs5
        with:
          year: rest.year
          get: rest.get
          for: rest.for
          in: rest.in
        outputParameters:
        - type: array
          mapping: $.
    - path: /v1/demographics/{year}/acs1
      name: acs1-demographics
      description: ACS 1-Year demographic estimates for large geographies
      operations:
      - method: GET
        name: get-acs1-demographics
        description: Get ACS 1-Year estimates for geographies with 65,000+ population
        call: census.get-acs1
        with:
          year: rest.year
          get: rest.get
          for: rest.for
        outputParameters:
        - type: array
          mapping: $.
    - path: /v1/population/{year}/estimates
      name: population-estimates
      description: Annual population estimates by geography
      operations:
      - method: GET
        name: get-population-estimates
        description: Get annual population estimates using births, deaths, and migration data
        call: census.get-population-estimates
        with:
          year: rest.year
          get: rest.get
          for: rest.for
        outputParameters:
        - type: array
          mapping: $.
    - path: /v1/census/{year}/decennial
      name: decennial-counts
      description: Decennial Census population counts
      operations:
      - method: GET
        name: get-decennial-data
        description: Get official Decennial Census population counts by geography and race
        call: census.get-decennial
        with:
          year: rest.year
          get: rest.get
          for: rest.for
        outputParameters:
        - type: array
          mapping: $.
    - path: /v1/economy/{year}/business-patterns
      name: business-patterns
      description: County Business Patterns economic data
      operations:
      - method: GET
        name: get-business-patterns
        description: Get business establishment counts, employment, and payroll by industry
        call: census.get-county-business-patterns
        with:
          year: rest.year
          get: rest.get
          for: rest.for
        outputParameters:
        - type: array
          mapping: $.
  - type: mcp
    port: 9090
    namespace: census-research-mcp
    transport: http
    description: MCP server for AI-assisted demographic research and census data analysis.
    tools:
    - name: query-demographic-data
      description: Query ACS 5-Year demographic data (population, income, education, housing) for any US geography from national
        down to block group level
      hints:
        readOnly: true
        openWorld: true
      call: census.get-acs5
      with:
        year: tools.year
        get: tools.get
        for: tools.for
        in: tools.in
      outputParameters:
      - type: array
        mapping: $.
    - name: query-acs-1year
      description: Query ACS 1-Year demographic data for large geographies (65,000+ population) with more current estimates
      hints:
        readOnly: true
        openWorld: true
      call: census.get-acs1
      with:
        year: tools.year
        get: tools.get
        for: tools.for
        in: tools.in
      outputParameters:
      - type: array
        mapping: $.
    - name: query-population-estimates
      description: Get annual population estimates for states and counties, including historical estimates back to the last
        decennial census
      hints:
        readOnly: true
        openWorld: true
      call: census.get-population-estimates
      with:
        year: tools.year
        get: tools.get
        for: tools.for
      outputParameters:
      - type: array
        mapping: $.
    - name: query-decennial-census
      description: Get official Decennial Census population counts from 2020 or 2010, with data by race/ethnicity at all geographic
        levels
      hints:
        readOnly: true
        openWorld: true
      call: census.get-decennial
      with:
        year: tools.year
        get: tools.get
        for: tools.for
      outputParameters:
      - type: array
        mapping: $.
    - name: query-business-statistics
      description: Get economic data on business establishments, employment counts, and payroll by industry (NAICS) and geography
        from County Business Patterns
      hints:
        readOnly: true
        openWorld: true
      call: census.get-county-business-patterns
      with:
        year: tools.year
        get: tools.get
        for: tools.for
      outputParameters:
      - type: array
        mapping: $.