Lugares

Coloque o lugar no fim da URL. Serve qualquer um destes:

• o nosso id dele, que vem em qualquer resposta;
• o cid do Google, uma sequência de dígitos. O dataId também serve, porque o cid está dentro dele;
• o place ID do Google, como ChIJ…;
• um link do Google Maps para o lugar. Abra o lugar no Maps e copie o link inteiro da barra de endereço.

Codifique o link antes de colocar na URL, com encodeURIComponent, por exemplo. O SDK faz isso por você. A consulta é de graça:

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

Um link curto, como os de maps.app.goo.gl, esconde o lugar até ser aberto, então é recusado com 400 VALIDATION_ERROR: abra no navegador e mande o link completo. Um link para uma busca ou para uma região do mapa, e não para um lugar só, é recusado do mesmo jeito.

A consulta nunca faz uma busca. Ela lê os lugares que já salvamos, que vêm de buscas e coletas feitas por você ou por qualquer outra pessoa.

Quando ainda não salvamos um lugar, a resposta é 404 PLACE_NOT_FOUND. Isso não quer dizer que o lugar não existe. Para trazer esse lugar, busque a região onde ele fica com uma palavra que o descreva, como a categoria dele. Quando os lugares novos chegarem, consulte de novo.

Consultar uma empresa que pediu para ficar de fora dá a mesma resposta, e ela continua de fora. Dados e privacidade explica como isso funciona.

A consulta também não atualiza o lugar. meta.scrapedAt diz quando o coletamos pela última vez. Coletamos de novo quando alguém busca a região dele depois que a nossa última busca ali venceu. Cobertura diz quanto tempo isso leva.

Os cids do Google são longos demais para um número em JavaScript, e também em muitas outras linguagens e planilhas. Lido como número, o cid perde os últimos dígitos e passa a apontar para outro lugar, ou para nenhum:

Number("12345678901234567890"); // 12345678901234567000

Por isso ele sempre vai como texto. Mantenha assim: guarde numa coluna de texto e importe para a planilha como texto.

Toda resposta com lugares usa este mesmo formato: a busca, os lugares de uma coleta e a consulta. Este é um 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
  }
}

Um campo vem null, ou como lista vazia, quando não temos a informação. Nomes, categorias e horários vêm no idioma da última busca que coletou o lugar, que pode não ser o que você pediu. Um lugar nunca traz texto de avaliações, nome de quem avaliou nem fotos.

identity: qual lugar é

contact: como falar com ele

location: onde fica

ratings: como é avaliado

hours: quando abre

commerce: o que oferece

meta: o nosso registro dele