--- title: "Google Maps Business Data API: Search Places as JSON" description: "One GET to simple-search returns places as JSON: name, rating, review_count, address, phone and business_id. Parameters, a real response, 1 credit per call." url: https://perceptlayer.com/blog/google-maps-business-data-api --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # Google Maps Business Data API: Search Places as JSON 18 Aug 2026 Perceptlayer 8 min read To get Google Maps business data as JSON, call `GET /v1/google-maps/simple-search` with a `query` such as `restaurants in new york`. You get back an `items` array where each place carries its name, rating, review count, address, phone numbers, coordinates and a `business_id`. One successful call costs 1 credit, and a failed call costs nothing. ## Key takeaways - `simple-search` has one required parameter, `query`, and returns each place with fields like `name`, `rating`, `review_count`, `full_address`, `phone_numbers` and `business_id`. - Pass a place's `business_id` to `business-details`, `photos` or `reviews` to go from a search hit to the full record. - The Google Maps API has 10 endpoints and every one costs 1 credit per successful call. - 10,000 search calls × 1 credit = 10,000 credits, which is the size of the Starter pack; [pricing](https://perceptlayer.com/pricing) shows what credits cost. - Every account gets 1,000 free credits a month after email verification, with no credit card. ## How do you search Google Maps places as JSON? Send a GET request to `/v1/google-maps/simple-search` with your key in the `X-API-Key` header and a `query` parameter. The query is free text, the same words you'd type into the Maps search box. The response is JSON with a top-level `items` array, one object per place. Here is the call we recorded: ```bash curl "https://api.perceptlayer.com/v1/google-maps/simple-search?query=restaurants+in+new+york" \ -H "X-API-Key: $API_KEY" ``` Keys start with `sk_live_`. If you don't have one yet, [get a free API key](https://perceptlayer.com/signup); the [quick start](https://docs.perceptlayer.com/quickstart) covers the first call, and [authentication](https://docs.perceptlayer.com/authentication) covers the header and the `api_key` query parameter for places where you can't set headers. The same request in Python: ```python import os import requests resp = requests.get( "https://api.perceptlayer.com/v1/google-maps/simple-search", params={"query": "restaurants in new york"}, headers={"X-API-Key": os.environ["API_KEY"]}, timeout=30, ) resp.raise_for_status() for place in resp.json()["items"]: print(place["name"], place["business_id"], place.get("rating"), place.get("review_count")) print("credits used:", resp.headers["X-Credits-Used"]) print("credits left:", resp.headers["X-Credits-Remaining"]) ``` The two credit headers come back on every successful response, so you can track spend without a separate call. You can also run the same request without writing code in the playground on the [Google Maps API page](https://perceptlayer.com/apis/google-maps). ## Which parameters does the search endpoint take? `simple-search` takes one required parameter, `query`, and six optional ones: `hl`, `gl`, `google_domain`, `limit`, `page` and `fields`. The table below lists all of them with the types from the endpoint's documentation. Nothing else is documented about them, so we don't state defaults or page sizes here. The response's `pagination` block, covered below, tells you where you are in the results; check `limit` in the playground on your query. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `query` | string | yes | What to search for, for example `restaurants in new york` | | `hl` | string | no | | | `gl` | string | no | | | `google_domain` | string | no | Up to 100 characters | | `limit` | integer | no | | | `page` | integer | no | | | `fields` | string | no | | Put the location in the query itself. The recorded call used `restaurants in new york`, and the first two results both came back with `district` set to Manhattan. If you need to search around specific coordinates, the [Advanced Search endpoint](https://perceptlayer.com/apis/google-maps/advanced-search) takes `lat`, `lon` and a required `zoom` alongside `query`. ### Which endpoint should you start with? Start with `simple-search` when you have a text query and want a list of businesses. Use `advanced-search` when your starting point is a map position rather than words. Use [Autocomplete](https://perceptlayer.com/apis/google-maps/autocomplete) when you're building a search box and want suggestions as someone types. All three cost 1 credit per call. ## What does a Google Maps search response look like? Each object in `items` is one business, and the recorded sample carries identity, location, contact and reputation fields in a flat structure. This is a trimmed excerpt of the real response from the call above, with `…` marking what we cut: ```json { "items": [ { "name": "Altair Restaurant NYC", "review_count": 1225, "rating": 4.8, "website": "https://www.altairnyc.com/", "domain": "altairnyc.com", "latitude": 40.7556565, "longitude": -73.9936282, "business_id": "0x89c2591598891521:0x4ebcde18610e64", "subtypes": [ "New American restaurant", "Restaurant" ], "district": "Manhattan", "full_address": "351 W 38th St, New York, NY 10018, United States", "timezone": "America/New_York", … "phone_numbers": [ "+1 929-561-6131" ], "place_id": "ChIJIRWJmBVZwokRZA5hGN68TgA=", … "city": "New York", "zip_code": "10018", "state": "New York", "country_code": "US", … }, … ] } ``` The fields group like this: | Group | Fields in the recorded response | | --- | --- | | Identity | `name`, `business_id`, `place_id`, `google_mid`, `subtypes` | | Reputation | `rating`, `review_count` | | Location | `latitude`, `longitude`, `full_address`, `street_address_full`, `city`, `state`, `zip_code`, `country_code`, `district`, `neighborhood`, `timezone` | | Contact | `website`, `domain`, `phone_numbers`, `order_link` | | Owner | `owner_id`, `owner_name`, `owner_link` | | Media and attributes | `photos_sample` (with `photo_id`, `photo_url`, `photo_url_large`), `attributes` | The second result in the same recording, Lulla NYC, has the same shape: an Italian restaurant with 1,571 reviews and a 4.8 rating. Both items carry `photos_sample` and an `attributes` object (in the recording, an `accessibility` group of wheelchair-access flags). Still, treat anything outside `name` and `business_id` as optional in your parser. ### How does pagination work? After `items`, the recorded response ends with a `pagination` object: ```json "pagination": { "current_page": 0, "total_results": 173, "has_more": false } ``` The recording shows `current_page` as 0, `total_results` as 173 and `has_more` as `false`. We haven't documented what each field means, so confirm them in the playground before you rely on them. For a business-list collector, a page loop that stops when `has_more` is `false` is the natural design, but cap the loop so a bug can't spend credits unchecked. Each page is one call, so it's 1 credit. We haven't documented what `limit` caps or the default page size, so check both in the playground. The recording includes `owner_id`, `owner_name` and a link in `owner_link`, so handle them as personal data. Only collect and store them if you have a lawful basis, and don't use them to contact the people behind a listing. ## How do you go from a search hit to full details? Take the `business_id` from a search result and pass it to the endpoint that answers your next question. A search gives you the summary; the other endpoints take one business and go deeper. `business_id` is required by Business Details, Photos, Reviews and Review, so it's the key you carry between calls. ```bash curl "https://api.perceptlayer.com/v1/google-maps/business-details?business_id=0x89c2591598891521:0x4ebcde18610e64" \ -H "X-API-Key: $API_KEY" ``` That's a real endpoint and a real `business_id` from the recorded search. We haven't recorded a `business-details` response, so check its fields in the playground rather than assuming them. A common pipeline looks like this: run a handful of searches, dedupe on `business_id`, then call details only for the places that pass your filter, for example `rating` above a threshold or a particular entry in `subtypes`. Filtering on search fields first keeps the second stage small, and every call you skip is a credit you keep. If reviews are what you're after, the `reviews` endpoint takes the same `business_id`; its parameters are listed on the [Google Maps API page](https://perceptlayer.com/apis/google-maps), and [Google Maps Reviews API: Parameters, Requests and Cost](https://perceptlayer.com/blog/google-maps-reviews-api-parameters) covers it in full. ## What are the other nine Google Maps endpoints? The Google Maps API has 10 endpoints, all `GET`, all 1 credit per successful call. Besides `simple-search`, they cover advanced search, autocomplete, business details, photos, posts, reviews, a single review, a contributor's reviews and directions. The table has the required parameters for each. | Endpoint | Returns | Required parameters | | --- | --- | --- | | `/v1/google-maps/simple-search` | Simple Search | `query` | | [`/v1/google-maps/advanced-search`](https://perceptlayer.com/apis/google-maps/advanced-search) | Advanced Search | `query`, `zoom` | | [`/v1/google-maps/autocomplete`](https://perceptlayer.com/apis/google-maps/autocomplete) | Autocomplete | none | | [`/v1/google-maps/business-details`](https://perceptlayer.com/apis/google-maps/business-details) | Business Details | `business_id` | | [`/v1/google-maps/photos`](https://perceptlayer.com/apis/google-maps/photos) | Photos | `business_id` | | [`/v1/google-maps/posts`](https://perceptlayer.com/apis/google-maps/posts) | Posts | `data_id` | | `/v1/google-maps/reviews` | Reviews | `business_id` | | [`/v1/google-maps/review`](https://perceptlayer.com/apis/google-maps/review) | Review | `review_id`, `business_id` | | [`/v1/google-maps/contributor-reviews`](https://perceptlayer.com/apis/google-maps/contributor-reviews) | Contributor Reviews | `contributor_id` | | [`/v1/google-maps/directions`](https://perceptlayer.com/apis/google-maps/directions) | Directions | `origin`, `destination` | Directions also takes an optional `mode` with the values `driving`, `walking`, `bicycling` or `transit`. Photos takes optional `page` and `limit`. Posts is keyed by `data_id` rather than `business_id`, and pages with `next_page_token`. Autocomplete has no required parameter; it accepts `query` or `q`, each up to 255 characters. ## How much does a Google Maps data call cost? Every Google Maps endpoint costs 1 credit per successful call, so the cost of a run is simply the number of calls. A failed call costs nothing and returns `X-Credits-Used: 0`. The free tier gives you 1,000 credits every month after you verify an email address, with no credit card. | Pack | Credits | | --- | --- | | Free | 1,000 a month | | Starter | 10,000 | | Build | 50,000 | | Growth | 200,000 | | Pro | 500,000 | | Scale | 1,000,000 | | Volume | 5,000,000 | Purchased credits last 12 months, and there's no subscription and no seats. The service is prepaid, so when the balance hits zero calls return `insufficient_credits` (402) and nothing more is debited. There's no automatic top-up. [Pricing](https://perceptlayer.com/pricing) shows what each pack costs. A worked example: 200 searches plus a `business-details` call for each of 1,000 places is 1,200 calls × 1 credit = 1,200 credits. That's 200 over a month's free credits. A bigger run of 10,000 calls × 1 credit = 10,000 credits, which is exactly the Starter pack. See [how credits work](https://docs.perceptlayer.com/credits) for the full rules. ## What happens when a call fails? A failed call returns an HTTP status and a JSON body with `error.code`, `error.message` and `error.request_id`, and it costs 0 credits. For a search workflow, the codes you'll meet most are `invalid_parameters` (422) when a required parameter is missing or invalid, `rate_limited` (429) when you're sending too fast, and `source_error` (502) or `temporarily_unavailable` (503) when the source side fails. Retry 429, 502 and 503. For 429 and 503, wait the number of seconds in the `Retry-After` header rather than guessing a backoff. Don't retry 422 or 401 without changing the request. A response that returns an error isn't billed, but requests have no idempotency key: if the reply is lost, for example when the 30-second client timeout in the Python example fires, the call may have succeeded and been billed. A retry then spends a second credit, so cap your retries. The [errors reference](https://docs.perceptlayer.com/errors) lists every code, and [rate limits](https://docs.perceptlayer.com/rate-limits) explains 429. ## When is Google's own Places API the better choice? If you're building an app on Google's own platform, look at Google's official [Places API](https://developers.google.com/maps/documentation/places/web-service/overview) and check its [billing and pricing](https://developers.google.com/maps/billing-and-pricing/pricing) for your volume. Read Google's terms for your use case before you choose. This API fits when you want flat JSON, one key across many sources and a fixed 1 credit per call. [Google Places API Alternative: Place Data Priced per Call](https://perceptlayer.com/blog/google-maps-places-api-alternative) compares the two approaches in more detail. Data here is collected from publicly available sources and returned as found at the time of the call. We don't promise completeness or freshness beyond that, so if you depend on a field, check it in the playground first. Agents can reach the same endpoints through the [MCP server](https://docs.perceptlayer.com/ai-agents), where `search_endpoints` and `get_endpoint` are free lookups and `call_endpoint` spends credits only on success. Next step: open the [Google Maps API page](https://perceptlayer.com/apis/google-maps), pick `simple-search` in the playground and run your own query. If you're comparing how other listing sources look as JSON, the [Zillow listings guide](https://perceptlayer.com/blog/zillow-listings-api-json) and the [API guides category](https://perceptlayer.com/blog/category/api-guides) follow the same format. ## APIs in this post - [Google Maps **1 credit per call** · 10 endpoints](https://perceptlayer.com/apis/google-maps) ## Frequently asked questions ### What does a Google Maps search return for each business? Each item in `items` carries `name`, `rating`, `review_count`, `full_address`, `latitude`, `longitude`, `phone_numbers`, `website`, `subtypes` and a `business_id`, plus address parts such as `city`, `state`, `zip_code` and `country_code`. Both recorded items also have `photos_sample` and `attributes`, and the response ends with a `pagination` object ( `current_page`, `total_results`, `has_more`). Treat fields beyond the name and ID as optional. ### How many credits does one Google Maps call use? One. All 10 Google Maps endpoints cost 1 credit per successful call, and failed calls cost nothing. The response carries `X-Credits-Used` and `X-Credits-Remaining`, so you can log what each call cost and what's left. A run of 1,000 calls is 1,000 credits; see [pricing](https://perceptlayer.com/pricing) for what credits cost. ### How do I get reviews or photos for a place I found? Copy the `business_id` from the search result and pass it to `/v1/google-maps/photos` or `/v1/google-maps/reviews`. Both take `business_id` as their only required parameter. Photos accepts optional `page` and `limit`, and reviews accepts `page`, `pages`, `search`, `sort`, `limit`, `hl` and `gl`. Each call is 1 credit. ### Can I try it before paying? Yes. Verify an email address and you get 1,000 free credits every month, with no credit card. That's 1,000 `simple-search` calls at 1 credit each. The playground on each API page runs real calls with your key, so you can see a response for your own query before you write any code. google maps places local business search business data ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 7 Aug 2026 Updated 26 Oct 2026 Perceptlayer 6 min read ## [Yelp Reviews API: Business Search and Reviews as JSON](https://perceptlayer.com/blog/yelp-reviews-api-json) Three Yelp endpoints return search results, business details and reviews as JSON, 1 credit per call. Parameters, a real response and a cost example. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 9 Jul 2026 Perceptlayer 8 min read ## [Google Maps Reviews API: Parameters, Requests and Cost](https://perceptlayer.com/blog/google-maps-reviews-api-parameters) Call GET /v1/google-maps/reviews with a business\_id from Simple Search. Every parameter, the sort values 1 to 4, and the cost: 1 credit per call. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 14 Oct 2026 Perceptlayer 7 min read ## [Google News API: Search News Articles as JSON](https://perceptlayer.com/blog/google-news-api) One GET call to /v1/google-news/news returns articles with title, link, source and ISO date as JSON for 1 credit. Parameters, a real response, cost.