Coverage

Send the same keywords, geo and lang you would send to a search. Coverage only reads what we've done there: it starts nothing, changes nothing and costs nothing.

curl -X POST https://api.gmaps.dev/v1/coverage \
  -H "Authorization: Bearer $GMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["bakery"], "geo": { "location": "Curitiba, PR" } }'

This is an area we'd partly searched:

{
  "data": {
    "coverage": "partial",
    "squaresTotal": 21,
    "squaresCovered": 9,
    "squaresToSearch": 12,
    "placesKnown": 14,
    "searchedAt": {
      "oldest": "2026-06-02T14:05:11.000Z",
      "newest": "2026-09-18T09:41:37.000Z"
    },
    "freshForDays": 180,
    "emptyFreshForDays": 7
  }
}

• coverage: fresh when we searched every square recently, partial when some, new when none.
• squaresTotal: how many squares this area and these terms come to.
• squaresCovered: how many of them we searched recently enough to use again.
• squaresToSearch: how many are left. A collection would search these.
• placesKnown: how many places we've saved in the covered squares. A search hands them over for free.
• searchedAt: when we searched the covered squares, the oldest and the newest. null when none are covered.
• freshForDays and emptyFreshForDays: how long a square stays covered, as the next sections explain.

One search on the map brings back a limited number of places, however big the area. So we split an area into small squares and search each one, once for each term. A small area is one square; a bigger one is a grid of them.

A square is covered for everyone. When someone else searched it recently, it counts for you too, and its places are free.

Each square belongs to one term and one language. bakery and cafe are different squares, and so is the same term in pt and in en. Capital letters, accents and extra spaces don't matter.

A square stays covered for a while after we search it:

• 180 days when it held places;
• 7 days when it came back empty. An empty square can mean there's nothing there, or that the search didn't get through, so we look again sooner.

An area is fresh when all its squares are covered. A square that's being searched right now doesn't count until its search is done. When its days are up, it counts as not searched again, and the next collection there searches it again and updates its places. A place we collected more than 180 days ago costs 1 credit again, like a new one.

placesKnown: 0 never means there are no businesses there. It means one of two things:

• coverage is new or partial: we haven't searched all of this area for this term and language yet. A search will collect the rest.
• coverage is fresh: we searched it recently and found nothing for this term. Try another word for the same thing. We'll look again once those squares' days are up.

All three read the same squares, and all three are free:

• A search checks coverage first, and its coverage field gives the same answer. Ask for coverage on its own when you only want to know, not to collect.
• A quote, at POST /v1/collections/quote, adds the most a collection could cost and a few of the places we've saved. Collections explains it.
• Coverage adds when the squares were searched and how long they stay covered. Use it to decide whether an area is worth collecting again.

Coverage counts every place in the covered squares. A search or a quote with minRating counts only the places that pass it, so its placesKnown can be lower.

The area follows the same rules as a search. A city we can't pin down answers 422 GEO_UNRESOLVED, and an area too big for one ask answers 400 VALIDATION_ERROR. Search explains both.