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 /pricing and 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

FieldRequiredWhat it does
categoriesYesBusiness categories, like Dentist. Up to 500.
locationsYesCities, states or countries. Up to 2,000.
results_file_nameYesName for the order, the new list and its file, 1 to 120 characters.
per_searchNoThe most businesses to take from each search. Leave it out for as many as available. It doesn't change the price.
output_formatNocsv (the default) or xlsx.
noteNoA note kept with the order, up to 1,000 characters.
callback_urlNoA 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 the list_id of the new list.
  • status: new orders start as pending or queued.
  • credits_deducted and new_balance: credits are taken when the order is accepted.
  • status_url: the address to check progress.
  • callback_signing_secret: only when you sent a callback_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 (or xlsx) returns the whole list.
  • GET /lists/{list_id}/rows returns the list as JSON, 50 rows per page.
  • The download_url on 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.

Start Your Export

Still stuck?

Our team usually replies the same day.

Contact support
Start a Google Maps Scrape With the API