> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/documentation/guides/how-to-guides-for-google-maps/how-to-search-google-maps-places-by-keyword.md). # How to Search Google Maps Places by Keyword Searching Google Maps manually works for a few places, but it quickly becomes slow when you need structured business data for local SEO, market research, sales prospecting, or competitor analysis. If you want to search Google Maps places by keyword and use the results in your own dashboard, spreadsheet, or database, Pullbay gives you a simple API endpoint for programmatic place search. This guide shows how to use Pullbay’s Google Maps Place Search endpoint to search by free-text query, optionally bias results toward a country, language, or map viewport, and handle larger result sets with `maxItems` or `offset` pagination. ### The Challenge of Keyword-Based Google Maps Search Google Maps search is useful because people search in natural language: “pizza near soho new york”, “best dentist in berlin”, or “coffee shop kadikoy”. But when you are doing research at scale, copying listings manually is not practical. Pullbay’s Google Maps API lets you search places with a free-text query and returns structured fields such as place name, address, website, phone, rating, review count, categories, location, Google Maps URL, and FID. ### Endpoint ``` GET https://dashboard.pullbay.com/api/google-maps/place/search Authorization: Bearer YOUR_API_KEY ``` ### Required Parameter | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------- | | `query` | string | Yes | Free-text search term, 1–200 characters | ### Optional Parameters | Parameter | Type | Description | | -------------- | ------- | ------------------------------------------------- | | `countryCode` | string | Country or region bias, 2–5 characters | | `languageCode` | string | Language code for localized text, 2–10 characters | | `latitude` | string | Latitude to center the search viewport | | `longitude` | string | Longitude to center the search viewport | | `zoom` | string | Map zoom level to use with latitude and longitude | | `offset` | string | Offset-style pagination value | | `maxItems` | integer | One-shot bulk pull, 1–500 results | `offset` and `maxItems` are mutually exclusive. Use one or the other in a request. ### Approach 1: Simple Keyword Search with `maxItems` Use `maxItems` when you want a simple one-shot pull of places matching a keyword. ```python import requests API_KEY = "YOUR_API_KEY" BASE_URL = "https://dashboard.pullbay.com/api" headers = { "Authorization": f"Bearer {API_KEY}" } params = { "query": "pizza near soho new york", "countryCode": "us", "languageCode": "en", "maxItems": 20 } response = requests.get( f"{BASE_URL}/google-maps/place/search", headers=headers, params=params ) response.raise_for_status() data = response.json() places = data.get("data", []) credits = data.get("pricing", {}).get("creditsCharged") print(f"Fetched {len(places)} places") print(f"Credits charged: {credits}") for place in places: print(place.get("title")) print(place.get("address")) print(place.get("totalScore"), place.get("reviewsCount")) print(place.get("url")) print("---") ``` #### When to use this Use this approach when you need up to 500 results in a single request and do not need to process results page by page. ### Approach 2: Location-Biased Search with Latitude, Longitude, and Zoom If you want to bias search results toward a specific map viewport, pass latitude, longitude, and zoom. ```python import requests API_KEY = "YOUR_API_KEY" BASE_URL = "https://dashboard.pullbay.com/api" headers = { "Authorization": f"Bearer {API_KEY}" } params = { "query": "coffee shops", "countryCode": "us", "languageCode": "en", "latitude": "40.730610", "longitude": "-73.935242", "zoom": "13", "maxItems": 50 } response = requests.get( f"{BASE_URL}/google-maps/place/search", headers=headers, params=params ) response.raise_for_status() data = response.json() for place in data.get("data", []): print({ "title": place.get("title"), "address": place.get("address"), "rating": place.get("totalScore"), "reviews": place.get("reviewsCount"), "fid": place.get("fid"), "url": place.get("url") }) ``` #### When to use this Use viewport parameters when your keyword is broad and you want results biased toward a specific area. ### Approach 3: Offset Pagination Use `offset` when you want to process results in batches. The response includes `pagination.offset`. For this endpoint, increment the offset by the number of items received. ```python import requests API_KEY = "YOUR_API_KEY" BASE_URL = "https://dashboard.pullbay.com/api" headers = { "Authorization": f"Bearer {API_KEY}" } query = "restaurants in brooklyn" offset = 0 all_places = [] while True: params = { "query": query, "countryCode": "us", "languageCode": "en", "offset": str(offset) } response = requests.get( f"{BASE_URL}/google-maps/place/search", headers=headers, params=params ) response.raise_for_status() data = response.json() places = data.get("data", []) if not places: break all_places.extend(places) print(f"Fetched {len(places)} places at offset {offset}") offset += len(places) print(f"Total places fetched: {len(all_places)}") ``` #### When to use this Use offset pagination when you want to process results incrementally instead of requesting a larger one-shot result set. ### Useful Fields in the Search Response A place search result can include fields such as: | Field | Description | | ----------------------------- | ------------------------------------------ | | `title` | Place name | | `url` | Google Maps URL for the place | | `address` | Full formatted address | | `location.lat / location.lng` | Latitude and longitude | | `website` | Place website URL | | `phone` | Formatted phone number | | `totalScore` | Average rating | | `reviewsCount` | Total number of reviews | | `categories` | Place category labels | | `openingHours` | Opening hours per weekday | | `fid` | Feature ID used for the Get Place endpoint | | `placeId` | Google Place ID | ### Credit Considerations Each request returns the exact credit charge in: ``` data["pricing"]["creditsCharged"] ``` Credit cost is dynamic. Do not hardcode a flat cost per endpoint or per result. Always read the value from the response. ### Troubleshooting | Problem | Possible Cause | Fix | | --------------------------- | ----------------------------------------- | -------------------------------------------------------- | | 400 Bad request | Missing or invalid parameter | Check query, offset, maxItems, and geo parameter formats | | 402 Insufficient credits | Your account does not have enough credits | Check your Pullbay account credits | | 404 Not found | No matching place or review set found | Try a different query or location bias | | Empty result set | Query may be too narrow | Broaden the keyword or remove viewport parameters | | Invalid pagination behavior | offset and maxItems used together | Use only one pagination mode per request | ### Next Steps After you can search Google Maps places by keyword, you can: * Use each result’s `fid` to fetch full place details * Use each result’s `url` to fetch reviews * Store search results in a database for local SEO analysis * Compare competitors by rating, review count, category, and location --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pullbay.com/documentation/guides/how-to-guides-for-google-maps/how-to-search-google-maps-places-by-keyword.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.