Start a scrape in one call
Every request authenticates with a Bearer token in the Authorization header. Keys look like mh_live_… and are created from the Integrations tab in your dashboard.
curl -X POST https://api.mapsharvest.com/scrape \
-H "Authorization: Bearer mh_live_..." \
-H "Content-Type: application/json" \
-d '{
"query": "dentist",
"states": "Florida,Georgia",
"country": "us",
"max_total_results": 500,
"min_rating": 4.0,
"exclude_website": true
}'
# → {"job_id":"a7f3c2d1e8b94f56","status":"queued", ... }That one request searches every city in Florida and Georgia for dentists rated 4.0 or higher with no website, and stops at 500 leads: a ready list for selling web design.
Nine endpoints run the whole job
/scrapeStart a scrape. Pass a query, states and optional filters; receive a job_id immediately.
/jobs/{job_id}Poll status, progress, cities completed and rows collected.
/jobs/{job_id}/downloadDownload finished results. Add ?fmt=csv, ?fmt=xlsx or ?fmt=json.
/scrape/{job_id}/stopStop a running job early. Rows already collected stay downloadable.
/jobs/{job_id}/resumeContinue a stopped, failed or interrupted job. Cities it already finished are skipped and not charged again.
/jobsList your jobs with status and row counts.
/fieldsList every data field.
/citiesList the cities the scraper will loop through for given states.
/api-keysCreate a new API key. Returns the raw key once, so store it straight away.
Start, poll and download in Python
The whole job, from the first call to a CSV on disk:
import time, requests
API = "https://api.mapsharvest.com"
HDRS = {"Authorization": "Bearer mh_live_..."}
# 1. Start
job = requests.post(f"{API}/scrape", headers=HDRS, json={
"query": "roofing contractor",
"states": "Texas",
"max_results_per_city": 60,
"require_phone": True,
}).json()
# 2. Poll while the job is working
while True:
status = requests.get(f"{API}/jobs/{job['job_id']}", headers=HDRS).json()
if status["status"] not in ("queued", "running", "stopping"):
break # completed, stopped, failed or interrupted
time.sleep(5)
# 3. Download
r = requests.get(
f"{API}/jobs/{job['job_id']}/download",
headers=HDRS, params={"fmt": "csv"},
)
r.raise_for_status()
open("leads.csv", "wb").write(r.content)Prefer not to poll? Pass webhook_url with "webhook_trigger": "completed" on POST /scrape and the finished rows are posted to you when the job completes. It works with Zapier, Make and n8n, on every plan.
Filter before you spend credits
Filters run during the scrape. A business that fails a filter is never written and never billed, so you pay only for the leads you asked for instead of scraping broadly and cleaning up afterwards.
| Parameter | Type | Effect |
|---|---|---|
min_ | float | Only businesses rated at or above this. 4.0 filters to well-reviewed operators. |
min_ | int | Skip businesses with fewer reviews than this, a rough guide to how established they are. |
max_ | int | Skip businesses with more reviews than this. Useful for finding smaller, less-saturated targets. |
require_ | bool | Keep only businesses that have a website. |
exclude_ | bool | Keep only businesses with no website: the usual list for selling web design. |
require_ | bool | Keep only businesses with a phone number. Use it for dialer imports. |
exclude_ | bool | Keep only businesses without a listed phone number. |
One job at a time, on every plan
One credit equals one lead. Every plan runs one job at a time: start another once the current one finishes or is stopped.
| Plan | Credits/mo | API |
|---|---|---|
| Free | 50 (once) | Included, with webhooks, CSV, Excel and JSON |
| Starter | 1,000 to 15,000 | Included, with webhooks, CSV, Excel and JSON |
| Growth | 2,500 to 37,500 | Included, with webhooks, CSV, Excel and JSON |
| Scale | 5,000 to 75,000 | Included, with webhooks, CSV, Excel and JSON |
| Enterprise | More than 75,000 | Included, plus the local worker CLI (by application) |
Starting a second job while one is running returns 429; running out of credits returns 402. See full pricing.
Questions about the API
Is there a free Google Maps scraper API?+
Yes. Create an account and you get 50 credits free with no credit card, and the free plan can create an API key, so you can call the API with those credits right away. Paid plans add more credits. Webhooks, JSON downloads and all 23 fields come with every plan, Free included.
How is this different from running my own scraper?+
There is nothing to host or maintain. You send JSON describing the businesses you want and get back business records, and your account is never sent the same business twice. Running your own scraper means hosting it and repairing it every time Google Maps changes.
What data fields does the API return?+
Up to 23 fields per business, on every plan: name, category, phone, website, full address, city, state, latitude/longitude, Google rating, review count, opening hours, price level, Google Maps URL, Plus Code, temporarily closed status, review breakdown, last updated by owner, service options and more. Call GET /fields to see the full list.
Which countries are supported?+
Six: the United States, the United Kingdom, Canada, Australia, Germany and Egypt. Pass the country parameter on POST /scrape (us, uk, canada, australia, germany or egypt); it defaults to us.
Is scraping Google Maps legal?+
We can't promise that it is legal for you, and nothing here is legal advice. The API returns information that businesses publish on their public Google Maps listings. Whether a particular use of it is lawful depends on where you are and what you do with it: in many places, including the EU, the UK, Canada and Australia, details of sole traders and small businesses count as personal data even though they are public. You are responsible for how you use the results, including the GDPR and the rules for marketing calls and emails in your jurisdiction, as our Terms of Service explain.
How many results can one job return?+
As many as you set with max_total_results, up to the credits in your account. Google Maps shows up to about 120 businesses per search in one city; API calls default to 60 per city, and max_results_per_city asks for more.
Build on the Maps Harvest API
Start with 50 free credits and no credit card. Your API key works on the free plan.