Lugares · GET /v1/places/{place}

Lugares

Consulta un lugar que ya guardamos, con cualquier id o enlace de Maps que tengas de él, y mira qué significa cada campo de un lugar.

Consulta un lugar

Pon el lugar al final de la URL. Sirve cualquiera de estos:

nuestro id del lugar, que viene en cualquier respuesta;
el cid de Google, una cadena de dígitos. El dataId también sirve, porque el cid va dentro;
el place ID de Google, como ChIJ…;
un enlace de Google Maps al lugar. Abre el lugar en Maps y copia el enlace completo de la barra de direcciones.

Codifica el enlace antes de ponerlo en la URL, por ejemplo con encodeURIComponent. El SDK lo hace por ti. Consultar es gratis:

curl https://api.gmaps.dev/v1/places/12345678901234567890 \
  -H "Authorization: Bearer $GMAPS_API_KEY"

Un enlace corto, como los de maps.app.goo.gl, esconde el lugar hasta que se abre, así que se rechaza con 400 VALIDATION_ERROR: ábrelo en un navegador y envía el enlace completo. Un enlace a una búsqueda o a una zona del mapa, y no a un solo lugar, se rechaza igual.

Solo lugares que ya guardamos

Una consulta nunca busca. Lee los lugares que ya guardamos, y esos vienen de búsquedas y recopilaciones, tuyas o de cualquier otra persona.

Cuando aún no hemos guardado un lugar, la respuesta es 404 PLACE_NOT_FOUND. Eso no significa que el lugar no exista. Para traerlo, busca en la zona donde está, con una palabra que lo describa, como su categoría. Cuando lleguen los lugares nuevos, consúltalo otra vez.

Consultar un negocio que pidió quedar fuera da la misma respuesta, y sigue fuera. Datos y privacidad explica cómo funciona.

Una consulta tampoco actualiza un lugar. meta.scrapedAt dice cuándo lo recopilamos por última vez. Lo recopilamos otra vez cuando alguien busca en su zona después de que venció nuestra última búsqueda allí. Cobertura dice cuánto tarda eso.

Guarda el cid como texto

Los cid de Google son demasiado largos para un número de JavaScript, y también para muchos otros lenguajes y hojas de cálculo. Leído como número, un cid pierde sus últimos dígitos y apunta a otro lugar, o a ninguno:

Number("12345678901234567890"); // 12345678901234567000

Por eso siempre lo enviamos como texto. Mantenlo así: guárdalo en una columna de texto e impórtalo a la hoja de cálculo como texto.

Qué trae un lugar

Toda respuesta con lugares usa esta misma forma: una búsqueda, los lugares de una recopilación y una consulta. Este es un lugar completo:

{
  "id": "5b0c8e0a-2f4d-4c1e-9a57-3d2b8f6e1c90",
  "identity": {
    "cid": "12345678901234567890",
    "placeId": "ChIJmadeUpPlaceIdForTheDocs",
    "dataId": "0x94dce35aa0000001:0xab54a98ceb1f0ad2",
    "name": "Padaria Estrela do Centro",
    "category": "Padaria",
    "mapsUrl": "https://maps.google.com/?cid=12345678901234567890",
    "description": "Pães de fermentação natural e café coado.",
    "status": null
  },
  "contact": {
    "phones": ["+55 41 0000-0000"],
    "website": "https://example.com"
  },
  "location": {
    "address": "R. Exemplo, 100 - Centro, Curitiba - PR, 80000-000",
    "completeAddress": {
      "borough": "Centro",
      "street": "R. Exemplo, 100",
      "city": "Curitiba",
      "postalCode": "80000-000",
      "state": "PR",
      "country": "BR"
    },
    "city": "Curitiba",
    "state": "PR",
    "country": "BR",
    "lat": -25.4296,
    "lng": -49.2713,
    "plusCode": "3QHH+5F Curitiba"
  },
  "ratings": {
    "rating": 4.6,
    "reviewCount": 212,
    "reviewsPerRating": { "1": 4, "2": 3, "3": 11, "4": 38, "5": 156 }
  },
  "hours": {
    "timezone": "America/Sao_Paulo",
    "openHours": {
      "segunda-feira": ["7:00–19:00"],
      "sábado": ["7:00–13:00"]
    },
    "popularTimes": { "segunda-feira": { "7": 35, "8": 60, "18": 80 } }
  },
  "commerce": {
    "priceRange": "R$ 20–40",
    "about": [
      {
        "id": "accessibility",
        "name": "Acessibilidade",
        "options": [
          {
            "name": "Entrada acessível para cadeirantes",
            "enabled": true
          }
        ]
      }
    ],
    "creditCardsAccepted": [],
    "menu": null,
    "orderOnline": [
      { "link": "https://example.com/pedidos", "source": "example.com" }
    ],
    "reservations": []
  },
  "meta": {
    "scrapedAt": "2026-09-18T09:41:37.000Z",
    "firstSeenAt": "2026-03-02T15:20:04.000Z",
    "cached": true
  }
}

