Blog / API guides

Google Maps Business Data API: Search Places as JSON

18 Aug 2026Perceptlayer8 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.

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:

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; the quick start covers the first call, and authentication covers the header and the api_key query parameter for places where you can't set headers.

The same request in 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.

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.

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 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 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:

{
  "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:

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:

"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.

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, and Google Maps Reviews API: Parameters, Requests and Cost 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.

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.

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 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 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 lists every code, and 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 and check its billing and 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 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, 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, 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 and the API guides category follow the same format.

google mapsplaceslocal businesssearchbusiness data