Coletas

Uma busca traz até 120 lugares. Uma cidade inteira tem muito mais empresas que isso, então a coleta divide a região em quadrados pequenos e busca cada um, uma vez para cada termo. Ela roda em segundo plano: leva alguns minutos numa região pequena e mais tempo numa cidade.

Quadrados que alguém buscou com o mesmo termo e o mesmo idioma nos últimos 180 dias já estão salvos. Os lugares deles voltam na hora e não custam nada. Um quadrado que voltou sem nenhum lugar vale só por 7 dias: depois disso, buscamos de novo. Você paga 1 crédito por lugar novo que encontramos para você.

Os quatro primeiros campos funcionam como numa busca. Os dois últimos são só da coleta. A estimativa e a coleta usam o mesmo corpo de requisição:

Uma região grande com muitos termos pode passar do número de quadrados que cabe numa coleta. Aí a resposta é 400 VALIDATION_ERROR: use uma região menor ou menos termos e tente de novo.

A estimativa diz quanto uma coleta custaria antes de você começar. É de graça e não começa nada:

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

Esta é a resposta, sem o sample:

{
  "data": {
    "coverage": "partial",
    "squaresTotal": 21,
    "squaresCovered": 9,
    "squaresToSearch": 12,
    "placesKnown": 140,
    "maxCost": 360
  }
}

• coverage: quanto da região buscamos há pouco tempo. fresh é tudo, partial é uma parte e new é nada.
• squaresTotal, squaresCovered, squaresToSearch: os quadrados em que a região se divide, contados uma vez por termo. Os já cobertos respondem na hora. Cada um que falta buscar leva alguns minutos.
• placesKnown: quantos lugares já salvamos ali. Eles são de graça.
• maxCost: o máximo que pode custar, em créditos. É o maxPlaces menos os lugares que já temos, ou o dobro disso quando você pede e-mails. Costuma sair mais barato, porque ninguém sabe quantas empresas um quadrado tem antes de buscá-lo.
• sample: alguns dos lugares que já temos, para você ver o que tem ali.

A estimativa confere os termos, o tamanho da região, o maxPlaces e os e-mails do mesmo jeito que a coleta. Se a estimativa recusar, a coleta também recusaria.

Mande o mesmo corpo para começar a coleta. A resposta vem na hora, com status 202: aceitamos o pedido, e a busca continua em segundo plano.

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

O que volta é a própria coleta:

{
  "data": {
    "id": "8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31",
    "kind": "collection",
    "status": "queued",
    "stopReason": null,
    "query": {
      "keywords": ["padaria"],
      "geo": { "location": "Curitiba, PR" },
      "lang": "pt",
      "minRating": null,
      "maxPlaces": 500,
      "enrich": []
    },
    "area": { "lat": -25.4195, "lng": -49.2646, "radiusM": 10000 },
    "squaresTotal": 21,
    "squaresCovered": 9,
    "jobsTotal": 12,
    "jobsDone": 0,
    "counts": {
      "placesDelivered": 140,
      "placesFresh": 0,
      "placesCached": 140,
      "creditsCharged": 0,
      "creditsRefunded": 0
    },
    "error": null,
    "queuedAt": "2026-09-24T14:02:11.000Z",
    "startedAt": null,
    "finishedAt": null,
    "cancelRequestedAt": null,
    "resultsExpireAt": "2026-10-24T14:02:11.000Z"
  }
}

Os lugares que já tínhamos salvado entram nela desde o começo. Aqui, counts.placesCached é 140.

Quando todos os quadrados já tinham sido buscados, não sobra nada a fazer. A coleta volta pronta, com status succeeded, e não custou nada.

Começar uma coleta é de graça. Você paga conforme os lugares chegam: primeiro descontamos os créditos dos lugares novos, depois eles entram na sua coleta, que nunca passa do maxPlaces:

• 0Um lugar que já salvamos volta na mesma resposta, marcado com cached: true.
• 1Um lugar novo que uma coleta encontra para você.
• 1E-mails de um lugar novo, nos planos pagos: 1 crédito por lugar, só quando encontramos pelo menos um.
• 0Buscas, estimativas, exportações e consultas ao seu consumo.
• 0Uma coleta que não encontra nada.

Se você mandar o mesmo pedido enquanto ela ainda roda, recebe a mesma coleta de volta. Não começa uma segunda nem paga duas vezes.

