Coverage lookup - CoverageMap API Docs

POSThttps://enterprise.coveragemap.com/api/v1/coverage

Returns the datasets you ask for, for every provider and technology, at up to 100 locations. Use it for a single location or a whole list; there is no separate single lookup endpoint. Billed per location and dataset, see Units and billing.

Request

Send a JSON body with the Content-Type: application/json header and your key in the Authorization header.

Body parameters

datasetsstring[] | stringRequired

The datasets to return, as an array or a comma separated string. Not case sensitive, and repeats are ignored.

Possible values: fcc-coverage, speed-tests, summary

locationsobject[]Required

1 to 100 locations. Each needs latitude and longitude, or an address.

Show child attributes

idstring | numberOptional

Your own identifier. It is echoed back as a string so you can match results without comparing coordinates.

latitudenumberOptional

Latitude from -90 to 90. Required with longitude unless an address is given.

longitudenumberOptional

Longitude from -180 to 180. Required with latitude unless an address is given.

addressstringOptional

A street address to geocode, up to 256 characters and 20 words. When coordinates are also given, the coordinates are used.

providersstring[] | stringOptional

Provider codes, such as ATT, VZW and TMO, as an array or a comma separated string. Leave it out to get every provider your subscription can use. A provider that is not enabled for you is rejected.

technologiesstring[] | stringOptional

Technology codes as an array or a comma separated string. Leave it out to combine every technology into one result per provider.

Possible values: lte, 5g

countrystringOptional

Two letter country code for every location in the request. Other countries must be enabled on your subscription; List countries returns the ones you can use.

Defaults to US.

curl -X POST "https://enterprise.coveragemap.com/api/v1/coverage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasets": ["fcc-coverage", "summary"],
    "providers": ["VZW"],
    "technologies": ["lte"],
    "locations": [
      {
        "id": "store-1",
        "latitude": 38.8911,
        "longitude": -77.0364
      },
      {
        "id": "store-2",
        "address": "1600 Pennsylvania Ave NW, Washington, DC 20500"
      }
    ]
  }'

Response

data is a coverage lookup result. It has one location per location you sent, in the same order, and each location has one coverage entry per provider and technology.

Result

countrystring

The country looked up: the country you sent, or US when you left it out.

datasetsstring[]

The datasets you requested, in lower case.

locationsobject[]

One location per location in the request, in the same order.

Show child attributes

indexinteger

Position of the location in your request, from 0.

idstringOptional

The id you sent, as a string.

latitudenumberOptional

Latitude that was looked up. For an address, the geocoded latitude.

longitudenumberOptional

Longitude that was looked up. For an address, the geocoded longitude.

addressstringOptional

The address you sent.

confidencestringOptional

How confident the geocoder is in the coordinates found for an address.

Possible values: exact, high, medium, low

errorstringOptional

Why the location could not be looked up, for example an address that was not found. A location with an error has no coverage and is not billed.

coverageobject[]

One coverage entry per provider and technology. Empty when the location has an error.

Show child attributes

providerobject

The provider of this entry.

Show child attributes

codestring

Provider code, such as ATT, TMO or VZW.

namestring

Provider name, such as AT&T Mobility, T-Mobile US or Verizon Wireless.

technologyobjectNullable

The technology of this entry. Null when the request had no technologies and every technology is combined.

Show child attributes

codestring

Technology code, lte or 5g.

namestring

Technology name, LTE or 5GNR.

fccCoverageobjectOptionalNullable

Present when fcc-coverage was requested. An FCC coverage object, or null when the FCC does not report this provider and technology at the location.

speedTestobjectOptionalNullable

Present when speed-tests was requested. A speed test object, or null when there is no test, successful or failed, within 10 km for this provider and technology. A location with only failed tests nearby still returns the object, with a count of 0 and a positive failedCount.

summaryobjectOptionalNullable

Present when summary was requested. A summary object. When the FCC has nothing for this provider and technology and there are no nearby speed tests, every score is 0. Null only when there are no nearby speed tests and no FCC data is available for the location, for example outside the US.

