Black Friday: 50% off paid plans, 25% more credits. Ends 30 November.See prices →
← Back to blog
GuideUpdated November 13, 2026·12 min read

Google Maps Scraper API

A Google Maps scraper API runs a Google Maps search from your own code and hands back the businesses as rows: name, phone, address, website, rating and review count. With the Maps Harvest REST API that is three calls against https://api.mapsharvest.com, authenticated with a Bearer key: start a scrape, poll it, download the file. There's no scraping code to write or maintain, and the API is on every plan, Free included.

An API saves you maintaining your own scraper

Rolling your own Google Maps scraper means building the collection code yourself and fixing it every time Google changes its markup.

A managed API does that part. You send a JSON request describing what you want and get back structured business data, with no business twice. It runs the same searches as the dashboard, from any language.

A scraper API is not Google's Maps API

Searches for "Google Maps API scraping" often mix up two different things. Google's own Maps Platform APIs, such as the Places API, are Google products with their own pricing and their own rules on what you may store. They suit apps that show a map or look up a place while a user waits.

A Google Maps scraper API is built for a different job: a lead list you keep. One request names a business type and a set of states, every city in them is searched, and the result is a file you can load into a CRM or a dialer. If you are choosing between the two, the limits, cost and terms are set side by side in Google Maps API vs scraping.

Four endpoints cover the whole workflow

Every request goes to https://api.mapsharvest.com and authenticates with a Bearer token (Authorization: Bearer mh_live_...). Requests and responses are JSON.

POST/scrape

Starts a job. Pass a query, states and optional filters, and get back a job_id straight away.

GET/jobs/{id}

Poll a job's status, cities done and remaining, and rows collected so far.

GET/jobs/{id}/download

Download the results as CSV, XLSX or JSON via ?fmt= (every plan gets all three).

POST/scrape/{id}/stop

Stop a running job early. Leads already collected stay available to download.

A complete example in three calls, curl and Python

Start a scrape, wait for it to finish, then download the CSV. The loop keeps checking only while the job is queued, running or stopping, so a job that ends early (stopped, failed, or interrupted by a server restart) never leaves your script waiting forever. If the API doesn't answer for a moment, the loop tries again for up to two minutes:

# 1. Start a scrape
JOB=$(curl -s -X POST https://api.mapsharvest.com/scrape \
  -H "Authorization: Bearer mh_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"dentist","states":"Florida","max_total_results":500}' \
  | jq -r .job_id)

# 2. Poll until the job ends
TRIES=0
while true; do
  STATUS=$(curl -s https://api.mapsharvest.com/jobs/$JOB \
    -H 'Authorization: Bearer mh_live_...' | jq -r .status 2>/dev/null)
  case "$STATUS" in
    queued|running|stopping) TRIES=0 ;;
    "") TRIES=$((TRIES + 1)); [ "$TRIES" -lt 8 ] || { echo "The API isn't answering"; exit 1; } ;;
    *) break ;;
  esac
  sleep 15
done

# 3. Download the results
curl -fsS "https://api.mapsharvest.com/jobs/$JOB/download?fmt=csv" \
  -H "Authorization: Bearer mh_live_..." -o leads.csv

The same three calls in Python, if that is where the rest of your pipeline lives:

import time, requests

API = "https://api.mapsharvest.com"
H = {"Authorization": "Bearer mh_live_..."}

# 1. Start a scrape
job = requests.post(f"{API}/scrape", headers=H, json={
    "query": "dentist",
    "states": "Florida",
    "max_total_results": 500,
}).json()["job_id"]

# 2. Poll until the job ends
while True:
    job_state = requests.get(f"{API}/jobs/{job}", headers=H).json()
    if job_state["status"] not in ("queued", "running", "stopping"):
        break
    time.sleep(15)

# 3. Download the results
rows = requests.get(f"{API}/jobs/{job}/download",
                    headers=H, params={"fmt": "csv"})
open("leads.csv", "wb").write(rows.content)

Both versions stop looping on any status that is not queued, running or stopping, rather than waiting for a success status that may never arrive. A job that was stopped, failed or interrupted still has the leads it collected, so the download call is worth making either way.

Every parameter and the full response schemas are in the API documentation.

The query field is a category, not a search phrase

The single parameter that decides whether a list is any good is query, and it behaves differently from the box on the Google Maps website. It takes a Google Business category: the label a business picks for itself when it sets up its listing. There are nearly 4,000 of them.

