GET

Google Reviews API

Get Google Maps reviews for any business using their data_id with token-based pagination.

Copy for your AI agent

Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.

Overview

Token-Based Pagination

Each response includes a next_page_token for fetching additional reviews. Continue requesting until has_more is false.

The Google Reviews endpoint provides access to customer reviews from Google Maps. Each request returns up to 10 reviews along with a pagination token for fetching more. Use the data_id parameter (Google's internal identifier) to specify which business to get reviews for.

Endpoint URL

GET https://api.stayapi.com/v1/google_reviews/reviews

Finding data_id

Use the /search-and-review endpoint to find the data_id for any business. It searches by name and returns the data_id you can use for subsequent requests.

reviews[].owner_response is a nullable string containing management reply text. owner_response_date is a separate nullable source date string. These are not nested objects; missing replies remain null.

Parameters

Parameter	Type	Required	Description
data_id	string	Required	Google Maps data_id for the place (e.g., 0x80c8c430cb5147bd:0x82f2c7c5d9d10d84): two hexadecimal numbers of up to 16 digits, each starting with `0x`, joined by a colon. Anything else returns 400.
next_page_token	string	Optional	Token for fetching the next page of reviews. Obtained from the previous response's next_page_token field. The token is opaque (it starts with `gt:`): pass it back unchanged, with the same `data_id` and `sort_by`. A token from an earlier version (one that does not start with `gt:`) returns 400; start again from the first page.
sort_by	string	Optional	Sort order for reviews. Options: most_relevant (default), newest, highest_rating, lowest_rating
hl	string	Optional	Language code for reviews (e.g., en, es, fr). Default: en

Response Structure

Success Response (200 OK)

{
  "success": true,
  "data_id": "0x80c8c430cb5147bd:0x82f2c7c5d9d10d84",
  "place_name": "Bellagio Hotel & Casino",
  "place_address": "3600 S Las Vegas Blvd, Las Vegas, NV 89109, United States",
  "total_reviews": 144222,
  "average_rating": 4.7,
  "reviews": [
    {
      "review_id": "ChdDSUhNMG9nS0VJQ0FnSURiOTlySm1RRRAB",
      "rating": 5.0,
      "text": "Amazing hotel with fantastic fountains and excellent service...",
      "date": "a week ago",
      "iso_date": "2026-10-13T18:00:00Z",
      "iso_date_source": "photo",
      "iso_date_of_last_edit": null,
      "photos": [
        "https://lh3.googleusercontent.com/grass-cs/..."
      ],
      "reviewer": {
        "name": "John Smith",
        "profile_picture": "https://lh3.googleusercontent.com/...",
        "reviews_count": null,
        "local_guide": false
      },
      "likes": 0,
      "owner_response": "Thank you for your wonderful review...",
      "owner_response_date": "3 days ago"
    }
    // ... up to 10 reviews per page
  ],
  "next_page_token": "gt:Ci8IARInCgoAP72F9UtFIG__EhDNB2mzUoLEeIXrHW4AAAAAGgf_Al9UtFIGGAAiAA:10",
  "has_more": true,
  "search_metadata": {
    "search_url": null,
    "datetime": "2026-10-20T14:35:42.788642",
    "total_time_taken": null
  }
}

Response Fields

data_id: Google Maps data_id for the place
place_name: Name of the business
place_address: Address of the business
total_reviews: Total number of reviews for the place on Google
average_rating: Overall rating of the business (1-5)
reviews: Array of review objects (up to 10 per page)
reviews[].date / iso_date: date is Google's relative label in the hl language ("a week ago") and is always present. iso_date is UTC and may be null; iso_date_source gives its precision (see Review Dates below).
next_page_token: Pagination token - Use this to fetch the next page of reviews. Opaque: pass it back unchanged. null when there are no further pages.
has_more: Whether more reviews are available (continue pagination if true). Some places, for example a harbour or a park, return only their first 5 reviews with has_more: false.

Review Dates and Reviewer Details

Every review has date, Google's relative label. iso_date (UTC) depends on iso_date_source:

"review": the exact review time (YYYY-MM-DDTHH:MM:SSZ), and iso_date_of_last_edit is set too. Available on every page, including paginated responses; best-effort, so individual reviews may instead have a photo-derived date or null.
"photo": the upload time of the reviewer's earliest attached photo, at hour precision (YYYY-MM-DDTHH:00:00Z), or the day (YYYY-MM-DD) when only the day is known.
null: no date is available; iso_date is null.

iso_date_of_last_edit is the exact time of the last edit and is set only when iso_date_source is "review". Exact likes, reviewer.reviews_count and reviewer.local_guide remain available for up to 5 reviews on the first page only, independently of date availability; on other reviews these are 0, null and false. photos and owner replies are filled on every page.

place_name, place_address, total_reviews and average_rating are filled on the first page only; later pages return null or 0 for them.

Pagination

Each request returns up to 10 reviews along with a next_page_token. To get more reviews, include this token, unchanged, in your next request with the same data_id and sort_by. Continue until has_more is false or next_page_token is null.

# Fetch all reviews using pagination
import requests

data_id = '0x80c8c430cb5147bd:0x82f2c7c5d9d10d84'
all_reviews = []
next_token = None

while True:
    params = {'data_id': data_id, 'sort_by': 'newest'}
    if next_token:
        params['next_page_token'] = next_token

    response = requests.get(
        'https://api.stayapi.com/v1/google_reviews/reviews',
        params=params,
        headers={'X-API-Key': 'YOUR_API_KEY'}
    )

    data = response.json()
    all_reviews.extend(data['reviews'])

    if not data.get('has_more') or not data.get('next_page_token'):
        break

    next_token = data['next_page_token']

print(f"Fetched {len(all_reviews)} total reviews")

Pagination Tips:

• Each page returns up to 10 reviews
• Keep the same sort_by on every page of one pagination run
• Tokens are valid for a limited time - don't store them long-term

Common Use Cases

📊 Reputation Management

Monitor and analyze customer feedback across your hotel portfolio. Track sentiment trends, identify common complaints, and respond to reviews promptly.

# Get recent reviews to monitor feedback
reviews = get_google_reviews(data_id, sort='newest')
negative_reviews = [r for r in reviews if r['rating'] <= 2]
# Alert management about negative reviews requiring response

🔍 Competitive Analysis

Compare review ratings and feedback between competing hotels. Identify strengths and weaknesses to improve your service offering.

💬 Content Enhancement

Display authentic Google Reviews on your website to build trust with potential customers and improve conversion rates.

Error Handling

Code	Type	Description
400	INVALID_PARAMETERS	Malformed data_id (see the format above), or a `next_page_token` that does not start with `gt:` (from an earlier version; restart from the first page)
404	NO_RESULTS	No reviews found for the provided data_id
429	RATE_LIMITED	Too many requests. Please retry after the specified time
500	INTERNAL_ERROR	Server error. Please try again later
502	UPSTREAM_ERROR	Error fetching data from Google Reviews
503	SERVICE_UNAVAILABLE	Google reviews are temporarily unavailable. Retry after the `Retry-After` header.
504	UPSTREAM_TIMEOUT	Google did not answer in time. Retry the request

Rate Limits

This endpoint is subject to the standard API rate limits based on your subscription tier.

✓ Free tier: 10 requests/day
✓ Basic: 1,000 requests/day
✓ Pro: 10,000 requests/day
✓ Enterprise: Custom limits

curl -X GET "https://api.stayapi.com/v1/google_reviews/reviews?data_id=0x80c8c430cb5147bd:0x82f2c7c5d9d10d84&sort_by=newest" \
  -H "X-API-Key: YOUR_API_KEY"

# To get the next page, use the next_page_token:
curl -X GET "https://api.stayapi.com/v1/google_reviews/reviews?data_id=0x80c8c430cb5147bd:0x82f2c7c5d9d10d84&sort_by=newest&next_page_token=gt%3ACi8IARInCgoAP72F9UtFIG__EhDNB2mzUoLEeIXrHW4AAAAAGgf_Al9UtFIGGAAiAA%3A10" \
  -H "X-API-Key: YOUR_API_KEY"

const dataId = "0x80c8c430cb5147bd:0x82f2c7c5d9d10d84";

// First request
const response = await fetch(
  `https://api.stayapi.com/v1/google_reviews/reviews?` +
  new URLSearchParams({
    data_id: dataId,
    sort_by: "newest"
  }),
  {
    headers: { "X-API-Key": "YOUR_API_KEY" }
  }
);

const data = await response.json();
console.log(`Place: ${data.place_name}`);
console.log(`Total reviews: ${data.total_reviews}`);
console.log(`Reviews on this page: ${data.reviews.length}`);

// If there are more reviews, use next_page_token
if (data.has_more && data.next_page_token) {
  const nextResponse = await fetch(
    `https://api.stayapi.com/v1/google_reviews/reviews?` +
    new URLSearchParams({
      data_id: dataId,
      sort_by: "newest",
      next_page_token: data.next_page_token
    }),
    {
      headers: { "X-API-Key": "YOUR_API_KEY" }
    }
  );
  // ... continue pagination
}

import requests

data_id = "0x80c8c430cb5147bd:0x82f2c7c5d9d10d84"

# First request
response = requests.get(
    "https://api.stayapi.com/v1/google_reviews/reviews",
    params={
        "data_id": data_id,
        "sort_by": "newest"
    },
    headers={"X-API-Key": "YOUR_API_KEY"}
)

data = response.json()
print(f"Place: {data['place_name']}")
print(f"Total reviews: {data['total_reviews']}")
print(f"Reviews on this page: {len(data['reviews'])}")

# Fetch all reviews with pagination
all_reviews = data['reviews']
next_token = data.get('next_page_token')

while data.get('has_more') and next_token:
    response = requests.get(
        "https://api.stayapi.com/v1/google_reviews/reviews",
        params={
            "data_id": data_id,
            "sort_by": "newest",
            "next_page_token": next_token
        },
        headers={"X-API-Key": "YOUR_API_KEY"}
    )
    data = response.json()
    all_reviews.extend(data['reviews'])
    next_token = data.get('next_page_token')

print(f"Total fetched: {len(all_reviews)} reviews")

$dataId = "0x80c8c430cb5147bd:0x82f2c7c5d9d10d84";

// First request
$params = [
    "data_id" => $dataId,
    "sort_by" => "newest"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.stayapi.com/v1/google_reviews/reviews?" . http_build_query($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo "Place: " . $data["place_name"] . "\n";
echo "Total reviews: " . $data["total_reviews"] . "\n";
echo "Reviews on this page: " . count($data["reviews"]) . "\n";

// Continue with pagination using next_page_token
if ($data["has_more"] && !empty($data["next_page_token"])) {
    $params["next_page_token"] = $data["next_page_token"];  // keep data_id and sort_by
    // ... make next request
}

Response

{
  "success": true,
  "data_id": "0x80c8c430cb5147bd:0x82f2c7c5d9d10d84",
  "place_name": "Bellagio Hotel & Casino",
  "place_address": "3600 S Las Vegas Blvd, Las Vegas, NV 89109, United States",
  "total_reviews": 144222,
  "average_rating": 4.7,
  "reviews": [
    {
      "review_id": "ChdDSUhNMG9nS0VJQ0FnSURiOTlySm1RRRAB",
      "rating": 5.0,
      "text": "Amazing hotel with fantastic fountains. The rooms are beautiful and the staff is incredibly friendly...",
      "date": "a week ago",
      "iso_date": "2026-10-13T18:42:10Z",
      "iso_date_source": "review",
      "iso_date_of_last_edit": "2026-10-13T18:42:10Z",
      "photos": [],
      "reviewer": {
        "name": "John Smith",
        "profile_picture": "https://lh3.googleusercontent.com/...",
        "reviews_count": 25,
        "local_guide": false
      },
      "likes": 3,
      "owner_response": "Thank you for your wonderful review!",
      "owner_response_date": "3 days ago"
    }
  ],
  "next_page_token": "gt:Ci8IARInCgoAP72F9UtFIG__EhDNB2mzUoLEeIXrHW4AAAAAGgf_Al9UtFIGGAAiAA:10",
  "has_more": true,
  "search_metadata": {
    "search_url": null,
    "datetime": "2026-10-20T14:35:42.788642",
    "total_time_taken": null
  }
}

{
  "type": "https://api.stayapi.com/errors/invalid-parameters",
  "title": "Invalid Parameters",
  "status": 400,
  "detail": "data_id must be a Google Maps data_id like 0x80c8c430cb5147bd:0x82f2c7c5d9d10d84",
  "instance": "/v1/google_reviews/reviews",
  "provider": "google_reviews",
  "error_code": "INVALID_PARAMETERS",
  "correlation_id": "req_abc123"
}