# Google Reviews API

Google Reviews API documentation for developers who need Google Maps place reviews in structured JSON. Scrappa's `GET /api/maps/reviews` endpoint fetches review text, star ratings, reviewer profile fields, timestamps, photos, language, review form attributes, review links, likes, and owner responses from public Google Maps business listings.

## Google Maps reviews API for business review data

Use this endpoint when you already have a Google Maps `business_id` and need reviews for reputation monitoring, local SEO research, review analytics, customer sentiment analysis, lead enrichment, or competitive benchmarking. It is built for Google Maps reviews scraping workflows where the output needs to be normalized JSON instead of browser HTML.

## Google Places API reviews endpoint documentation

Use this page as Scrappa's Google Places API reviews endpoint documentation when the official Google Places or Google Business Profile APIs do not return the public Maps review fields your workflow needs. The request path is `GET /api/maps/reviews`, the required identifier is `business_id`, and the response is ready for review monitoring, local business enrichment, and reputation analytics pipelines.

## What the reviews endpoint returns

Each review item can include `review_id`, `review_text`, `rating`, `timestamp`, `review_updated_timestamp`, `review_link`, `review_likes`, reviewer identifiers, author profile links, author review counts, Local Guide level, review language, images, owner response text, and owner response timestamps. `timestamp` is the original review creation time when Google exposes it; `review_updated_timestamp` is the edited/display timestamp used by Google Maps UI when available. The endpoint keeps every valid review returned by Google Maps and removes duplicate review IDs across fetched pages. First-party reviews have `review_source: "Google"`, a numeric Google contributor `author_id`, and `is_google_review: true`. Syndicated reviews remain available with their actual provider, such as `Jameda`, `GoLocal`, or `Trustpilot`, and `is_google_review: false`; an unknown provider is reported as `External`. The `review_count` and `reviews_per_rating` fields from Google Maps Business Details describe Google's listing totals, but they do not guarantee that every review is available through the paginated public feed.

## Filtering, sorting, localization, and pagination

Use `search` to filter reviews by keyword, `sort` to request most relevant, newest, highest-rated, or lowest-rated reviews, and `page` or `pages` to paginate through larger review sets. A `nextPage` token is reusable for 30 minutes after it is issued and is valid only for the same business. An invalid or expired token returns a non-billable `410` response with `error_code: "continuation_token_invalid_or_expired"`; restart from the first page by omitting `page`. For deeper collection, prefer a multi-page `pages` request because Scrappa follows continuation tokens inside one request and starts bounded recovery when a full page unexpectedly omits its token. Google can still stop returning a continuation token before the displayed review count is reached, so `nextPage: null` does not prove that every displayed review was retrievable. Use `termination_reason`, `feed_exhausted`, `continuation_retries`, and `continuation_recovered` to diagnose how collection stopped. Use `hl` and `gl` when your review monitoring workflow needs localized review text, region-specific behavior, or country-specific Google Maps results.

## How to get the business ID before fetching reviews

Start with [Google Maps Simple Search](/docs/google-maps-api/simple_search) when you know a business name, category, or address. Use [Google Maps Business Details](/docs/google-maps-api/google_business_details) when you need the business profile, rating summary, review count, hours, photos, and place identifiers before calling the reviews endpoint. For one known review, use [Single Review](/docs/google-maps-api/google_single_review).

