Places

Put the place at the end of the URL. Any of these works:

• our id for it, from any answer;
• Google's cid, a string of digits. Its dataId works too, because the cid is inside it;
• Google's place ID, such as ChIJ…;
• a Google Maps link to the place. Open the place in Maps and copy the whole link from the address bar.

Encode a link before you put it in the URL, with encodeURIComponent for example. The SDK does that for you. A lookup is free:

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

A short link, such as one from maps.app.goo.gl, hides the place until it's opened, so it's refused with 400 VALIDATION_ERROR: open it in a browser and send the full link. A link to a search or a map area, rather than one place, is refused the same way.

A lookup never searches. It reads the places we've saved, and those come from searches and collections, by you or by anyone else.

When we haven't saved a place, the answer is 404 PLACE_NOT_FOUND. That doesn't mean the place doesn't exist. To bring it in, search the area it's in with a word that describes it, such as its category. Once the new places arrive, look it up again.

Looking up a business that asked to be left out gets the same answer, and it stays out. Data and privacy explains how that works.

A lookup doesn't refresh a place either. meta.scrapedAt says when we last collected it. We collect it again when someone searches its area after our last search there has expired. Coverage says how long that takes.

Google's cids are too long for a JavaScript number, and for many other languages and spreadsheets. Read as a number, a cid loses its last digits and points to another place, or to none:

Number("12345678901234567890"); // 12345678901234567000

So we always send it as a string. Keep it that way: store it in a text column, and import it into a spreadsheet as text.

Every answer with places in it uses this same shape: a search, a collection's places and a lookup. This is a whole place:

{
  "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
  }
}

A field is null, or an empty list, when we don't have it. Names, categories and hours are in the language of the last search that collected the place, which may not be the one you asked for. A place never carries review text, reviewer names or photos.

identity: which place it is

contact: how to reach it

location: where it is

ratings: how people rate it

hours: when it's open

commerce: what it offers

meta: our record of it