---
title: "Check an area's coverage"
method: POST
path: "/coverage"
tags: ["Coverage"]
---

# Check an area's coverage

`POST /coverage`

## Request

- Base URL: `https://api.gmaps.dev/v1`
- URL: `https://api.gmaps.dev/v1/coverage`
- Auth: HTTP bearer

See how much of an area we have already searched for a term, when we last searched it, and how many places we have saved there. Use it to decide whether to collect again or just read the saved places. Needs an API key. Costs no credits and starts nothing.

## Request body

- object
  - `keywords` string[], required: What you would search for, such as ["bakery"]. Coverage is per term: we may have searched an area for one and never for another.
  - `geo` union, required: The area. Give exactly one of: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm.
    - object
      - `location` string, required
    - object
      - `lat` number, required
      - `lng` number, required
      - `radiusM` number, required
    - object
    - object
      - `cityIbge` integer, required
      - `radiusKm` number, required
  - `lang` string: The language the search would run in. Two letters, such as pt or en.

## Response `200`

Check an area's coverage

- object
  - `data` object, required
    - `coverage` 'fresh' | 'partial' | 'new', required: `fresh`: we searched all of it recently. `new`: none of it. `partial`: some.
    - `squaresTotal` integer, required: How many searches the area takes: one per square of the area, for each term.
    - `squaresCovered` integer, required: How many of those we searched recently enough to reuse. Their places cost nothing.
    - `squaresToSearch` integer, required: How many searches a collection would still have to run. Each takes a few minutes.
    - `placesKnown` integer, required: Places we have saved in this area. They cost nothing.
    - `searchedAt` object, nullable, required: When we searched the covered squares, oldest and newest. Null when we searched none.
      - `oldest` string, date-time, required
      - `newest` string, date-time, required
    - `freshForDays` integer, required: How many days a search stays good for. After that, a collection searches the square again.
    - `emptyFreshForDays` integer, required: How many days a search that found no places stays good for. It is far shorter, because finding nothing can also mean the search was blocked.
  - `meta` union
    - object
      - `total` integer, required: Every item that matches, not just this page.
      - `limit` integer, required: The most items a page holds.
      - `offset` integer, required: How many items came before this page.
      - `hasMore` boolean, required: True when another page follows.
    - object
      - `cost` integer, required: Credits this call took.
      - `creditsRemaining` integer, required: Credits left after this call, this month's and bought ones together.
      - `requestId` string, required: This call's id. Send it to support if something went wrong.
      - `cached` boolean: True when this response used only saved results.

## Other responses

- `default`: Any other failure.

---

[API](https://skmtc.dev/gmaps/apis/gmaps-dev.md) · [All operations](https://skmtc.dev/gmaps/apis/gmaps-dev/llms.txt) · [OpenAPI document](https://skmtc.dev/gmaps/apis/gmaps-dev/revisions/0b3459aaf802?raw)