- **Documentation:** [https://scrappa.co/docs/google-maps-api/google_reviews](https://scrappa.co/docs/google-maps-api/google_reviews)
- **API group:** Google Maps API
- **Endpoint:** `GET https://scrappa.co/api/maps/reviews`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `business_id` | string | Yes | The assigned business id by Google (e.g. 0x60188b88b7d8f7ab:0x2133080e9923eaac). |
| `search` | string | No | Filter reviews by keyword. |
| `sort` | integer | No | Sorting order: 1 for Most Relevant, 2 for Newest, 3 for Highest Rating, 4 for Lowest Rating. |
| `page` | string | No | Continuation token returned as `nextPage` by a previous response. Reusable for 30 minutes with the same business ID. Invalid or expired tokens return a non-billable 410 response. |
| `pages` | integer | No | Number of pages to fetch in a single request (1-50). Each successfully fetched page counts as one API credit. Multi-page requests are preferred for deeper pagination. The response includes termination and continuation-recovery diagnostics. |
| `limit` | integer | No | Maximum number of reviews to return per page. |
| `hl` | string | No | Language code for results. Default: en |
| `gl` | string | No | Country/region code for geo-filtering. Default: us |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/maps/reviews?business_id=0x60188b88b7d8f7ab%3A0x2133080e9923eaac"
```

## Example response

```json
{
    "items": [
        {
            "review_id": "ChZDSUhNMG9nS0VJQ0FnSUM1bnYzQzJ3EAE",
            "review_text": [
                "Great place with excellent service!"
            ],
            "rating": 5,
            "timestamp": 1704067200000,
            "review_updated_timestamp": 1704153600000,
            "review_link": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VJQ0FnSUM1bnYzQzJ3EAE",
            "review_source": "Google",
            "is_google_review": true,
            "review_likes": 12,
            "author_id": "123456789012345678901",
            "author_link": "https://www.google.com/maps/contrib/123456789012345678901?hl=en",
            "author_name": "John Doe",
            "author_profile_photo": "https://lh3.googleusercontent.com/a-/example_photo.jpg",
            "author_review_count": 45,
            "author_reviews_link": "https://www.google.com/maps/contrib/123456789012345678901/reviews",
            "author_photo_count": 12,
            "author_local_guide_level": 3,
            "owner_response_timestamp": null,
            "owner_response_text": null,
            "owner_response_language": null,
            "review_language": [
                "en"
            ],
            "review_form": [],
            "images": []
        }
    ],
    "nextPage": null,
    "termination_reason": "token_missing",
    "feed_exhausted": null,
    "continuation_retries": 0,
    "continuation_recovered": false
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 410 | Continuation Token Invalid or Expired | The continuation token is unknown, expired, or belongs to a different business. Omit `page` to restart pagination. This response is not billed. |
| 422 | Validation Error | The business ID, pagination, sorting, or locale parameters failed validation. |
| 503 | Reviews Temporarily Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## Frequently asked questions

### Is there a Google Reviews API for developers?

Scrappa provides a Google Reviews API endpoint for public Google Maps listings. Send a `business_id` to `GET /api/maps/reviews` and the endpoint returns normalized review JSON with ratings, review text, authors, timestamps, images, owner responses, and pagination.

### What does the Google Maps reviews endpoint return?

The endpoint returns first-party Google reviews and syndicated reviews exposed by Google Maps, with `review_id`, `review_text`, `rating`, timestamps, reviewer fields, images, owner responses, and pagination. Use `review_source` for the actual provider. `is_google_review: true` together with a numeric Google contributor `author_id` is the stable signal for a genuine Google review.

### How do I call the Google Reviews API endpoint?

Send `GET /api/maps/reviews` with `business_id` and your `x-api-key` header. Optional parameters include `search`, `sort`, `page`, `pages`, `limit`, `hl`, and `gl` for filtering, ordering, pagination, and localization.

### Is this official Google Places API reviews documentation?

No. This is Scrappa's Google Places and Google Maps reviews endpoint documentation. It helps developers retrieve public place reviews as structured JSON through Scrappa's API.

### Which place identifier does the Google Reviews API use?

Use the Google `business_id` in `0x...:0x...` format. You can get that identifier from Scrappa Google Maps Simple Search or Business Details responses before calling the reviews endpoint.

### Can I filter or sort Google Maps reviews?

Yes. Use `search` to filter reviews by keyword and `sort` to request most relevant, newest, highest-rating, or lowest-rating review order. Use `page` or `pages` when you need more than one page of reviews.

### Can I retrieve every review shown in the Google Maps review count?

Not always. Google Maps can stop exposing continuation tokens before the displayed review count is reached. Use a multi-page `pages` request for the most robust collection path and inspect the pagination diagnostic fields to see why the response stopped.

### How long is a Google Reviews continuation token valid?

A `nextPage` token is reusable for 30 minutes after Scrappa issues it and must be used with the same business ID. If the token is invalid or expired, the endpoint returns a non-billable `410` response. Omit `page` to restart pagination.

## Related endpoints

- [Google Maps Simple Search](https://scrappa.co/docs/google-maps-api/simple_search)
- [Business Details](https://scrappa.co/docs/google-maps-api/google_business_details)
- [Single Review](https://scrappa.co/docs/google-maps-api/google_single_review)
- [Photos](https://scrappa.co/docs/google-maps-api/google_maps_photos)

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)