Cobertura

Mande os mesmos keywords, geo e lang que você mandaria numa busca. A cobertura só lê o que já fizemos ali: não começa nada, não muda nada e não custa nada.

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

Esta é uma região que já tínhamos buscado em parte:

{
  "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 quando buscamos todos os quadrados recentemente, partial quando só alguns, new quando nenhum.
• squaresTotal: quantos quadrados essa região e esses termos somam.
• squaresCovered: quantos deles buscamos há pouco tempo, o bastante para aproveitar de novo.
• squaresToSearch: quantos faltam. Uma coleta buscaria esses.
• placesKnown: quantos lugares já salvamos nos quadrados cobertos. Uma busca entrega esses lugares de graça.
• searchedAt: quando buscamos os quadrados cobertos, o mais antigo e o mais recente. null quando nenhum está coberto.
• freshForDays e emptyFreshForDays: por quanto tempo um quadrado continua coberto, como explicam as próximas seções.

Uma busca no mapa traz um número limitado de lugares, não importa o tamanho da região. Por isso dividimos a região em quadrados pequenos e buscamos cada um, uma vez para cada termo. Uma região pequena é um quadrado só; uma maior vira uma grade deles.

Um quadrado fica coberto para todo mundo. Se outra pessoa buscou ali recentemente, isso vale para você também, e os lugares de lá saem de graça.

Cada quadrado é de um termo e de um idioma. padaria e confeitaria são quadrados diferentes, e o mesmo termo em pt e em en também. Maiúsculas, acentos e espaços sobrando não fazem diferença.

Um quadrado continua coberto por um tempo depois que o buscamos:

• 180 dias quando trouxe lugares;
• 7 dias quando voltou vazio. Um quadrado vazio pode querer dizer que não há nada ali, ou que a busca não conseguiu passar, então olhamos de novo mais cedo.

Uma região é fresh quando todos os quadrados dela estão cobertos. Um quadrado que está sendo buscado agora só conta quando a busca dele termina. Quando os dias acabam, ele volta a contar como não buscado, e a próxima coleta ali busca de novo e atualiza os lugares dele. Um lugar que coletamos há mais de 180 dias volta a custar 1 crédito, como um lugar novo.

placesKnown: 0 nunca quer dizer que não existem empresas ali. Quer dizer uma destas duas coisas:

• coverage é new ou partial: ainda não buscamos essa região inteira para esse termo e idioma. Uma busca vai coletar o resto.
• coverage é fresh: buscamos recentemente e não achamos nada para esse termo. Tente outra palavra para a mesma coisa. Vamos olhar de novo quando os dias desses quadrados acabarem.

As três leem os mesmos quadrados, e as três são de graça:

• Uma busca confere a cobertura antes, e o campo coverage dela dá a mesma resposta. Peça só a cobertura quando quiser saber, sem coletar.
• Uma estimativa, em POST /v1/collections/quote, mostra também o máximo que uma coleta pode custar e alguns dos lugares que já salvamos. Coletas explica como funciona.
• A cobertura mostra também quando os quadrados foram buscados e por quanto tempo continuam cobertos. Use para decidir se vale a pena coletar uma região de novo.

A cobertura conta todos os lugares dos quadrados cobertos. Uma busca ou estimativa com minRating conta só os lugares que passam no filtro, então o placesKnown dela pode ser menor.

A região segue as mesmas regras da busca. Uma cidade que não conseguimos identificar responde 422 GEO_UNRESOLVED, e uma região grande demais para um pedido responde 400 VALIDATION_ERROR. Busca explica os dois casos.