Un campo es null, o una lista vacía, cuando no tenemos el dato. Los nombres, las categorías y los horarios vienen en el idioma de la última búsqueda que recopiló el lugar, que puede no ser el que pediste. Un lugar nunca trae el texto de las reseñas, los nombres de quienes reseñaron ni fotos.

`identity`: qué lugar es

Campo	Qué contiene
`id`	Nuestro id del lugar. Nunca cambia.
`cid`	El id de Google del lugar, siempre como texto.
`placeId`	El place ID de Google.
`dataId`	Otro id de Google del lugar, con el cid dentro.
`name`	El nombre del negocio.
`category`	Lo que el negocio dice que es, en el idioma de la búsqueda: `Bakery`, `Padaria`.
`mapsUrl`	Un enlace al lugar en Google Maps.
`description`	La descripción corta de la propia ficha.
`status`	Lo que decía la ficha sobre el lugar cuando lo recopilamos: `Permanently closed`, `Fechado permanentemente`.

`contact`: cómo contactarlo

Campo	Qué contiene
`phones`	Sus números de teléfono, como los muestra la ficha.
`website`	Su sitio web.
`emails`	Correos electrónicos que encontramos del lugar. Este campo solo llega a las cuentas que tienen un plan con correos electrónicos y aceptaron la política de uso aceptable. Para las demás, ni siquiera aparece. Si una cuenta que puede leer correos recibe el lugar sin `emails`, no tenemos ninguna dirección de él. Correos electrónicos tiene más detalles.

`location`: dónde está

Campo	Qué contiene
`address`	La dirección en una sola línea, como la escribe la ficha.
`completeAddress`	La misma dirección por partes: `street`, `borough`, `city`, `postalCode`, `state` y `country`. Cualquier parte puede ser `null`.
`city, state, country`	Su ciudad, estado y país.
`lat, lng`	Dónde está en el mapa, en grados. Las dos son números, o las dos son `null`.
`plusCode`	Su plus code: un código corto para ese punto del mapa.

`ratings`: cómo lo califican

Campo	Qué contiene
`rating`	La calificación promedio, de 0 a 5. `null` cuando nadie lo ha calificado.
`reviewCount`	Cuántas reseñas tiene.
`reviewsPerRating`	Cuántas reseñas dieron cada cantidad de estrellas. Si la ficha omite una cantidad de estrellas, aquí también falta.

`hours`: cuándo abre

Campo	Qué contiene
`timezone`	Su zona horaria, como `America/Sao_Paulo`.
`openHours`	Cada día y las horas en que abre, escritos como los escribe la ficha.
`popularTimes`	Qué tan concurrido suele estar. Para cada día, cada hora de `0` a `23` tiene un número de 0 a 100, donde 100 es su momento más concurrido.

`commerce`: qué ofrece

Campo	Qué contiene
`priceRange`	Qué tan caro es, como lo muestra la ficha, por ejemplo `R$ 20–40`.
`about`	Lo que el lugar dice de sí mismo, en grupos como accesibilidad. Cada opción tiene un `name`, si está activa (`enabled`) y, a veces, `values`.
`creditCardsAccepted`	Las tarjetas que acepta.
`menu`	Un enlace a su menú y quién lo ofrece.
`orderOnline`	Enlaces para pedir en línea, cada uno con quién lo ofrece, como una app de entregas.
`reservations`	Enlaces para reservar, cada uno con quién lo ofrece.

`meta`: nuestro registro del lugar

Campo	Qué contiene
`scrapedAt`	Cuándo lo recopilamos por última vez.
`firstSeenAt`	Cuándo lo guardamos por primera vez.
`cached`	`true` cuando vino de lo que ya habíamos guardado, así que no costó nada. Una consulta siempre dice `true`.

Lugares

Consulta un lugar

Solo lugares que ya guardamos

Guarda el cid como texto

Qué trae un lugar

identity: qué lugar es

contact: cómo contactarlo

location: dónde está

ratings: cómo lo califican

hours: cuándo abre

commerce: qué ofrece