Find businesses on Google Maps with an API
Find Google Maps business data with the places.search API. Extract names, addresses, phone numbers, websites, ratings, and hours in structured JSON.
On this page 7 sections
You can find businesses on Google Maps and extract their structured data using the places.search API action. Pass a text query like "dentist in Turin" or precise coordinates using near to get verified business names, addresses, phone numbers, websites, star ratings, review counts, and opening hours. Every run answers synchronously over HTTP, through the CLI, or via code.
This guide walks through the parameters for searching Google Maps, the exact shape of the returned JSON, how to run queries from code or the terminal, and how pricing and limits work.
What business data does places.search return?
The places.search action queries Google Maps and parses the results into clean JSON. Instead of parsing messy web markup or managing browser sessions yourself, you send a search term and receive an array of normalized place records.
Each record inside the places array provides:
name: The legal or public name of the business.address: The full street address.phone: The public contact phone number.website: The external URL linked to the business profile.rating: The average star rating (for example,4.8).reviewsCount: The total number of published user reviews.openingHours: Operating schedules and open hours.
If you need user review text alongside the business listing, pass the optional maxReviews parameter (from 0 to 10) to pull recent customer reviews directly into each place record. For deeper sentiment audits across hundreds of customer comments, you can pair this with the dedicated reviews action; see our guide on how to collect Google Maps and Trustpilot reviews with an API.
How to search Google Maps from the CLI and curl
Every web data action in thelastapi can be run directly from your terminal using the vibiz CLI or via standard HTTP requests against https://thelastapi.dev/v1/actions/:name.
To search businesses from your command line:
vibiz run places.search --input '{"query":"pizzeria in Turin","maxPlaces":10}'To run the same search from any language or script using curl:
curl https://thelastapi.dev/v1/actions/places.search \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"query": "pizzeria in Turin",
"maxPlaces": 10,
"language": "it"
}
}'The endpoint responds synchronously with an action_result object:
{
"object": "action_result",
"action": "places.search",
"output": {
"places": [
{
"name": "Pizzeria Uno",
"address": "Via Roma 10, 10121 Torino TO, Italy",
"phone": "+39 011 5551234",
"website": "https://example.com",
"rating": 4.6,
"reviewsCount": 342,
"openingHours": "Mon-Sun 19:00 - 23:30"
}
]
},
"cost_micro_usd": 50000,
"run_id": "arun_01hgb789k12",
"console_url": "https://thelastapi.dev/web-data?action=places.search&run=arun_01hgb789k12"
}The response includes the raw cost of the run in cost_micro_usd, the unique run_id, and a console_url where you can inspect past outputs in your browser.
How to call places.search in an application or AI agent
Inside a Node.js or TypeScript application, use the @vibiz/app package. The SDK reads your environment credentials and exposes a typed runner:
import { vibiz } from '@vibiz/app';
async function findLocalServices(term: string) {
const result = await vibiz.actions.run('places.search', {
query: term,
maxPlaces: 5,
language: 'en',
});
for (const place of result.output.places) {
console.log(`${place.name} (${place.rating}★, ${place.reviewsCount} reviews)`);
console.log(`Phone: ${place.phone} | Web: ${place.website}`);
}
}
findLocalServices('mechanic in Austin');If you build with AI agents using the Model Context Protocol (MCP), your agent can call the vibiz_run_action tool directly with the action name set to places.search. The agent receives third-party text data to process without needing an external browser automation setup.
Once you have a business website URL from places.search, you can feed it into companion actions. For example, pass the URL into web.scrape to extract their services page into clean text; see scrape a website to markdown with one API call for that workflow.
Target parameters and location coordinates
You can tune your search using simple keyword strings, geographic bounding coordinates, or language codes.
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | required | Search query, such as "dentist in Austin" or "hotel near central station". |
near | object | optional | Coordinates object: {"latitude": 45.0703, "longitude": 7.6869}. |
maxPlaces | number | 5 | Number of business profiles to return (between 1 and 20). |
language | string | optional | Language tag for returned metadata and addresses (e.g., "en", "it"). |
maxReviews | number | 0 | Recent reviews per business to include directly in output (0 to 10). |
When you supply near, Google Maps centers its radius around those exact coordinates before evaluating the text query. This helps avoid ambiguity when queries span common street names or multiple suburbs with similar names.
For a full list of all available extraction tools, review the web data documentation.
Pricing, timeouts, and execution history
Each call to places.search computes live data from Maps. Keep these operational details in mind:
- Cost: Every result includes
cost_micro_usd. The account is billed that raw cost plus thelastapi's 30% web data margin, deducted from your prepaid balance. As a general guide, places data costs roughly half a cent ($0.005) per business returned. - Daily Spend Ceiling: Calls draw against your account's daily spend ceiling ($5 default across AI and web data, adjustable in your dashboard).
- Execution bounds: Fetching live business details across Maps can take between 60 and 150 seconds depending on
maxPlacesandmaxReviews. If a run exceeds this bound, it stops and fails withprovider_unavailableanddetails.reason: "timeout". To prevent timeouts, keepmaxPlacesaround 5 to 10 per request. - Run audit logs: Every call is recorded. Check past searches using
vibiz runs --action places.search, fetch an exact output again withvibiz runs <run_id>, or review history in the console sidebar under Web data.
Handling API errors
When a call fails, the response returns standard HTTP error codes with descriptive details:
| Status | Code | Cause | Resolution |
|---|---|---|---|
400 | invalid_request | Missing query or invalid parameter value. | Check details.field and adjust your payload. |
402 | payment_required | Account credits are exhausted. | Top up balance with vibiz billing top-up. |
429 | rate_limited | Hit the account daily spend ceiling. | Wait for midnight UTC or raise the limit in Billing. |
503 | provider_unavailable | Search timed out (reason: "timeout"). | Re-run with a lower maxPlaces value. |
Next step: run vibiz actions in your terminal to see parameter schemas for all actions, or explore our guide on Google Search Console data next to your analytics to manage your own domain visibility.
Frequently asked questions
How many businesses can I fetch in a single places.search request?
You can request between 1 and 20 businesses per call using the maxPlaces parameter, which defaults to 5.
Can places.search extract customer reviews along with business details?
Yes, set maxReviews between 1 and 10 to retrieve recent review text inline for each business, or use the dedicated reviews action for larger review exports.
How much does searching Google Maps cost?
Each returned place costs roughly half a cent ($0.005) before the platform's 30% web data margin, and the exact cost is returned in the cost_micro_usd response field.
What should I do if a search times out?
Searches that take longer than 60 to 150 seconds fail with a provider_unavailable error and details.reason set to "timeout"; resolve this by lowering your maxPlaces or maxReviews value.