Google Maps API
Scrape Google Maps search results and place details as structured JSON
The Google Maps API is a specialized plugin that searches Google Maps, extracts structured data from place details pages, and returns paginated user reviews, all as clean JSON. Instead of rendering Google Maps in a headless browser and parsing protobuf, you send a query and get back ratings, addresses, opening hours, contact info, menus, popular times, reviews, and more.
Credit Usage: Each successful request costs 10 credits, same for Search, Place, and Reviews. For bulk processing, use the Async API with plugins.
Key Features
- Structured JSON Output: Get 25+ parsed fields per place including
place_id,data_id, coordinates, rating, reviews count, opening hours, menu, popular times, and service options. - Worldwide Coverage: Target any regional Google domain from
google.comtogoogle.co.jp,google.de,google.com.tr, and more. 150+ interface languages and 240+ country codes supported. - Precise Geo-Targeting: Constrain Maps searches to a specific area with the
ll=@lat,lng,zoomparameter. Without it, Google uses IP-based geolocation. - Full Place Details: Dedicated
/placeendpoint returns enriched fields not in search results:menu,popular_times,user_reviews,plus_code,rating_summary,summary, and a fullimagesarray. - Paginated Reviews: Fetch up to 20 reviews per request with sorting (newest, highest, lowest), topic filters, keyword search, and guided review details (food/service/atmosphere for restaurants, bed comfort/location/rooms for hotels).
- Localized Reviews: Non-English locales return both the original review text and a translation inline, plus guided-review
detailskeys in the requested language. - Owner Responses & Third-Party Sources: Business replies are returned inline. Hotels include reviews from Priceline, Tripadvisor, Booking.com, and Trip.com alongside Google reviews.
- Pagination: Navigate through up to 6 pages of Maps search results, or paginate reviews with
next_page_token. - No Blocks or CAPTCHAs: All anti-bot measures are handled automatically by Scrape.do.
Endpoints
| Endpoint | Method | Output | Description | Details |
|---|---|---|---|---|
/plugin/google/maps/search | GET | JSON | Search Google Maps and get a paginated list of places with ratings, addresses, and contact info | more |
/plugin/google/maps/place | GET | JSON | Fetch enriched details for a single place (menu, popular times, user reviews, images) | more |
/plugin/google/maps/reviews | GET | JSON | Paginated user reviews with ratings, text, images, guided details, topics, and owner responses | more |
Credit Costs
| Endpoint | Credits per Request |
|---|---|
/plugin/google/maps/search | 10 |
/plugin/google/maps/place | 10 |
/plugin/google/maps/reviews | 10 |
Authentication
All requests require your Scrape.do API token passed via the token query parameter:
https://api.scrape.do/plugin/google/maps/search?token=YOUR_TOKEN&q=pizza+new+yorkResponse Format
Responses are returned as JSON. Array fields always return [] when empty (never null). Object fields return null when absent.
Parameter keys are case-insensitive. You can use q, Q, hl, HL, etc.
Handling Transient Empty Results
Google occasionally returns an empty result shell for a query even when the underlying place data exists. The plugin surfaces this as 502 no results or, less commonly, an empty results array. These are almost always transient.
For paginated crawls, treat 502 no results as a retry-once condition rather than a permanent empty. A single retry is usually enough to recover. Only treat a repeated failure as a true "no results" state.
Error Handling
All endpoints return errors in a consistent JSON format:
{
"error": "error_code",
"message": "Human readable error message"
}Common Error Codes
| Status | Error | Description |
|---|---|---|
400 | token is required | Missing authentication token |
400 | q (search query) is required | Missing q parameter (Search endpoint) |
400 | place_id or data_cid is required | Neither identifier provided (Place endpoint) |
400 | data_id or place_id is required | Neither identifier provided (Reviews endpoint) |
400 | sort_by must be one of: newestFirst, ratingHigh, ratingLow | Invalid Reviews sort_by value |
400 | topic_id and query parameters can't be used together | Mutually exclusive Reviews filters both supplied |
400 | num must be an integer between 1 and 20 | Reviews num outside the accepted range |
400 | invalid ll parameter | Bad location format; expected @lat,lng,zoom |
400 | invalid start parameter | Start must be a non-negative multiple of 20 |
502 | no results | Google returned zero results for this query. Retry once before treating as final |
502 | request failed | Transient upstream failure. Safe to retry |
502 | failed to extract search data URL / failed to extract place data URL | Upstream shell did not contain the expected data URL. Retry |
502 | reviews request failed | Reviews endpoint: transient upstream failure. Retry |
502 | failed to extract data_id from place | Reviews endpoint: could not resolve place_id to a data_id. Retry or pass data_id directly |
500 | failed to parse search results / failed to parse place results / failed to parse reviews | Parser error on the Google response |