A broad category also matches its more specific versions. Send "restaurant" and you get Italian restaurants, sushi restaurants and tapas bars in the same job, each with its own category in the category column, so you can split them after download. Send "italian restaurant" and the Italian ones are all you get.

That shapes how to build a request. Ask for the broadest category that still describes who you sell to, then cut the list down with filters and with the category column, instead of running one job per narrow category and paying for the overlap. Two things make that safe: filters run during the search, so a listing that fails one is never saved or charged, and an account is never sent the same business twice across all of its searches, so overlapping areas do not bill twice for the same row.

A longer phrase is the common mistake. "Best plumber near me" is how a person searches; it is not a category, and it is not what the field expects. "plumber" with a minimum rating and a minimum review count gets you the same intent as a row of structured data you can sort.

Three requests for three real jobs

The body of POST /scrape is where a list gets good or bad. Filters run during the search, and only leads that pass are saved and charged, so a tight request is also a cheap one. Three examples:

A call list of established dentists in two states

Picture a sales rep who books demos for a dental software product and only wants practices that answer the phone and have a track record.

{
  "query": "dentist",
  "states": "Texas, Arizona",
  "min_rating": 4.0,
  "min_reviews": 20,
  "require_phone": true,
  "max_results_per_city": 120
}

Every city in both states is searched. Listings under 4.0 stars, under 20 reviews or without a phone are skipped before they are saved, so they never cost a credit.

Roofers with no website, for a web design pitch

Picture a small web studio that builds sites for trades and wants owners who have nothing online yet.

{
  "query": "roofing contractor",
  "states": "Ohio",
  "exclude_website": true,
  "require_phone": true,
  "max_total_results": 300
}

exclude_website keeps only businesses that show no website. max_total_results stops the job at exactly 300 leads, so the spend is known before it starts.

A small test before wiring anything up

Picture a developer on the Free plan who wants to see the real columns before building an import.

{
  "query": "coffee shop",
  "states": "Ontario",
  "country": "canada",
  "cities": "Toronto, Ottawa",
  "max_total_results": 25
}

cities narrows the search to a hand-picked list instead of every city in the province. 25 leads uses half of the Free plan's 50 credits and leaves room for a second try.

The filters available are minimum rating, minimum reviews, maximum reviews, has or has no website, and has or has no phone. There is no maximum-rating filter, so a list of poorly rated businesses has to be sorted after download.

What comes back: fields, formats and credits

Each lead is one row with the same 23 columns on every plan, Free included:

  • The listing: search query, name, category, phone, address, city, state, latitude, longitude, rating, review count, Google Maps URL and the time it was collected.
  • Web presence: website, website domain and plus code.
  • The detail: description, opening hours, price level, temporarily closed, the review breakdown by star, last updated by owner, and service options.

Every plan can download CSV, Excel or JSON, so set fmt to whichever your import expects.

Every call spends your account's own credits, 1 credit per lead. A job never collects more leads than you have credits; if it runs out it stops, and you can continue it later from the last finished city without paying for finished cities again. At monthly prices a lead costs 1.9 cents on Starter ($19 for 1,000 credits) and about 1 cent on Growth ($49 for 5,000).

Skip the polling loop with a webhook

Polling is the obvious way to use a job API and the one most examples show, including the two above. It is also the part that tends to go wrong in production: a process has to stay alive for the length of the job, a container restart loses the loop, and a job that ends in a way your code did not expect leaves a script waiting.

On every plan a search can send its leads to a webhook instead. You give the search a URL, and when it finishes the leads arrive at that URL on their own. Nothing of yours has to stay running, and there is no status to ask about: the arrival of the payload is the event.

The URL can be an endpoint in your own backend, or a catch hook in Zapier, Make or n8n if the next step is a spreadsheet, a CRM record or a Slack message rather than code. That makes a useful split for teams: the API starts the work from wherever it belongs, and the webhook hands the finished list to whatever already handles your data. If you would rather start from a flow that is already wired up, the n8n and Make templates call this same API.

Six things to check before you pick one

Most Google Maps scraper APIs look alike on a landing page. These are the details that change what you actually get:

How it charges

Per lead, per request or per hour of run time changes what a list really costs. Maps Harvest charges 1 credit per lead saved, whatever fields you get, and filtered-out listings cost nothing.

Which fields come back

Some APIs return a name and an address; a lead list needs phone, website, rating and review count. Check the full column list, not the headline.

Duplicates across runs

