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

**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](https://thelastapi.dev/blog/google-trustpilot-reviews-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:

```bash
vibiz run places.search --input '{"query":"pizzeria in Turin","maxPlaces":10}'
```

To run the same search from any language or script using `curl`:

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

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

```ts
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](https://thelastapi.dev/blog/scrape-website-to-markdown-api) 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](https://thelastapi.dev/docs/actions).

## 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 `maxPlaces` and `maxReviews`. If a run exceeds this bound, it stops and fails with `provider_unavailable` and `details.reason: "timeout"`. To prevent timeouts, keep `maxPlaces` around 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 with `vibiz 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](https://thelastapi.dev/blog/search-console-data-next-to-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.

---

Published 2026-11-15 · https://thelastapi.dev/blog/google-maps-businesses-api-leads
