Cobertura

Envía los mismos keywords, geo y lang que enviarías a una búsqueda. La cobertura solo lee lo que ya hicimos ahí: no inicia nada, no cambia nada y no cuesta nada.

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

Esta es una zona que habíamos buscado en 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 cuando buscamos todos los cuadros hace poco, partial cuando solo algunos, new cuando ninguno.
• squaresTotal: cuántos cuadros suman esta zona y estos términos.
• squaresCovered: cuántos de ellos buscamos hace tan poco que todavía sirven.
• squaresToSearch: cuántos faltan. Una recopilación buscaría en esos.
• placesKnown: cuántos lugares ya guardamos en los cuadros cubiertos. Una búsqueda los entrega gratis.
• searchedAt: cuándo buscamos los cuadros cubiertos, el más antiguo y el más reciente. null cuando no hay ninguno cubierto.
• freshForDays y emptyFreshForDays: cuánto tiempo sigue cubierto un cuadro, como explican las secciones siguientes.

Una búsqueda en el mapa trae un número limitado de lugares, sin importar el tamaño de la zona. Por eso dividimos la zona en cuadros pequeños y buscamos en cada uno, una vez por cada término. Una zona pequeña es un solo cuadro; una más grande es una cuadrícula de ellos.

Un cuadro está cubierto para todos. Si alguien más lo buscó hace poco, también cuenta para ti, y sus lugares son gratis.

Cada cuadro pertenece a un término y a un idioma. panadería y cafetería son cuadros distintos, y también lo es el mismo término en pt y en en. Las mayúsculas, los acentos y los espacios de más no importan.

Un cuadro sigue cubierto por un tiempo después de buscarlo:

• 180 días cuando trajo lugares;
• 7 días cuando volvió vacío. Un cuadro vacío puede significar que no hay nada ahí, o que la búsqueda no funcionó, así que volvemos a mirar antes.

Una zona es fresh cuando todos sus cuadros están cubiertos. Un cuadro que se está buscando ahora no cuenta hasta que termine su búsqueda. Cuando se acaban sus días, vuelve a contar como no buscado, y la siguiente recopilación ahí lo busca otra vez y actualiza sus lugares. Un lugar que recopilamos hace más de 180 días vuelve a costar 1 crédito, como uno nuevo.

placesKnown: 0 nunca significa que no haya negocios ahí. Significa una de estas dos cosas:

• coverage es new o partial: todavía no buscamos toda esta zona para este término e idioma. Una búsqueda recopilará el resto.
• coverage es fresh: buscamos hace poco y no encontramos nada para este término. Prueba otra palabra para lo mismo. Volveremos a mirar cuando se acaben los días de esos cuadros.

Las tres leen los mismos cuadros y las tres son gratis:

• Una búsqueda revisa primero la cobertura, y su campo coverage da la misma respuesta. Pide solo la cobertura cuando quieras saber, no recopilar.
• Una estimación, en POST /v1/collections/quote, agrega lo máximo que podría costar una recopilación y algunos de los lugares que ya guardamos. Recopilaciones lo explica.
• La cobertura agrega cuándo se buscaron los cuadros y cuánto tiempo siguen cubiertos. Úsala para decidir si vale la pena recopilar una zona otra vez.

La cobertura cuenta todos los lugares de los cuadros cubiertos. Una búsqueda o una estimación con minRating cuenta solo los lugares que pasan ese filtro, así que su placesKnown puede ser menor.

La zona sigue las mismas reglas que una búsqueda. Una ciudad que no podemos identificar responde 422 GEO_UNRESOLVED, y una zona demasiado grande para una sola solicitud responde 400 VALIDATION_ERROR. Búsqueda explica ambos casos.