# Coverage Maps

A coverage map shows your users where your plans have mobile network coverage. You build one from network availability tilesets, which your map library draws as a layer on top of your basemap.

<Note type="warning">
**Preview**

Network availability tilesets are in preview, and their interface may change. Send any feedback to [support@gigs.com](mailto:support@gigs.com).

</Note>

## How it works

Network availability tilesets use three common mapping standards, which libraries such as MapLibre and Mapbox support natively:

1. **XYZ tiles.** The world is cut into a grid at every zoom level `z`, and each tile is addressed by its column `x` and row `y`. Your map library works out which tiles it needs as users pan and zoom.
2. **[Mapbox Vector Tiles](https://docs.mapbox.com/data/tilesets/guides/vector-tiles-standards/).** Each tile contains coverage shapes, with one layer per network technology, such as 4G and 5G. Tiles carry no styling: you choose the colors, the opacity and which technologies to show.
3. **URL templates.** You give your map library one URL with `{z}`, `{x}` and `{y}` placeholders, and it requests the tiles itself. You don't fetch any tiles in your own code.

## 1. Fetch the tilesets

Call the [list all coverage map tilesets][tilesets-endpoint] endpoint:

<CodeGroup title="List coverage map tilesets">

```bash
curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/networkAvailabilityTilesets" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"
```

</CodeGroup>

<CodeGroup title="Response">

```json
{
  "object": "list",
  "items": [
    {
      "object": "networkAvailabilityTileset",
      "expiresAt": "2026-08-10T12:00:00Z",
      "layers": [
        { "technology": "4G", "sourceLayer": "coverage_4g" },
        { "technology": "5G", "sourceLayer": "coverage_5g" }
      ],
      "maxZoom": 10,
      "minZoom": 0,
      "urlTemplate": "https://tiles.gigs.com/tiles/default/2026-08-03/{z}/{x}/{y}.pbf?Expires=...&Signature=..."
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}
```

</CodeGroup>

The response lists a tileset for each network your project's available plans use. Note that we don't have a coverage tileset for every network provider. The list is empty if none of your project's available plans has a coverage tileset. See the [API reference][tilesets-endpoint] for all fields.

Each tileset's `urlTemplate` is signed and stops working at `expiresAt`. Store the response, and fetch the tilesets again before `expiresAt` instead of hardcoding the URL. This also picks up new coverage data without code changes.

## 2. Add the tiles to your map

Add each tileset's `urlTemplate` as a vector tile source, then add a layer for each entry in its `layers`. In [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/), for example:

<CodeGroup title="Render coverage with MapLibre GL JS">

```js
// The tilesets from your backend
const { items } = await fetchCoverageTilesets()

map.on('load', () => {
  items.forEach((tileset, index) => {
    const sourceId = `coverage-${index}`

    map.addSource(sourceId, {
      type: 'vector',
      tiles: [tileset.urlTemplate],
      minzoom: tileset.minZoom,
      maxzoom: tileset.maxZoom,
    })

    // Tip: draw coverage below water, roads and labels, and above buildings
    for (const layer of tileset.layers) {
      map.addLayer({
        id: `${sourceId}-${layer.sourceLayer}`,
        type: 'fill',
        source: sourceId,
        'source-layer': layer.sourceLayer,
        paint: {
          'fill-color': layer.technology === '5G' ? '#4f8f6f' : '#7fb3a0',
          'fill-opacity': 0.6,
        },
      })
    }
  })
})
```

</CodeGroup>

For a readable map, draw coverage below your basemap's water, roads and labels, and above its buildings.

## Considerations

- **Coverage data.** Tiles show whether there is coverage for each technology, such as 4G and 5G, not signal strength. Coverage is currently available for networks in the United States.
- **Placement.** Show the map where users choose to open it rather than on a landing page, to avoid tile traffic nobody looks at. Opening it zoomed in on the user's area, for example from their ZIP code, makes it more useful.
- **Rate limiting.** We may rate-limit tile traffic if we see unusually high volumes.
- **Disclaimer.** We recommend including a disclaimer wherever the map appears, stating that coverage is predicted, not guaranteed, and can vary inside a covered area.

[tilesets-endpoint]: /api/latest/core/network-availabilities#list-all-coverage-map-tilesets