If you search overlapping areas every week, a business you already have should not be charged again. A Maps Harvest account is never sent the same business twice, across all its searches.

Stopping and continuing

Long jobs get interrupted. Look for a stop call that keeps what was collected, and a way to continue without paying for finished cities again.

How many jobs run at once

Maps Harvest runs one scrape at a time per account on every plan. If you need parallel jobs, that is a real difference to weigh.

Where results can go

A download link is enough for scripts. For no-code tools, check whether results can be pushed to Zapier, Make or n8n when a job finishes.

Four things you can build on it

Agencies automating client lead gen

Wire the API into your onboarding so a new client's lead list is built automatically as soon as their niche and territory are set, with no manual searching per account.

SaaS data enrichment

Call the API from your product to add business data (phone, website, rating) to records when you need it, instead of shipping an old database.

Recurring pipelines from your own backend

Trigger searches from your own cron job, drop the CSV into your warehouse or CRM, and add each run's new businesses without anyone clicking a button.

Internal tools & dashboards

Give your sales ops team a one-click 'pull leads' button that hits the API behind the scenes and returns a ready-to-dial list.

Prefer to start from a working flow? The n8n and Make templates call the same API, so they run on the Free plan's 50 credits.

Every plan includes an API key, Free too

API access is included on every plan, including Free, and each call uses your account's own credits. Generate a key from the Integrations tab in your dashboard, keep it secret, and pass it as a Bearer token on every request. Prefer no-code? On every plan, results can also be sent automatically to any webhook (Zapier, Make, n8n) when a search finishes, without writing a line of code.

Product
Google Maps Scraper API: every endpoint, filter and plan limit →

Questions about Google Maps scraper APIs

What is a Google Maps scraper API?

A web API that runs a Google Maps search for you and returns the businesses it finds as structured rows: name, category, phone, address, rating, review count and more. You send one request describing the search, then poll the job and download the file, instead of writing and maintaining collection code yourself.

Is a Google Maps scraper API the same as the Google Maps API?

No. Google's own Maps Platform APIs, such as the Places API, are Google's products with their own pricing and their own rules on storing results. A scraper API like Maps Harvest's is built for lead lists: one request covers a business type across whole states, and the result is a file you keep. The differences in limits, cost and terms are compared in our guide to the Google Maps API vs scraping.

Can I try the API for free?

Yes. The API is on every Maps Harvest plan, Free included. The Free plan gives 50 credits once, with no card, and 1 credit is 1 lead, so a small test request with max_total_results set to 50 or less shows you the real output before you pay for anything.

How many results does one city return?

Up to about 120 per search in one city, which is a Google Maps limit. API requests default to 60 per city; set max_results_per_city to ask for more. To cover a large area, search by state so every city in it is searched, and use max_total_results to cap the whole job.

Which countries does the API cover?

The US, UK, Canada, Australia, Germany and Egypt. Set the country field to us, uk, canada, australia, germany or egypt; it defaults to us.

Can I run several scrapes at the same time?

No. Every plan, Enterprise included, runs one scrape at a time. Queue jobs in your own code and start the next one once the current job is no longer queued, running or stopping.

Does the API return email addresses?

No. Search results have no email column on any plan. On every plan, the Campaigns step called Populate emails & socials reads each lead's own website for emails and social profile links.

How do I authenticate?

With a Bearer token. Every request goes to https://api.mapsharvest.com and carries an Authorization: Bearer header holding your API key, which you generate from the Integrations tab in your dashboard. There is no separate login call and no token to refresh.

What should I put in the query field?

A Google Business category. There are nearly 4,000 of them, and a broad one also matches its more specific versions, so "Restaurant" brings back Italian restaurants and sushi restaurants too. Pick the broadest category that still describes who you sell to, then narrow with filters rather than with a longer search phrase.

What happens if a job runs out of credits?

It stops. A search never collects more leads than the account has credits, so the job ends rather than overspending, and the leads already collected stay available to download. Move to a bigger credit amount or plan and you can continue the same job from the last finished city, without paying for the cities it already finished.

Can I get the results without polling?

Yes. On every plan a search can send its leads to a webhook automatically when it finishes, so your code receives the results instead of asking for them. Point it at Zapier, Make, n8n or any URL of your own.

Start a search from your own code, on any plan

Read the full API reference, or start with 50 free leads on the Free plan. No card needed.

Black Friday: 50% off every paid plan for as long as you stay subscribed, plus 25% more credits. Ends 30 November.