Response

{
  "status": 200,
  "messages": {},
  "data": {
    "country": "US",
    "datasets": ["fcc-coverage", "summary"],
    "locations": [
      {
        "index": 0,
        "id": "store-1",
        "latitude": 38.8911,
        "longitude": -77.0364,
        "coverage": [
          {
            "provider": { "code": "VZW", "name": "Verizon Wireless" },
            "technology": { "code": "lte", "name": "LTE" },
            "fccCoverage": {
              "signal": {
                "signal": -84.5,
                "halfKilometer": -85.1,
                "oneKilometer": -86.3,
                "twoKilometers": -88.9
              },
              "coverage": {
                "halfKilometer": 1,
                "oneKilometer": 0.985,
                "twoKilometers": 0.912
              }
            },
            "summary": {
              "overall": 8.6,
              "performance": 7.9,
              "coverage": 9.5,
              "reliability": 7.7,
              "isFullyCovered": true,
              "source": "measured",
              "accuracy": "exact"
            }
          }
        ]
      },
      {
        "index": 1,
        "id": "store-2",
        "latitude": 38.897684,
        "longitude": -77.036574,
        "address": "1600 Pennsylvania Ave NW, Washington, DC 20500",
        "confidence": "exact",
        "coverage": [
          {
            "provider": { "code": "VZW", "name": "Verizon Wireless" },
            "technology": { "code": "lte", "name": "LTE" },
            "fccCoverage": {
              "signal": {
                "signal": -79.2,
                "halfKilometer": -80.4,
                "oneKilometer": -82.7,
                "twoKilometers": -85.6
              },
              "coverage": {
                "halfKilometer": 1,
                "oneKilometer": 1,
                "twoKilometers": 0.974
              }
            },
            "summary": {
              "overall": 9.1,
              "performance": 8.4,
              "coverage": 9.8,
              "reliability": 8.3,
              "isFullyCovered": true,
              "source": "measured",
              "accuracy": "high"
            }
          }
        ]
      }
    ]
  }
}

Behaviour

Locations come back in the order you sent them, with the same count.
Addresses are geocoded first; the coordinates found are returned with a confidence.
One bad location does not fail the request. It is returned with an error and the others are looked up as normal.
A dataset with nothing to report for a provider at a location is null on that coverage entry. FCC coverage and the summary are still billed, but speed tests are only billed for a location where at least one entry has speed test data.
If a dataset is temporarily unavailable it is null on every entry, a note is added to messages.information, and it is not billed.

Errors

Invalid requests are rejected with a 400, every problem listed in messages.errors, and nothing billed. The common errors apply too.

Request errors
Message	Cause
`datasets must contain at least one of: …`	datasets is missing or empty.
`Unknown dataset: …`	A dataset code is not recognised.
`locations must contain at least one location`	locations is missing or empty.
`Either latitude/longitude or address is required.`	A location has neither.
`Latitude must be a number between -90 and 90.`	Latitude is not a number or out of range.
`Longitude must be a number between -180 and 180.`	Longitude is not a number or out of range.
`Exceeded maximum number of locations of 100 per request`	More than 100 locations.
`Invalid provider code: …`	The provider is unknown or not enabled on your subscription.
`Country … is not supported`	The country is not enabled on your subscription.

These errors apply to one location and are returned in its error field:

Location errors
Message	Cause
`Failed to geocode address`	The address could not be found.
`Address is too long to geocode, use at most 256 characters and 20 words`	The address is over the limit.
`Location could not be processed`	The lookup failed for this location. Try it again.

400 response

{
  "status": 400,
  "messages": {
    "errors": [
      "datasets must contain at least one of: fcc-coverage, speed-tests, summary",
      "Latitude must be a number between -90 and 90."
    ]
  },
  "data": null
}

Location with an error

{
  "index": 2,
  "id": "warehouse-9",
  "address": "123 Nowhere Lane, Atlantis",
  "error": "Failed to geocode address",
  "coverage": []
}

Request#

Response#

Behaviour#

Errors#

Request

Response

Behaviour

Errors