openapi: 3.0.3
info:
  title: Broadband Map Public API
  description: |
    Look up broadband and cellular coverage at any US location by latitude/longitude.

    Data starts with the FCC's Broadband Data Collection (BDC) program.
    Cell signal strength values are adjusted using crowdsourced real-world
    measurements and are significantly different from raw FCC predictions.

    Rate limited to 60 requests per hour per IP address (1,000/hour global cap).
  version: 1.0.0
  contact:
    name: Broadband Map
    url: https://broadbandmap.com

servers:
  - url: https://broadbandmap.com
    description: Production

paths:
  /api/v1/location/internet:
    get:
      summary: Fixed broadband ISPs at a location
      description: |
        Returns all fixed broadband providers (fiber, cable, DSL, etc.)
        available at the given coordinates using H3 resolution 8 hexagons.
      operationId: internetLookup
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude (-90 to 90)
          schema:
            type: number
            minimum: -90
            maximum: 90
            example: 40.758
        - name: lng
          in: query
          required: true
          description: Longitude (-180 to 180)
          schema:
            type: number
            minimum: -180
            maximum: 180
            example: -73.985
        - name: service_type
          in: query
          required: false
          description: Type of service
          schema:
            type: string
            enum: [residential, business]
            default: residential
      responses:
        '200':
          description: ISP availability data
          content:
            application/json:
              schema:
                type: object
                properties:
                  lat:
                    type: number
                  lng:
                    type: number
                  h3_hex:
                    type: string
                    description: H3 hex ID at resolution 8
                  h3_resolution:
                    type: integer
                    example: 8
                  service_type:
                    type: string
                  count:
                    type: integer
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: Verizon
                        technology:
                          type: string
                          example: Fiber
                        technology_code:
                          type: integer
                          example: 50
                        max_download_mbps:
                          type: number
                          example: 940
                        max_upload_mbps:
                          type: number
                          example: 880
                        provider_id:
                          type: integer
                          example: 131425
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/location/cell:
    get:
      summary: Cellular signal strength at a location
      description: |
        Returns cellular coverage data for all networks at the given
        coordinates using H3 resolution 9 hexagons. Signal strength values
        are adjusted from raw FCC predictions using empirical correction factors.
      operationId: cellLookup
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude (-90 to 90)
          schema:
            type: number
            minimum: -90
            maximum: 90
            example: 40.758
        - name: lng
          in: query
          required: true
          description: Longitude (-180 to 180)
          schema:
            type: number
            minimum: -180
            maximum: 180
            example: -73.985
        - name: network
          in: query
          required: false
          description: Filter by network slug
          schema:
            type: string
            enum: [att, verizon, t-mobile, us-cellular, dish, gci, cellcom, c-spire]
        - name: tech
          in: query
          required: false
          description: Filter by technology generation
          schema:
            type: string
            enum: ['4g', '5g']
      responses:
        '200':
          description: Cellular coverage data
          content:
            application/json:
              schema:
                type: object
                properties:
                  lat:
                    type: number
                  lng:
                    type: number
                  h3_hex:
                    type: string
                    description: H3 hex ID at resolution 9
                  h3_resolution:
                    type: integer
                    example: 9
                  count:
                    type: integer
                  coverage:
                    type: array
                    items:
                      type: object
                      properties:
                        network:
                          type: string
                          example: T-Mobile
                        network_slug:
                          type: string
                          example: t-mobile
                        technology:
                          type: string
                          example: 5G NR
                        technology_code:
                          type: integer
                          example: 500
                        rsrp_dbm:
                          type: number
                          description: Adjusted signal strength in dBm
                          example: -95.2
                        signal_level:
                          type: string
                          description: Human-readable signal level
                          enum: [Excellent, Strong, Good, Fair, Weak, Very Weak]
                          example: Good
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
