openapi: 3.2.0
info:
  title: FCC Area and Census Block API
  description: 'The FCC Area and Census Block API returns US Census Bureau Census Block FIPS codes, county FIPS codes, state FIPS codes, and associated US State and County names based on latitude and longitude coordinates. Also returns market data and population data. All endpoints are free with no authentication required.

    '
  version: 1.0.0
  contact:
    name: Federal Communications Commission
    url: https://www.fcc.gov/census-block-conversions-api
  license:
    name: FCC API Terms of Service
    url: https://www.fcc.gov/reports-research/developers/api-terms-service
servers:
- url: https://geo.fcc.gov/api/census
  description: FCC Census/Area API
tags:
- name: block
  description: Get census block, county, and state FIPS codes by latitude and longitude
paths:
  /block/find:
    get:
      tags:
      - block
      operationId: findBlock
      summary: Get Census Block FIPS by Latitude and Longitude
      description: 'Returns the US Census Bureau Census Block FIPS code, county FIPS code, and state FIPS code for a given latitude and longitude. Also returns the associated US State and County names.

        '
      parameters:
      - name: latitude
        in: query
        required: true
        description: 'Latitude in decimal degrees or DMS format. Range: -90 to 90. Examples: 38.26 or 38:15:36N

          '
        schema:
          type: string
      - name: longitude
        in: query
        required: true
        description: 'Longitude in decimal degrees or DMS format. Range: -180 to 180. Examples: -77.51 or 77:30:36W

          '
        schema:
          type: string
      - name: censusYear
        in: query
        required: false
        description: 'Census year for results. Valid values: 2010, 2020 (default)'
        schema:
          type: integer
          enum:
          - 2010
          - 2020
          default: 2020
      - name: showall
        in: query
        required: false
        description: 'If the coordinate lies on the boundary of multiple geographies, use showall=true to return the complete list.

          '
        schema:
          type: boolean
          default: false
      - name: format
        in: query
        required: false
        description: Response format. Defaults to xml.
        schema:
          type: string
          enum:
          - xml
          - json
          - jsonp
          default: xml
      responses:
        '200':
          description: Census block, county, and state data for the specified location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockResponse'
            text/xml:
              schema:
                type: string
components:
  schemas:
    BlockResponse:
      type: object
      properties:
        Block:
          type: object
          properties:
            FIPS:
              type: string
              description: Full Census Block FIPS code (15 digits)
              example: '110010083011001'
            bbox:
              type: array
              items:
                type: number
              description: Bounding box [minLon, minLat, maxLon, maxLat]
        County:
          type: object
          properties:
            FIPS:
              type: string
              description: County FIPS code
              example: '11001'
            name:
              type: string
              description: County name
              example: District of Columbia
        State:
          type: object
          properties:
            FIPS:
              type: string
              description: State FIPS code
              example: '11'
            code:
              type: string
              description: State two-letter code
              example: DC
            name:
              type: string
              description: State name
              example: District of Columbia
        status:
          type: string
          description: Status of the response
          example: OK
        executionTime:
          type: string
          description: Time taken to execute the query
          example: '0'