Get Provider Coverage by Census Geography

curl --request GET \
  --url https://api-sandbox.letshum.com/coverage \
  --header 'Authorization: Bearer <token>'

{
  "message": "Coverage for states: CA, NY",
  "request_status": "ok",
  "data": [
    {
      "provider_id": "130317",
      "provider_name": "Xfinity",
      "telephone": "+18009346489",
      "provider_icon": null,
      "provider_logo": "https://api.letshum.com/rails/active_storage/blobs/logo.png",
      "url": null,
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 3500
      },
      "button_label": "xfinity.com",
      "offerings": [
        {
          "technology": "Cable",
          "max_download_speed": 1200,
          "max_upload_speed": 35
        },
        {
          "technology": "Fiber",
          "max_download_speed": 2000,
          "max_upload_speed": 2000
        }
      ],
      "matched_areas": {
        "states": [
          "06",
          "36"
        ]
      }
    },
    {
      "provider_id": "130079",
      "provider_name": "Spectrum",
      "telephone": "+18558551114",
      "provider_icon": null,
      "provider_logo": "https://api.letshum.com/rails/active_storage/blobs/logo.png",
      "url": null,
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 4999
      },
      "button_label": "spectrum.com",
      "offerings": [
        {
          "technology": "Cable",
          "max_download_speed": 1000,
          "max_upload_speed": 35
        }
      ],
      "matched_areas": {
        "states": [
          "06"
        ]
      }
    }
  ],
  "meta": {
    "responded_at": "2026-01-29T22:00:00Z",
    "hum_data_set": "25041808",
    "provider_count": 2,
    "query": {
      "states": [
        "CA",
        "NY"
      ]
    }
  }
}

Informational

Get Provider Coverage by Census Geography

Retrieves Internet service provider coverage for specified census geographic areas. This endpoint allows querying by state, county, tract, or block GEOIDs, returning all providers that offer service in the specified areas.

Geographic Hierarchy

Census geography follows a hierarchical structure where each level contains the parent levels:

State (2 characters): State FIPS code (e.g., 06 for California) or postal abbreviation (CA)
County (5 characters): State FIPS + County FIPS (e.g., 06037 for Los Angeles County)
Tract (11 characters): State + County + Tract code (e.g., 06037100100)
Block (15 characters): Full census block GEOID (e.g., 060371001001000)

Query Logic

Within same parameter type: OR logic (e.g., states[]=CA&states[]=NY returns providers in CA OR NY)
Between different parameter types: AND logic (e.g., states[]=CA&counties[]=06037 returns providers in CA AND county 06037)

Use Cases

Analyzing provider coverage across multiple states
Comparing service availability between counties
Identifying providers serving specific census tracts
Bulk coverage lookups for geographic regions

Response Data

Each provider includes:

Provider details (name, logo, contact info)
Technology offerings (Fiber, Cable, DSL, etc.) with max speeds
matched_areas: Which of the queried geographic areas this provider covers

Example Queries

# Providers in California and New York
GET /coverage?states[]=CA&states[]=NY

# Providers in Los Angeles County
GET /coverage?counties[]=06037

# Providers in specific tracts
GET /coverage?tracts[]=06037100100&tracts[]=06037100200

# Providers in California AND Los Angeles County (intersection)
GET /coverage?states[]=CA&counties[]=06037

Important Notes

At least one geographic parameter is required
All parameters accept arrays for querying multiple areas
States can be specified as FIPS codes (06) or postal abbreviations (CA)
County, tract, and block must use full GEOIDs (which include parent geography)

GET

coverage

Get Provider Coverage by Census Geography

curl --request GET \
  --url https://api-sandbox.letshum.com/coverage \
  --header 'Authorization: Bearer <token>'

{
  "message": "Coverage for states: CA, NY",
  "request_status": "ok",
  "data": [
    {
      "provider_id": "130317",
      "provider_name": "Xfinity",
      "telephone": "+18009346489",
      "provider_icon": null,
      "provider_logo": "https://api.letshum.com/rails/active_storage/blobs/logo.png",
      "url": null,
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 3500
      },
      "button_label": "xfinity.com",
      "offerings": [
        {
          "technology": "Cable",
          "max_download_speed": 1200,
          "max_upload_speed": 35
        },
        {
          "technology": "Fiber",
          "max_download_speed": 2000,
          "max_upload_speed": 2000
        }
      ],
      "matched_areas": {
        "states": [
          "06",
          "36"
        ]
      }
    },
    {
      "provider_id": "130079",
      "provider_name": "Spectrum",
      "telephone": "+18558551114",
      "provider_icon": null,
      "provider_logo": "https://api.letshum.com/rails/active_storage/blobs/logo.png",
      "url": null,
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 4999
      },
      "button_label": "spectrum.com",
      "offerings": [
        {
          "technology": "Cable",
          "max_download_speed": 1000,
          "max_upload_speed": 35
        }
      ],
      "matched_areas": {
        "states": [
          "06"
        ]
      }
    }
  ],
  "meta": {
    "responded_at": "2026-01-29T22:00:00Z",
    "hum_data_set": "25041808",
    "provider_count": 2,
    "query": {
      "states": [
        "CA",
        "NY"
      ]
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer token authentication using API tokens. Include the token in the Authorization header as: Authorization: Bearer <token>

Obtain tokens through your Hum API account dashboard or contact support@letshum.com for access.

Query Parameters

states[]

string[]

State FIPS codes (2 characters) or postal abbreviations. Examples: 06 or CA for California, 36 or NY for New York

Required string length: 2

counties[]

string[]

County GEOIDs (5 characters: 2-digit state FIPS + 3-digit county FIPS). Example: 06037 for Los Angeles County (06=California, 037=LA County)

Pattern: ^\d{5}$

tracts[]

string[]

Census tract GEOIDs (11 characters: state + county + 6-digit tract code). Example: 06037100100 (California, LA County, tract 100100)

Pattern: ^\d{11}$

blocks[]

string[]

Census block GEOIDs (15 characters: full block identifier). Example: 060371001001000

Pattern: ^\d{15}$

Response

Provider coverage data for the specified geographic areas

message

string

required

Human-readable summary of the query parameters

Example:

"Coverage for states: CA, NY; counties: 06037"

request_status

enum<string>

required

A status code summarizing the outcome of this response.

ok: Request was successful
warning: Request was processed but with some issues
error: Request failed

Available options:

ok,

warning,

error

Example:

"ok"

data

object[]

required

Array of providers with coverage in the specified areas

Show child attributes