Start a Google Maps Scrape With the API
Send categories and locations to POST /google-maps-scraper, read the response, avoid double charges with an Idempotency-Key, then check status and download your list.
4 min read
You can start a Google Maps scrape with the API using one request. You send business categories and locations, we run every search on our servers, and the result becomes a new list in your account. This guide covers the request, every field, the response, safe retries, and how to get the file when it's done.
Before You Start
- An API key. Follow Get Your MapsDaddy API Key and test it with
GET /me. - Enough credits. The API spends the same balance as the dashboard. At the time of writing, the Google Maps Scraper costs a flat 10 credits per search, however many businesses come back.
GET /pricingand the pricing page always show the current numbers. - Your categories and locations. Every category in every location is one search.
In the example below we want plumbers and electricians in Manchester and Liverpool. That's 2 categories in 2 locations, so 4 searches and 40 credits.
How a Google Maps Scrape With the API Works
Send a POST to /google-maps-scraper on the base URL https://api.mapsdaddy.com/api/v1:
curl -X POST https://api.mapsdaddy.com/api/v1/google-maps-scraper \
-H "Authorization: Bearer $MAPSDADDY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: trades-north-west-001" \
-d '{
"categories": ["Plumber", "Electrician"],
"locations": ["Manchester, England, United Kingdom", "Liverpool, England, United Kingdom"],
"results_file_name": "Trades North West",
"callback_url": "https://example.com/webhooks/mapsdaddy"
}'
All four searches go into one list. Adding the region and country to each location helps when a town name exists in more than one place.
The Body Fields
| Field | Required | What it does |
|---|---|---|
categories | Yes | Business categories, like Dentist. Up to 500. |
locations | Yes | Cities, states or countries. Up to 2,000. |
results_file_name | Yes | Name for the order, the new list and its file, 1 to 120 characters. |
per_search | No | The most businesses to take from each search. Leave it out for as many as available. It doesn't change the price. |
output_format | No | csv (the default) or xlsx. |
note | No | A note kept with the order, up to 1,000 characters. |
callback_url | No | A public HTTPS address we notify when the order changes. See Get API Webhooks When Your List Is Ready. |
Read the Response
A 201 means the order was created. The response includes:
order_id: save it. Once the order is done, it's also thelist_idof the new list.status: new orders start aspendingorqueued.credits_deductedandnew_balance: credits are taken when the order is accepted.status_url: the address to check progress.callback_signing_secret: only when you sent acallback_url. It's shown once, so store it with the order ID.
Other status codes you may see: 400 (something in the body is wrong, and the message names the field), 401 (key missing or invalid), 402 (not enough credits), 403 (account suspended) and 429 (more than 60 requests in a minute).
Retry Safely With an Idempotency-Key
A request can time out on your side even though it reached us. If your script simply tries again, you could start a second order and pay twice. Add an Idempotency-Key header, 8 to 100 characters, unique for each order you mean to place. If the same key arrives again, you get the original order back instead of a new charge.
Tip: Build the key from something stable, like a campaign name plus a row ID, rather than a timestamp. A script that crashes and restarts will then reuse the same keys.
Check Status and Get the File
Call GET /orders/{order_id} to see where things are. queued means it's waiting its turn, processing means it's running, and completed means the list is ready. Most lists are ready in minutes. Checking every minute or so is plenty, or skip polling and use a webhook.
curl https://api.mapsdaddy.com/api/v1/orders/ORDER_ID \
-H "Authorization: Bearer $MAPSDADDY_API_KEY"
When the status is completed, you have a few ways to get the data:
GET /lists/{list_id}/download?format=csv(orxlsx) returns the whole list.GET /lists/{list_id}/rowsreturns the list as JSON, 50 rows per page.- The
download_urlon the order is a public link to the file as delivered. It works without your key.
The list also appears in Lists & Exports, and the file stays available for 180 days.
What It Costs
Each search is a flat price. If a search finds only a few businesses, there's no refund, so test one category in one location before you send hundreds. If an order is cancelled, its credits go back to your balance.
Where to Go Next
To add emails or decision makers, call POST /lists/{list_id}/enrichments, and send dry_run: true first to see the most it could cost, free. The API documentation lists every endpoint, and our Google Maps API page explains what the API covers.
Ready to try it?
Start your export with MapsDaddy. No browser extension, Google account or API key needed.
Related Guides
Still stuck?
Our team usually replies the same day.