# Google Maps: List reviews

`google_maps/reviews/list` · version 1.1.0 · pilot · 2 credits a call

One page of a Google Maps place's reviews, 10 at most, with their rating, text, author, photos and owner reply.

Categories: Reviews

## When to use

You have a place (its `id` from google_maps/places/search, or its cid or feature id) and need what people wrote about it: rating, full text and its translation, date, visit, author, photos, reactions, the owner's reply, and the ratings by aspect (food, service...) when the reviewer gave them. Follow `next` for the following page, as far as you need.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "google_maps", "operation": "reviews/list", "options": {"place": "ChIJ39Y-tdg1fYcRQcZcBb499do", "sort": "newest"}}'
```

The answer's `next` is the whole call for the following page: send it as it is. `null` on the last page.

Beside `options`, the call takes:

| Parameter | Type | Description |
|---|---|---|
| `fields` | array of string | The record fields to keep, by path (`title`, `address.city`); `object`, `id` and `position` always come. Left out: every field. |
| `limit` | integer | Only the first N records of this call (1 to 1000), in the call's order; the call costs the same, and `next` keeps the limit. Left out: every record. |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `place` | string | yes |  | The place: its Google place id (ChIJ..., the `id` google_maps/places/search and places/get return), its cid (`ids.cid`, the number in a maps?cid= link), its feature id (`ids.feature_id`, 0x...:0x...), or the link of its page on Google Maps as the browser shows it. A short link (maps.app.goo.gl) is not taken: open it and copy the page's link. With only a name, get the place with google_maps/places/get first (1 credit). |
| `sort` | `newest`, `relevant`, `highest`, `lowest` |  | `"newest"` | The order Google Maps offers: newest first, most relevant (its own), highest rating first, lowest first. `newest` is the order that reaches every review of a place; Google stops the others after about 1,500. |
| `language` | string |  | `"en"` | An ISO 639-1 code (a regional form such as pt-BR is not taken yet). Reviews written in it come first with `sort: relevant`, and aspect labels are written in it. `text` is always as its author wrote it (its `language` says which); a review written in another language also comes with Google's `translation` into this one. |
| `cursor` | string |  |  | Where to continue, from `next` in an answer, as it is: opaque, and only for the place and sort it was given with (otherwise `invalid_cursor`). |

## Record

Each item of `results`. Every field is always present, `null` when the site gives nothing.

| Field | Type | Description |
|---|---|---|
| `object` | `"review"` | The kind of record: a review, whichever site it comes from. |
| `id` | string | Google's id of the review, stable across languages and sorts. |
| `position` | integer | Its rank in this order, across pages: 11 is the first of page 2. |
| `place` | object | The place reviewed, so reviews of several places can be told apart. |
| `place.cid` | string | The place's cid, as google_maps/places/search gives it in `ids.cid`. |
| `place.url` | string (uri) | The place on Google Maps. |
| `rating` | object |  |
| `rating.value` | integer, 1 to 5 |  |
| `rating.scale` | `5` | The best possible value. |
| `text` | string | null | The author's own words, whole, in their language (`language`), line breaks as \n; null for a rating alone. Quote this as what the author wrote. |
| `language` | string | null | The text's language, ISO 639-1, as Google detects it. |
| `translation` | object | null | Google's translation of `text` into the call's `language`, when the review is written in another. |
| `translation.language` | string |  |
| `translation.text` | string | Google's machine translation, not the author's words: say so when you quote it. |
| `published_at` | string (date-time) | When the review was posted, or last edited when `is_edited` (the first date is then not given), UTC. Tell reviews apart by `id`, never by date. |
| `is_edited` | boolean |  |
| `visit` | object | null | When the author says they went, when they said. |
| `visit.month` | string | null | YYYY-MM; null in a language we do not read yet. |
| `visit.text` | string | As Google writes it, in the call's language. |
| `reaction_count` | integer | null | People who reacted to the review (likes and other reactions). |
| `author` | object |  |
| `author.name` | string |  |
| `author.id` | string | null | The author's Google Maps contributor id. |
| `author.url` | string | null (uri) | The author's reviews on Google Maps. |
| `author.photo_url` | string | null (uri) |  |
| `author.review_count` | integer | null | Reviews the author has written, all places. |
| `author.photo_count` | integer | null | Photos the author has posted, all places. |
| `author.is_local_guide` | boolean |  |
| `photo_urls` | array of string | The photos posted with the review. |
| `owner_reply` | object | null | The place's reply, when it gave one (Google shows no date for it). |
| `owner_reply.text` | string |  |
| `aspects` | array | What the reviewer added beyond the text: a rating of an aspect (`rating`, 1 to 5), or answers to Google's questions (`answers`). `id` is stable across languages; `label` and the answers are in `language`. |
| `aspects[].id` | string |  |
| `aspects[].label` | string | null |  |
| `aspects[].rating` | integer | null, 1 to 5 |  |
| `aspects[].answers` | array of string | null |  |
| `url` | string | null (uri) | The review on Google Maps. |
| `source_url` | string (uri) | The place whose reviews these values were read from. |
| `observed_at` | string (date-time) | When they were read |

Example:

```json
{
  "object": "review",
  "id": "ChZDSUhNMG9nS0VBQUFBQUFBQUFBQUEQAQ",
  "position": 1,
  "place": {
    "cid": "15777584755905447489",
    "url": "https://www.google.com/maps?cid=15777584755905447489"
  },
  "rating": {
    "value": 5,
    "scale": 5
  },
  "text": "The best croissant in the district.\nFriendly staff, short wait even on Sunday.",
  "language": "en",
  "translation": null,
  "published_at": "2026-10-25T08:12:40Z",
  "is_edited": false,
  "visit": {
    "month": "2026-10",
    "text": "Oct 2026"
  },
  "reaction_count": 3,
  "author": {
    "name": "Jane Doe",
    "id": "100000000000000000000",
    "url": "https://www.google.com/maps/contrib/100000000000000000000/reviews",
    "photo_url": "https://lh3.googleusercontent.com/a/example",
    "review_count": 42,
    "photo_count": 12,
    "is_local_guide": true
  },
  "photo_urls": [
    "https://lh3.googleusercontent.com/grass-cs/example"
  ],
  "owner_reply": {
    "text": "Thank you Jane, see you soon!"
  },
  "aspects": [
    {
      "id": "dining_food",
      "label": "Food",
      "rating": 5,
      "answers": null
    },
    {
      "id": "dining_meal_type",
      "label": "Meal type",
      "rating": null,
      "answers": [
        "Breakfast"
      ]
    }
  ],
  "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VBQUFBQUFBQUFBQUEQAQ",
  "source_url": "https://www.google.com/maps?cid=15777584755905447489",
  "observed_at": "2026-10-26T09:00:00Z"
}
```

## Price

2 credits a call, whatever the page holds: a short last page costs a whole call. An empty page (a place without reviews, or an unknown place) and a failed call are free.

## Errors

| Code | Status | Retry | Message |
|---|---|---|---|
| `invalid_place` | 422 | no | This place id does not say which place it is on Google's side; send the place's cid (`ids.cid`) instead. |
| `invalid_cursor` | 422 | no | This cursor was not given by an answer; send `next` from the last answer as it is. |
| `site_unavailable` | 503 | yes | Google did not answer in time or refused the call; retry later (not charged). |
| `unexpected_answer` | 424 | no | Google answered in a shape we do not read yet; we are told and fix it, and it is not charged. Retrying now gives the same. |
| `missing_api_key` | 401 | no | No API key: send it as `Authorization: Bearer <key>`. |
| `invalid_api_key` | 401 | no | The key is not valid, or not anymore. |
| `insufficient_credits` | 402 | no | The call costs more credits than are left. |
| `unknown_operation` | 404 | no | No such source and operation in the catalog. |
| `timeout` | 408 | yes | The call did not finish within its deadline (not charged). |
| `invalid_body` | 422 | no | The body is not a call: source, operation, options. |
| `invalid_options` | 422 | no | An option is missing or out of its contract; `param` names it. |
| `invalid_idempotency_key` | 400 | no | The Idempotency-Key header is not printable ASCII, or too long. |
| `concurrency_limit` | 429 | yes | The plan's calls at a time are all in progress (Free 1, Starter 2, Pro 10, Team 50); retry when one has finished (not charged, never queued). |
| `service_busy` | 503 | yes | Too many calls at once on the account; retry in a few seconds. |
| `balance_unavailable` | 503 | yes | The balance could not be read; retry in a few seconds. |

## Changelog

- **1.1.0** (2026-11-13): `cursor` is opaque, as every cursor of the API: copy it from `next` as before. It holds Google's token sealed with the place and sort it continues, and is refused with another (`invalid_cursor`).
- **1.0.0** (2026-10-26): First version on the API v2.

Schema: https://api.lobstr.io/v2/catalog/google_maps/reviews/list · All operations: https://api.lobstr.io/v2/catalog.md
