thelastapi
Get started free

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:

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

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

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

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

ParameterTypeDefaultDescription
querystringrequiredSearch query, such as "dentist in Austin" or "hotel near central station".
nearobjectoptionalCoordinates object: {"latitude": 45.0703, "longitude": 7.6869}.
maxPlacesnumber5Number of business profiles to return (between 1 and 20).
languagestringoptionalLanguage tag for returned metadata and addresses (e.g., "en", "it").
maxReviewsnumber0Recent 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 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:

StatusCodeCauseResolution
400invalid_requestMissing query or invalid parameter value.Check details.field and adjust your payload.
402payment_requiredAccount credits are exhausted.Top up balance with vibiz billing top-up.
429rate_limitedHit the account daily spend ceiling.Wait for midnight UTC or raise the limit in Billing.
503provider_unavailableSearch 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.