Recopilaciones

Una búsqueda te da hasta 120 lugares. Una ciudad entera tiene muchos más negocios, así que una recopilación divide la zona en cuadros pequeños y busca en cada uno, una vez por cada término. Corre en segundo plano: unos minutos en una zona pequeña y más tiempo en una ciudad.

Los cuadros que alguien ya buscó con el mismo término e idioma en los últimos 180 días ya están guardados. Sus lugares llegan al instante y no cuestan nada. Un cuadro que no trajo lugares cuenta solo por 7 días, y después lo buscamos otra vez. Pagas 1 crédito por cada lugar nuevo que encontramos para ti.

Los primeros cuatro campos funcionan como en una búsqueda. Los dos últimos son solo de las recopilaciones. Una estimación y una recopilación llevan el mismo cuerpo:

Una zona grande con muchos términos puede dar más cuadros de los que admite una recopilación. Entonces la respuesta es 400 VALIDATION_ERROR: usa una zona más pequeña o menos términos e inténtalo de nuevo.

Una estimación te dice cuánto costaría una recopilación antes de empezarla. Es gratis y no inicia nada:

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

Esta es la respuesta, sin sample:

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

• coverage: cuánto de la zona buscamos hace poco. fresh es toda, partial es una parte y new es nada.
• squaresTotal, squaresCovered, squaresToSearch: los cuadros en que se divide la zona, contados una vez por término. Los cubiertos responden al instante. Cada uno que falta por buscar tarda unos minutos.
• placesKnown: cuántos lugares ya guardamos ahí. Son gratis.
• maxCost: lo máximo que puede costar, en créditos. Es maxPlaces menos los lugares que ya tenemos, o el doble de eso si pides correos electrónicos. Normalmente cuesta menos, porque nadie sabe cuántos negocios hay en un cuadro hasta que lo buscamos.
• sample: algunos de los lugares que ya tenemos, para que veas qué hay.

Una estimación revisa tus términos, el tamaño de la zona, maxPlaces y los correos electrónicos igual que al empezar una recopilación. Si la estimación se rechaza, empezar la recopilación también se rechazaría.

Envía el mismo cuerpo para empezar la recopilación. La respuesta llega al instante, con el estado 202: aceptamos la solicitud y la búsqueda sigue en segundo plano.

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

Lo que vuelve es la recopilación misma:

{
  "data": {
    "id": "8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31",
    "kind": "collection",
    "status": "queued",
    "stopReason": null,
    "query": {
      "keywords": ["panadería"],
      "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"
  }
}

Los lugares que ya teníamos guardados están en ella desde el principio. Aquí, counts.placesCached es 140.

Cuando ya se buscó en todos los cuadros, no queda nada por hacer. La recopilación vuelve terminada, con el estado succeeded, y no costó nada.

Empezar una recopilación es gratis. Pagas a medida que llegan los lugares: primero cobramos los créditos de los lugares nuevos, luego los agregamos a tu recopilación, y nunca recibes más de maxPlaces:

• 0Un lugar que ya guardamos llega en la misma respuesta, marcado con cached: true.
• 1Un lugar nuevo que encuentra una recopilación para ti.
• 1Correos electrónicos de un lugar nuevo, en los planes de pago: 1 crédito por lugar, solo cuando encontramos al menos uno.
• 0Búsquedas, estimaciones, exportaciones y consultar tu uso.
• 0Una recopilación que no encuentra nada.

Si envías la misma solicitud mientras sigue en marcha, recibes la misma recopilación. No empiezas una segunda ni pagas dos veces.

Antes de empezar, revisamos dos cosas. Si alguna falla, la respuesta es 429 QUOTA_EXCEEDED:

• details.scope es concurrency: ya tienes en marcha todas las recopilaciones que permite tu plan. No dejamos la nueva en espera, así que envíala de nuevo cuando termine una, o cancela una antes.
• details.scope es day o month: llegaste a tu límite diario de créditos o gastaste los créditos de este mes, y aún falta buscar parte de la zona. details.resetAt dice cuándo vuelven. Los créditos que compras ayudan con el mes, no con el día: el límite diario sigue vigente.

Cada plan define el máximo de lugares que te entrega una recopilación y cuántas recopilaciones corren a la vez:

Si pides un maxPlaces mayor que el de tu plan, la respuesta es 400 VALIDATION_ERROR. Los demás límites de tu plan están en Límites, y puedes cambiar de plan en la página Plan.

Lee la recopilación otra vez cuando quieras saber hasta dónde llegó. Es gratis:

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

Para ver los lugares a medida que llegan, abre su progreso en vivo. Para que tu servidor se entere cuando termine, agrega un webhook.

jobsDone de jobsTotal es cuánto avanzó. Buscamos los cuadros por lotes, y cada lote es un paso.

Cuando una recopilación se detiene antes de buscar en toda la zona o de llegar a maxPlaces, o termina sin lugares, stopReason dice por qué:

counts es lo que te entregó y lo que eso costó:

• placesDelivered: los lugares de la recopilación. Siempre es placesFresh más placesCached.
• placesFresh: lugares nuevos, buscados por primera vez o de nuevo porque nuestra copia tenía más de 180 días. 1 crédito cada uno.
• placesCached: lugares que ya teníamos guardados. Gratis.
• creditsCharged: 1 por cada lugar nuevo, y 1 más cuando encontramos un correo electrónico de ese lugar.
• creditsRefunded: créditos devueltos. Una recopilación que termina sin lugares devuelve todo lo que cobró.

queuedAt, startedAt y finishedAt dicen cuándo se aceptó, cuándo empezó y cuándo terminó.

Tus recopilaciones llegan de la más reciente a la más antigua. Filtra por status para encontrar las que siguen en marcha. limit acepta de 1 a 100 y vale 20 si no lo defines. offset se salta las primeras, y total dice cuántas hay en total:

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

Cancela una recopilación que ya no quieras. Lo que pasa depende de hasta dónde llegó:

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

• Esperando su turno: se detiene al instante y no cuesta nada.
• En marcha: no empieza nada nuevo. Las búsquedas que ya están en curso terminan, y sus lugares se agregan y se cobran como siempre. Luego su estado pasa a cancelled. cancelRequestedAt muestra cuándo lo pediste.
• Ya terminó: no hay nada que detener. La respuesta es 409 CONFLICT, con su estado en details.status, y sus lugares se quedan donde están.

Los lugares vienen en el orden de llegada, del más antiguo al más nuevo, así que una página que ya leíste no cambia mientras llegan más. limit acepta de 1 a 200 y vale 50 si no lo defines:

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

Cada elemento es un lugar completo. Su meta.cached es true cuando ya lo teníamos, así que fue gratis. Así compruebas qué pagaste.

Para la página siguiente, suma limit a offset. Ya leíste todo cuando offset llega a total.

Una página puede traer menos lugares que limit cuando un negocio nos pidió dejarlo fuera, así que no te detengas en una página corta. El counts de la recopilación sigue contando ese lugar y lo que costó.

Puedes leer los lugares de una recopilación durante 30 días después de empezarla, hasta resultsExpireAt. Después borramos su lista de lugares y su progreso en vivo. La recopilación en sí se queda, con sus conteos y cobros.

Cuando se borran, su página de lugares vuelve vacía y se rechaza cualquier exportación, así que exporta lo que quieras conservar antes de que pase. Para recuperar los lugares, empieza la misma recopilación: los cuadros buscados en los últimos 180 días vuelven gratis.