Antes de começar, conferimos duas coisas. Se alguma falhar, a resposta é 429 QUOTA_EXCEEDED:

• details.scope é concurrency: você já está com o máximo de coletas simultâneas do seu plano. A nova não fica guardada para depois: mande de novo quando uma terminar, ou cancele uma antes.
• details.scope é day ou month: você chegou ao limite diário de créditos ou acabaram os créditos do mês, e ainda falta buscar parte da região. O details.resetAt diz quando eles voltam. Créditos comprados ajudam no mês, mas não no dia: o limite diário continua valendo.

Cada plano define o máximo de lugares que uma coleta entrega e quantas coletas rodam ao mesmo tempo:

Se você pedir um maxPlaces acima do limite do seu plano, a resposta é 400 VALIDATION_ERROR. Os outros limites do plano estão em Limites, e você troca de plano na página Plano.

Leia a coleta de novo sempre que quiser saber até onde ela chegou. É de graça:

curl https://api.gmaps.dev/v1/collections/8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31 \
  -H "Authorization: Bearer $GMAPS_API_KEY"

Para ver os lugares conforme chegam, abra o progresso ao vivo. Para o seu servidor ser avisado quando ela terminar, cadastre um webhook.

jobsDone de jobsTotal mostra quanto ela já andou. Buscamos os quadrados em lotes, e cada lote é um passo.

Quando uma coleta para antes de buscar a região inteira ou de chegar ao maxPlaces, ou termina sem nenhum lugar, o stopReason diz por quê:

O counts mostra o que ela entregou e quanto isso custou:

• placesDelivered: os lugares da coleta. É sempre placesFresh mais placesCached.
• placesFresh: lugares novos, buscados pela primeira vez ou de novo porque a nossa cópia tinha mais de 180 dias. 1 crédito cada.
• placesCached: lugares que já tínhamos salvado. De graça.
• creditsCharged: 1 por lugar novo, e 1 a mais quando encontramos um e-mail dele.
• creditsRefunded: créditos devolvidos. Uma coleta que termina sem nenhum lugar devolve todos os créditos que usou.

queuedAt, startedAt e finishedAt dizem quando ela foi aceita, quando começou e quando terminou.

Suas coletas vêm da mais recente para a mais antiga. Filtre por status para achar as que ainda estão rodando. O limit vai de 1 a 100 e é 20 se você não mudar. O offset pula as primeiras, e o total diz quantas são ao todo:

curl "https://api.gmaps.dev/v1/collections?status=running" \
  -H "Authorization: Bearer $GMAPS_API_KEY"

Cancele uma coleta que você não quer mais. O que acontece depende de onde ela está:

curl -X DELETE https://api.gmaps.dev/v1/collections/8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31 \
  -H "Authorization: Bearer $GMAPS_API_KEY"

• Esperando a vez: para na hora e não custa nada.
• Rodando: nenhuma busca nova começa. As que já estão em andamento terminam, e os lugares delas entram e são cobrados normalmente. Depois disso, o status vira cancelled. O cancelRequestedAt mostra quando você pediu.
• Já terminou: não há o que parar. A resposta é 409 CONFLICT, com o status em details.status, e os lugares continuam onde estão.

Os lugares vêm na ordem em que chegaram, do mais antigo para o mais novo. Assim, uma página que você já leu continua igual enquanto outros chegam. O limit vai de 1 a 200 e é 50 se você não mudar:

curl "https://api.gmaps.dev/v1/collections/8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31/places?limit=200" \
  -H "Authorization: Bearer $GMAPS_API_KEY"

Cada item é um lugar completo. O meta.cached dele é true quando já tínhamos o lugar, então ele saiu de graça. É assim que você confere o que pagou.

Para a próxima página, some o limit ao offset. Você leu tudo quando o offset chega ao total.

Uma página pode vir com menos lugares que o limit quando uma empresa pediu para ficar de fora, então não pare numa página curta. O counts da coleta continua contando esse lugar e o que ele custou.

Os lugares de uma coleta ficam disponíveis por 30 dias depois que você a começa, até o resultsExpireAt. Depois disso, apagamos a lista de lugares e o progresso ao vivo dela. A coleta em si continua, com as contagens e as cobranças.

Depois de apagados, a página de lugares volta vazia e a exportação é recusada, então exporte o que quiser guardar antes disso. Para ter os lugares de novo, comece a mesma coleta: os quadrados buscados nos últimos 180 dias voltam de graça.