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

    An API key is required (Authorization: Bearer or X-Api-Key header).
    Plans and free demo keys: https://broadbandmap.com/api/
    Each plan has a monthly request quota; only successful (2xx) responses
    count toward it. Exhausted quotas return 429 until the calendar month
    resets (UTC). Keys also have a burst limit of 10 requests per second
    (may be relaxed on request); requests over it return 429 with code
    burst_limit_exceeded and don't consume quota.
  version: 1.2.0
  contact:
    name: Broadband Map
    url: https://broadbandmap.com

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

security:
  - bearerAuth: []
  - apiKeyHeader: []

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
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
          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
                        max_download_mbps:
                          type: number
                          example: 940
                        max_upload_mbps:
                          type: number
                          example: 880
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Quota or rate limit exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          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, 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
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
          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
                        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'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Quota or rate limit exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/usage:
    get:
      summary: Current usage for the presented API key
      description: |
        Returns the key's plan, monthly quota, and usage so far this month.
        Calls to this endpoint do not count toward the quota.
      operationId: usageLookup
      responses:
        '200':
          description: Usage data
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan:
                    type: string
                    example: starter
                  key_status:
                    type: string
                    example: active
                  customer_status:
                    type: string
                    example: active
                  month_start:
                    type: string
                    format: date
                    example: '2026-06-01'
                  monthly_limit:
                    type: integer
                    example: 1000
                  monthly_used:
                    type: integer
                    example: 132
                  monthly_remaining:
                    type: integer
                    example: 368
                  daily_limit:
                    type: integer
                    description: Present only for keys with a daily cap (demo keys)
                  daily_used:
                    type: integer
                    description: Present only for keys with a daily cap (demo keys)
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Authorization: Bearer YOUR_API_KEY"
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
  headers:
    XRateLimitLimit:
      description: Monthly request quota for the presented key
      schema:
        type: integer
    XRateLimitRemaining:
      description: Requests remaining in the current month
      schema:
        type: integer
    RetryAfter:
      description: Seconds until the relevant quota or rate limit resets
      schema:
        type: integer
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable message. Wording may change; key off `code` instead.
        code:
          type: string
          description: Stable machine-readable error code
          enum:
            - missing_key
            - invalid_key
            - key_inactive
            - invalid_params
            - monthly_quota_exceeded
            - daily_quota_exceeded
            - burst_limit_exceeded
            - rate_limited
            - method_not_allowed
            - server_error
      required:
        - error
        - code
