GET # Google Reviews API Get Google Maps reviews for any business using their data\_id with token-based pagination. ## 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 ## Related Endpoints [ ### Google Search and Review Look up any place by name and get its first page of reviews in one request. Returns the data\_id for use with this endpoint. ](/docs/endpoints/google-search-and-review)[ ### Google Travel Search Search hotels by destination with nightly and total prices for your dates ](/docs/endpoints/google-travel/search)[ ### TripAdvisor Reviews Get comprehensive reviews from TripAdvisor ](/docs/endpoints/tripadvisor/hotel-reviews) Request ```curl 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" ``` Response ```json { "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 } } ``` ```json { "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" } ```