API reference

Google Maps Scraper API

The MapsDaddy Google Maps scraper API does everything the dashboard does, from your own code: scrape Google Maps by category and location, export ready-made businesses from the Local Business Database, and enrich your lists with websites, emails, social links and decision makers. It's a simple JSON REST API that uses the same credits, prices and lists as your dashboard.

Base URLhttps://api.mapsdaddy.com/api/v1

How it works

  1. 1

    Find businesses

    Scrape Google Maps with categories and locations, or export from the Local Business Database with filters. Either way you get a list.

  2. 2

    Track it

    Poll the order or export, or get a webhook. Most scrapes finish in seconds, and big exports within a minute or two.

  3. 3

    Enrich it

    Run Enrich Contacts on the list to add websites, emails, social links or decision makers. A dry run shows the cost first.

  4. 4

    Use it

    Read the rows as JSON, or download the list as CSV or Excel with every enrichment result included.

Quickstart

Three requests take you from a fresh API key to a finished list. From there you can enrich it and download it with the Lists and Enrich Contacts endpoints.

1

Check your key and balance

Store your key in an environment variable, then call /me. A 200 response means you're connected.

GET /me
curl "https://api.mapsdaddy.com/api/v1/me" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
2

Scrape Google Maps

Send your business categories and locations to the Google Maps Scraper. Save the order_id from the response: once done, it's also your list_id.

POST /google-maps-scraper
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: scrape-2026-11-10-001" \
  -d '{
    "categories": [
      "Dentist",
      "Orthodontist"
    ],
    "locations": [
      "Austin, Texas, United States",
      "Cedar Park, Texas, United States"
    ],
    "results_file_name": "dentists-austin",
    "callback_url": "https://example.com/webhooks/mapsdaddy"
  }'
3

Check status and download

Poll the order until status is completed (usually seconds), then download the file from download_url. Or skip polling with a callback_url.

GET /orders/{order_id}
curl "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"

Authentication

Every request needs your API key in the Authorization header as a bearer token. Create, view or regenerate your key on the API Key page.

Your key can spend your credits. Keep it on your server, never in browser or mobile code, and regenerate it right away if it leaks. Regenerating instantly disables the old key.
Authorization: Bearer YOUR_API_KEY
Store your key
export MAPSDADDY_API_KEY="md_live_..."

Credits & pricing

Everything is priced in credits, the same as in your dashboard. Credits are pay as you go: buy a package or a custom amount whenever you need them, and they never expire. The Google Maps Scraper is a flat price per search. The Local Business Database charges each business once per account, so businesses you exported before are free. Enrichment holds credits when it starts and refunds every row with no result. See the Pricing page for packages.

ServiceEndpointCredits
Google Maps Scraper/google-maps-scraper10 per search
Local Business Database/business-database/exports0.5 per business
Find Contacts Email (Waterfall)/lists/{list_id}/enrichments5 per result found
personal_email/lists/{list_id}/enrichments10 per result found
Find Contact Phone Number (Waterfall)/lists/{list_id}/enrichments20 per result found
Verify Emails/lists/{list_id}/enrichments0.5 per row checked
Find Company Website/lists/{list_id}/enrichments2 per result found
Find Business Email/lists/{list_id}/enrichments5 per result found
Find Company Social Media/lists/{list_id}/enrichments3 per result found
Find Decision Makers/lists/{list_id}/enrichments20 per result found

Live values are always available from GET /pricing.

Errors

Errors use standard HTTP status codes and always return the same JSON shape, with a stable code you can branch on and a readable message.

Status codes

  • 400Invalid request: the message names the field
  • 401Missing, invalid or revoked API key
  • 402Not enough credits
  • 403Account suspended, or the Local Business Database is switched off
  • 404Order, list or export not found
  • 409File or list not ready yet
  • 410File expired, or an endpoint for a tool that's no longer offered
  • 429Rate limit exceeded
  • 500Something went wrong on our side
Error response
{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits for this order."
  }
}

Rate limits

Each API key can make 60 requests per minute. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get a 429; wait a few seconds and retry.

Polling an order? Once a minute is plenty, or use webhooks and skip polling entirely.

Idempotency

Network hiccups happen. Add an Idempotency-Key header (8–100 characters, unique per request) when you scrape, export or enrich. If you retry with the same key, you get the original order, export or run back instead of being charged twice.

Google Maps Scraper

Google Maps Scraper

POSThttps://api.mapsdaddy.com/api/v1/google-maps-scraper

Scrape Google Maps live: every business in each search, with name, website, address, phone number, category, rating, review count, opening hours and the Google Maps link. Send business categories and locations (every category in every location is one search), or one search URL. The result is a new list you can read, enrich and download.

Body parameters

  • categoriesstring[]optional

    Business categories, for example Dentist. Up to 500. Send with locations, instead of search_url.

  • locationsstring[]optional

    Places to search, for example Austin, Texas, United States. Up to 2,000. Send with categories, instead of search_url.

  • search_urlstringoptional

    A Google Maps search URL (https://www.google.com/maps/search/dentists+in+austin+tx/@30.2672,-97.7431,12z), instead of categories and locations. maps.app.goo.gl share links work too.

  • per_searchnumberoptional

    The most businesses to take from each search. Leave it out for as many as Google shows (up to about 200 a search).

  • deep_searchbooleanoptional

    true: a deep search. After the normal results, MapsDaddy sweeps the area in smaller map views to get more than the ~120 businesses one Google Maps search shows, where more exist. Priced per deep search (credits_per_deep_search in GET /pricing) instead of per search.

  • results_file_namestringrequired

    Name for the order, the new list and its file (1–120 characters).

  • notestringoptional

    Optional note kept with the order (max 1,000 characters).

  • callback_urlstringoptional

    Public HTTPS URL notified when the order moves to processing, delivered or cancelled.

  • output_formatstringoptional

    File format of the delivery. Defaults to csv.

    csvxlsx

Headers

  • Authorizationstringrequired

    Bearer YOUR_API_KEY

  • Content-Typestringrequired

    application/json

  • Idempotency-Keystringoptional

    Makes retries safe: sending the same key again returns the original result instead of charging twice.

Returns

  • messagestring

    Human-readable confirmation for the accepted order.

  • order_idstring

    Unique order ID. Once it's done, it's also the list_id of the new list.

  • order_numbernumber

    Short order number shown in your dashboard.

  • servicestring

    Always people for the Google Maps Scraper.

  • statusstring

    Current status. New orders start as pending or queued.

    pendingqueuedprocessingcompletedcancelled
  • requested_countnumber

    Always 0 on the Google Maps Scraper, which has a flat price and no quantity.

  • credits_deductednumber

    Credits deducted from your balance for this order.

  • new_balancenumber

    Your credit balance after the deduction.

  • status_urlstring

    Authenticated endpoint to poll for status and result details.

  • download_urlstring | null

    Public link to the result file once the order is completed (no API key needed, valid until the file expires); null until then.

  • callback_urlstring | null

    Webhook URL accepted for this order, or null when none was supplied.

  • callback_signing_secretstring | null

    Returned once when callback_url is supplied. Store it to verify webhook signatures.

Status codes

  • 201Order created
  • 400Invalid request
  • 401API key missing or invalid
  • 402Insufficient credits
  • 403Account suspended
  • 429Rate limit exceeded

Good to know

  • Send either search_url, or both categories and locations, not both.
  • Costs a flat 10 credits per search. Searches are categories × locations, and a search_url is one search. This example is 2 × 2 = 4 searches.
  • Credits are deducted when the order is accepted. The price is the same however many businesses come back. If the order is cancelled, its credits are refunded.
  • Orders start straight away and run one after another with other customers' orders. A single search usually finishes in under 10 seconds, and 100,000 businesses in about a minute or two.
  • Poll status_url (or use callback_url). Once completed, the order_id is also the list_id: read it with Get List Rows, or add emails and decision makers with Enrich a List.
POST /google-maps-scraper
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: scrape-2026-11-10-001" \
  -d '{
    "categories": [
      "Dentist",
      "Orthodontist"
    ],
    "locations": [
      "Austin, Texas, United States",
      "Cedar Park, Texas, United States"
    ],
    "results_file_name": "dentists-austin",
    "callback_url": "https://example.com/webhooks/mapsdaddy"
  }'
Response · 201
{
  "message": "Order created successfully",
  "order_id": "ord_8f2c41d9a7b34e01",
  "order_number": 1042,
  "service": "people",
  "status": "queued",
  "requested_count": 0,
  "credits_deducted": 40,
  "new_balance": 12360,
  "status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
  "download_url": null,
  "callback_url": "https://example.com/webhooks/mapsdaddy",
  "callback_signing_secret": "whsec_3b9f0c2e7d41a8b6c5e0f19d2a7c4b81e6f3d905"
}

Local Business Database

Price an Export

POSThttps://api.mapsdaddy.com/api/v1/business-database/quote

What exporting these businesses would cost, before anything is charged. Businesses your account exported before are free and counted in already_paid.

Body parameters

  • filtersobjectoptional

    Which businesses. Every filter is optional: leave one out to match everything. Send {} for the whole database.

  • filters.searchstringoptional

    Text in the business name or website.

  • filters.categoriesstring[]optional

    Business types, like Dentist or Plumber. Any of them matches, and part of a word works (dent finds Dentist and Dental clinic).

  • filters.locationsstring[]optional

    Cities, states or countries, like Austin, Texas or Canada. Any of them matches.

  • filters.zip_codesstring[]optional

    ZIP or postal codes.

  • filters.has_websitebooleanoptional

    true: only businesses with a website. false: only without one.

  • filters.has_phonebooleanoptional

    true: only businesses with a phone number. false: only without one.

  • filters.has_opening_hoursbooleanoptional

    true: only businesses that list opening hours.

  • filters.min_ratingnumberoptional

    Lowest Google rating, 0 to 5.

  • filters.min_reviewsnumberoptional

    Fewest Google reviews.

  • filters.max_reviewsnumberoptional

    Most Google reviews.

  • filters.open_onstring[]optional

    Days the business must be open.

    MonTueWedThuFriSatSun
  • filters.open_24_hoursbooleanoptional

    true: only businesses open 24 hours.

  • filters.include_listsstring[]optional

    Only businesses in these lists, by list_id or File ID (Exp_12).

  • filters.exclude_listsstring[]optional

    Leave out businesses in these lists, for example ones you already exported.

  • filters.sortstringoptional

    Order of the results. todays_picks (the default) is a shuffled order that changes every day.

    todays_picksrating_descrating_ascreviews_descreviews_ascname_ascname_desc
  • limitnumberoptional

    Only the first N matches. Up to 100,000 per export.

Headers

  • Authorizationstringrequired

    Bearer YOUR_API_KEY

  • Content-Typestringrequired

    application/json

Returns

  • businessesnumber

    How many the export would have.

  • already_paidnumber

    Of those, how many your account exported before (free).

  • new_businessesnumber

    How many are charged.

  • creditsnumber

    What the export would cost: new_businesses × credits_per_business, rounded up.

  • credits_per_businessnumber

    Price per business.

  • balancenumber

    Your credit balance now.

  • max_per_exportnumber

    The most businesses one export can have.

Status codes

  • 200Success
  • 400Invalid filter or limit
  • 403Local Business Database switched off
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Send the same filters and limit to Export Businesses to get exactly this selection.
POST /business-database/quote
curl -X POST "https://api.mapsdaddy.com/api/v1/business-database/quote" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "categories": [
        "Dentist"
      ],
      "locations": [
        "Austin, Texas, United States"
      ],
      "has_website": true,
      "min_rating": 4.5
    },
    "limit": 1000
  }'
Response · 200
{
  "businesses": 1000,
  "already_paid": 120,
  "new_businesses": 880,
  "credits": 440,
  "credits_per_business": 0.5,
  "balance": 12400,
  "max_per_export": 100000
}

Local Business Database

Export Businesses

POSThttps://api.mapsdaddy.com/api/v1/business-database/exports

Export the businesses matching the filters as a new list, with full websites and every column. Each business is charged once per account: ones you exported before are free. The file is built in the background.

Body parameters

  • filtersobjectoptional

    Which businesses. Every filter is optional: leave one out to match everything. Send {} for the whole database.

  • filters.searchstringoptional

    Text in the business name or website.

  • filters.categoriesstring[]optional

    Business types, like Dentist or Plumber. Any of them matches, and part of a word works (dent finds Dentist and Dental clinic).

  • filters.locationsstring[]optional

    Cities, states or countries, like Austin, Texas or Canada. Any of them matches.

  • filters.zip_codesstring[]optional

    ZIP or postal codes.

  • filters.has_websitebooleanoptional

    true: only businesses with a website. false: only without one.

  • filters.has_phonebooleanoptional

    true: only businesses with a phone number. false: only without one.

  • filters.has_opening_hoursbooleanoptional

    true: only businesses that list opening hours.

  • filters.min_ratingnumberoptional

    Lowest Google rating, 0 to 5.

  • filters.min_reviewsnumberoptional

    Fewest Google reviews.

  • filters.max_reviewsnumberoptional

    Most Google reviews.

  • filters.open_onstring[]optional

    Days the business must be open.

    MonTueWedThuFriSatSun
  • filters.open_24_hoursbooleanoptional

    true: only businesses open 24 hours.

  • filters.include_listsstring[]optional

    Only businesses in these lists, by list_id or File ID (Exp_12).

  • filters.exclude_listsstring[]optional

    Leave out businesses in these lists, for example ones you already exported.

  • filters.sortstringoptional

    Order of the results. todays_picks (the default) is a shuffled order that changes every day.

    todays_picksrating_descrating_ascreviews_descreviews_ascname_ascname_desc
  • limitnumberoptional

    Only the first N matches. Up to 100,000 per export.

  • results_file_namestringrequired

    Name for the new list and its file (1–120 characters).

  • output_formatstringoptional

    File format. Defaults to csv.

    csvxlsx

Headers

  • Authorizationstringrequired

    Bearer YOUR_API_KEY

  • Content-Typestringrequired

    application/json

  • Idempotency-Keystringoptional

    Makes retries safe: sending the same key again returns the original result instead of charging twice.

Returns

  • export_idnumber

    Check progress with Get an Export.

  • statusstring

    processing while the file is built (100,000 businesses take about a minute).

    processingreadyfailed
  • businessesnumber

    Businesses in the export.

  • credits_deductednumber

    Credits charged (only for businesses your account hadn't paid for).

  • list_id / file_idstring | null

    The new list, once ready.

  • download_urlstring | null

    Public link to the file, once ready.

  • status_urlstring

    Get an Export for this export.

  • new_balancenumber

    Your balance after the charge.

Status codes

  • 201Export started
  • 200Same Idempotency-Key: the original export
  • 400Invalid request, or no businesses match
  • 402Insufficient credits
  • 403Local Business Database switched off
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Costs 0.5 credits per business you haven't exported before. Use Price an Export first to see the exact cost.
  • Credits are charged when the export starts. Send an Idempotency-Key so a retry returns the same export instead of charging again.
  • The new list works like a scraped one: read its rows, enrich it and download it from the Lists endpoints.
POST /business-database/exports
curl -X POST "https://api.mapsdaddy.com/api/v1/business-database/exports" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: export-2026-11-10-001" \
  -d '{
    "filters": {
      "categories": [
        "Dentist"
      ],
      "locations": [
        "Austin, Texas, United States"
      ],
      "has_website": true,
      "min_rating": 4.5
    },
    "limit": 1000,
    "results_file_name": "Austin dentists"
  }'
Response · 201
{
  "export_id": 318,
  "results_file_name": "Austin dentists",
  "output_format": "csv",
  "businesses": 1000,
  "credits_deducted": 440,
  "status_url": "https://api.mapsdaddy.com/api/v1/business-database/exports/318",
  "error": null,
  "created_at": "2026-11-10T10:02:17.000Z",
  "status": "processing",
  "list_id": null,
  "file_id": null,
  "download_url": null,
  "finished_at": null,
  "new_balance": 11960
}

Local Business Database

Get an Export

GEThttps://api.mapsdaddy.com/api/v1/business-database/exports/{export_id}

An export's progress. Once status is ready, list_id is the new list and download_url links to the file.

Path parameters

  • export_idnumberrequired

    The export_id from Export Businesses.

Status codes

  • 200Success
  • 404Export not found
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Same fields as Export Businesses. Checking every few seconds is fine: most exports are ready within a minute.
GET /business-database/exports/{export_id}
curl "https://api.mapsdaddy.com/api/v1/business-database/exports/318" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "export_id": 318,
  "results_file_name": "Austin dentists",
  "output_format": "csv",
  "businesses": 1000,
  "credits_deducted": 440,
  "status_url": "https://api.mapsdaddy.com/api/v1/business-database/exports/318",
  "error": null,
  "created_at": "2026-11-10T10:02:17.000Z",
  "status": "ready",
  "list_id": "ord_c41d9a7b34e01f8a",
  "file_id": "Exp_14",
  "download_url": "https://api.mapsdaddy.com/api/orders/ord_c41d9a7b34e01f8a/download?file=0&t=Qm4pXw2Ks9",
  "finished_at": "2026-11-10T10:02:21.000Z"
}

Lists

List Lists

GEThttps://api.mapsdaddy.com/api/v1/lists

Your lists, newest first: every Google Maps scrape and Local Business Database export, with the File ID you see in Lists & Exports.

Query parameters

  • statusstringoptional

    Only lists with this status.

    pendingqueuedprocessingcompletedcancelled
  • limitnumberoptional

    Page size, 1–100. Defaults to 20.

  • offsetnumberoptional

    How many to skip. Defaults to 0.

Returns

  • data[].list_idstring

    Use it with the other Lists and Enrich Contacts endpoints. The File ID (Exp_14) works too.

  • data[].file_idstring

    The File ID shown in Lists & Exports.

  • data[].sourcestring

    Where the list came from.

    google_maps_scraperbusiness_database
  • data[].businessesnumber | null

    Businesses in the list, once completed.

  • data[].searchesnumber | null

    Searches in a scrape.

  • data[].rows_url / download_url / enrichments_urlstring

    Links to read, download and enrich the list.

  • data[].expires_atstring | null

    When the file stops being kept.

  • total / has_morenumber / boolean

    For paging with limit and offset.

Status codes

  • 200Success
  • 400Invalid status, limit or offset
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Enrichment runs aren't separate lists: their results are added to the list they ran on.
GET /lists
curl "https://api.mapsdaddy.com/api/v1/lists?limit=20" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "data": [
    {
      "list_id": "ord_c41d9a7b34e01f8a",
      "file_id": "Exp_14",
      "name": "Austin dentists",
      "source": "business_database",
      "status": "completed",
      "businesses": 1000,
      "searches": null,
      "created_at": "2026-11-10T09:24:11.000Z",
      "rows_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/rows",
      "download_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/download",
      "enrichments_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/enrichments",
      "expires_at": "2027-05-09T09:24:52.000Z"
    },
    {
      "list_id": "ord_8f2c41d9a7b34e01",
      "file_id": "Exp_13",
      "name": "dentists-austin",
      "source": "google_maps_scraper",
      "status": "completed",
      "businesses": 684,
      "searches": 4,
      "created_at": "2026-11-10T09:24:11.000Z",
      "rows_url": "https://api.mapsdaddy.com/api/v1/lists/ord_8f2c41d9a7b34e01/rows",
      "download_url": "https://api.mapsdaddy.com/api/v1/lists/ord_8f2c41d9a7b34e01/download",
      "enrichments_url": "https://api.mapsdaddy.com/api/v1/lists/ord_8f2c41d9a7b34e01/enrichments",
      "expires_at": "2027-05-09T09:24:52.000Z"
    }
  ],
  "total": 14,
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Lists

Get a List

GEThttps://api.mapsdaddy.com/api/v1/lists/{list_id}

One list, by its list_id or File ID.

Path parameters

  • list_idstringrequired

    The list_id (ord_...) or File ID (Exp_14).

Status codes

  • 200Success
  • 404List not found
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Same fields as one item of List Lists.
GET /lists/{list_id}
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "list_id": "ord_c41d9a7b34e01f8a",
  "file_id": "Exp_14",
  "name": "Austin dentists",
  "source": "business_database",
  "status": "completed",
  "businesses": 1000,
  "searches": null,
  "created_at": "2026-11-10T09:24:11.000Z",
  "rows_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/rows",
  "download_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/download",
  "enrichments_url": "https://api.mapsdaddy.com/api/v1/lists/ord_c41d9a7b34e01f8a/enrichments",
  "expires_at": "2027-05-09T09:24:52.000Z"
}

Lists

Get List Rows

GEThttps://api.mapsdaddy.com/api/v1/lists/{list_id}/rows

One page of a finished list as JSON: 50 rows, each an object keyed by column name, with any enrichment results added as columns.

Query parameters

  • list_idstringrequired

    In the path: the list_id or File ID.

  • pagenumberoptional

    Page number, from 1. Defaults to 1.

Returns

  • columnsstring[]

    Column names in order. A repeated name gets (2), (3).

  • rowsobject[]

    Up to 50 rows, each keyed by column name. Values are text.

  • total / has_morenumber / boolean

    Rows in the list, and whether there's another page.

Status codes

  • 200Success
  • 404List not found
  • 409List not ready yet
  • 410File expired
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • For the whole list at once, use Download a List.
GET /lists/{list_id}/rows
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14/rows?page=1" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "list_id": "ord_c41d9a7b34e01f8a",
  "page": 1,
  "page_size": 50,
  "total": 1000,
  "has_more": true,
  "columns": [
    "Business ID",
    "Business Name",
    "Website",
    "Phone Number",
    "Category",
    "Rating",
    "Rating Count",
    "Address",
    "Business Email"
  ],
  "rows": [
    {
      "Business ID": "MDfb5ngckc9",
      "Business Name": "Lone Star Smiles",
      "Website": "https://lonestarsmiles.example.com/",
      "Phone Number": "+1 512-555-0142",
      "Category": "Dentist",
      "Rating": "4.8",
      "Rating Count": "312",
      "Address": "1200 S Lamar Blvd, Austin, TX 78704, United States",
      "Business Email": "hello@lonestarsmiles.example.com"
    }
  ]
}

Lists

Download a List

GEThttps://api.mapsdaddy.com/api/v1/lists/{list_id}/download

The whole list as CSV or Excel, with every enrichment result added as columns.

Query parameters

  • list_idstringrequired

    In the path: the list_id or File ID.

  • formatstringoptional

    Defaults to csv.

    csvxlsx

Status codes

  • 200The file
  • 404List not found
  • 409List not ready yet
  • 410File expired
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Unlike download_url on an order (the file as delivered), this includes enrichment results.
  • Files are kept for six months after delivery.
GET /lists/{list_id}/download
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14/download?format=csv" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY" \
  -L -o "austin-dentists.csv"
Response · 200
Business ID,Business Name,Website,Phone Number,Category,Rating,Rating Count,Business Email
MDfb5ngckc9,Lone Star Smiles,https://lonestarsmiles.example.com/,+1 512-555-0142,Dentist,4.8,312,hello@lonestarsmiles.example.com
MD2k8d0qz7a,Barton Creek Dental,https://bartoncreekdental.example.com/,+1 512-555-0187,Dentist,4.6,198,

Enrich Contacts

List Enrichment Services

GEThttps://api.mapsdaddy.com/api/v1/enrichments

The Enrich Contacts services: what each costs, the list columns it reads and the columns it adds.

Parameters

No parameters. Just send the Authorization header.

Returns

  • services[].servicestring

    The key to send to Enrich a List.

    website_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier
  • services[].credits_per_resultnumber

    Credits per result found (or per row checked, for Verify Emails).

  • services[].charged_forstring

    What you pay for.

    results_foundrows_checked
  • services[].columnsarray

    The list columns the service reads. They're matched to your list automatically.

  • services[].adds_columnsstring[]

    The columns it adds to your list.

  • services[].optionsobject

    Find Decision Makers only: its settings.

Status codes

  • 200Success
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • The response lists every service that's switched on (this example shows two).
GET /enrichments
curl "https://api.mapsdaddy.com/api/v1/enrichments" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "services": [
    {
      "service": "biz_email_finder",
      "name": "Find Business Email",
      "description": "Find public business emails from a website",
      "credits_per_result": 5,
      "charged_for": "results_found",
      "columns": [
        {
          "key": "company_domain",
          "label": "Website / Domain",
          "required": true
        }
      ],
      "adds_columns": [
        "Email"
      ],
      "enabled": true
    },
    {
      "service": "contact_enrichment",
      "name": "Find Decision Makers",
      "description": "Find decision makers and their contact details",
      "credits_per_result": 20,
      "charged_for": "results_found",
      "columns": [
        {
          "key": "company_domain",
          "label": "Company Domain",
          "required": true
        }
      ],
      "adds_columns": [
        "Full Name",
        "First Name",
        "Last Name",
        "Job Title",
        "LinkedIn URL",
        "Email"
      ],
      "enabled": true,
      "options": {
        "job_titles": "Optional. Job titles to look for, up to 100 (for example Owner, CEO, Marketing Manager).",
        "countries": "Optional. Where the people are based, up to 100 countries.",
        "max_people_per_company": "Optional. 1 to 50, default 5. Each person found is one result."
      }
    }
  ]
}

Enrich Contacts

Enrich a List

POSThttps://api.mapsdaddy.com/api/v1/lists/{list_id}/enrichments

Run an Enrich Contacts service on a finished list: websites, business emails, social links, decision makers and more. Send dry_run first to see how many rows would run and the most it could cost, without charging anything.

Body parameters

  • list_idstringrequired

    In the path: the list_id or File ID.

  • servicestringrequired

    Which service. See List Enrichment Services.

    website_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier
  • dry_runbooleanoptional

    true: only return the rows that would run and the most it could cost. Nothing is charged.

  • limitnumberoptional

    Run only the first N rows that can run.

  • columnsobjectoptional

    Optional. Which list column each input reads, like {"company_domain": "Website"}. Leave it out to match them automatically.

  • options.job_titlesstring[]optional

    Find Decision Makers: job titles to look for.

  • options.countriesstring[]optional

    Find Decision Makers: where the people are based.

  • options.max_people_per_companynumberoptional

    Find Decision Makers: 1 to 50, default 5.

Headers

  • Authorizationstringrequired

    Bearer YOUR_API_KEY

  • Content-Typestringrequired

    application/json

  • Idempotency-Keystringoptional

    Makes retries safe: sending the same key again returns the original result instead of charging twice.

Returns

  • enrichment_idstring

    The new column set on the list. See List a List's Enrichments.

  • run.run_idstring

    The run, an order: check it with Get Order Status.

  • run.rowsnumber

    Rows sent to the service.

  • run.creditsobject

    held is set aside now; rows with no result are refunded when the run finishes.

  • dry run: rows, most_creditsnumber

    With dry_run: how many rows would run, and the most it could cost.

Status codes

  • 201Enrichment started
  • 200Dry run, or the same Idempotency-Key again
  • 400Unknown service, a column the list doesn't have, or no rows to run
  • 402Insufficient credits
  • 404List not found
  • 409List not ready yet
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Example: Find Business Email costs 5 credits per email found. A dry run returns { "rows": 500, "most_credits": 2,500, ... } and charges nothing.
  • Rows already enriched by the same service aren't run again, so you never pay twice for a row.
  • Credits are held when the run starts; anything not found goes back to your balance. Send an Idempotency-Key so a retry can't start a second run.
  • Results appear in Get List Rows and Download a List as the run finishes.
POST /lists/{list_id}/enrichments
curl -X POST "https://api.mapsdaddy.com/api/v1/lists/Exp_14/enrichments" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: enrich-2026-11-10-001" \
  -d '{
    "service": "biz_email_finder",
    "limit": 500
  }'
Response · 201
{
  "enrichment_id": "col_5d7a1e93c2b84f60",
  "run": {
    "run_id": "ord_e01f8a2c41d9a7b3",
    "service": "biz_email_finder",
    "status": "pending",
    "rows": 500,
    "credits": {
      "deducted": 2500,
      "held": 2500,
      "refunded": 0,
      "charged": 0
    },
    "status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_e01f8a2c41d9a7b3"
  },
  "new_balance": 9900
}

Enrich Contacts

List a List's Enrichments

GEThttps://api.mapsdaddy.com/api/v1/lists/{list_id}/enrichments

The enrichments added to a list, with progress and each run's credits.

Path parameters

  • list_idstringrequired

    The list_id or File ID.

Returns

  • data[].progressobject | null

    done and total rows.

  • data[].runs[].creditsobject

    charged is the final cost; refunded went back for rows with no result.

Status codes

  • 200Success
  • 404List not found
  • 401API key missing or invalid
  • 429Rate limit exceeded
GET /lists/{list_id}/enrichments
curl "https://api.mapsdaddy.com/api/v1/lists/Exp_14/enrichments" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "list_id": "ord_c41d9a7b34e01f8a",
  "data": [
    {
      "enrichment_id": "col_5d7a1e93c2b84f60",
      "service": "biz_email_finder",
      "columns": {
        "company_domain": "Website"
      },
      "options": null,
      "progress": {
        "done": 500,
        "total": 500,
        "stoppable": false
      },
      "runs": [
        {
          "run_id": "ord_e01f8a2c41d9a7b3",
          "status": "completed",
          "rows": 500,
          "credits": {
            "deducted": 2500,
            "held": 0,
            "refunded": 900,
            "charged": 1600
          },
          "status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_e01f8a2c41d9a7b3"
        }
      ],
      "created_at": "2026-11-10T10:05:02.000Z"
    }
  ]
}

Orders

Get Order Status

GEThttps://api.mapsdaddy.com/api/v1/orders/{order_id}

One order's status, credits and result details: a Google Maps scrape, or an enrichment run. Poll it until status is completed.

Path parameters

  • order_idstringrequired

    The order_id of a scrape, or the run_id of an enrichment.

Returns

  • order_idstring

    Unique order ID.

  • order_numbernumber

    Short order number shown in your dashboard.

  • servicestring

    people for a Google Maps scrape, or the enrichment's key for an enrichment run.

    peoplewebsite_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier
  • statusstring

    Current status.

    pendingqueuedprocessingcompletedcancelled
  • search_urlstring | null

    Google Maps URL submitted with the order, if you sent one.

  • categoriesstring[] | null

    Business categories submitted with a Google Maps Scraper order.

  • locationsstring[] | null

    Locations submitted with a Google Maps Scraper order.

  • placesstring[]

    Older orders only. Always empty now.

  • per_searchnumber | null

    The most businesses to take from each search, if you set a limit.

  • deep_searchboolean

    true when the order was a deep search (the area swept for more than Google's ~120 results).

  • output_formatstring

    File format of the delivery.

    csvxlsx
  • input_fileobject | null

    Enrichment runs: the rows sent to the service (name, rows, size_bytes). null on scrapes.

  • results_file_namestring

    Name given to the order and its file.

  • requested_countnumber

    Rows sent for an enrichment run. 0 on the Google Maps Scraper, which has a flat price.

  • delivered_countnumber

    Results delivered (0 until completed).

  • verify_emailsboolean

    Older orders only. Always false now.

  • notestring | null

    Notes sent with the order.

  • creditsobject

    deducted (taken from your balance when you order), held (set aside until the order finishes), refunded (returned for rows with no result, or if the order is cancelled) and charged (final cost, 0 until the order finishes).

  • status_urlstring

    This endpoint.

  • download_urlstring | null

    Public download link for the first file. It works without an API key. null while processing, after cancellation or once the file expired.

  • fileobject | null

    name, rows and size_bytes of the first delivered file.

  • filesarray

    Every delivered file: name, size_bytes and download_url.

  • callback_urlstring | null

    Webhook URL attached to the order.

  • cancel_reasonstring | null

    Why the order was cancelled, when it was.

  • created_atstring

    ISO 8601 timestamp of order creation.

  • delivered_atstring | null

    ISO 8601 timestamp of delivery.

  • expires_atstring | null

    When the delivered file stops being downloadable.

  • delivery_expiredboolean

    true once expires_at has passed.

Status codes

  • 200Success
  • 404Order not found
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • You can only read your own account's orders; anything else returns 404.
  • queued means it's waiting its turn; processing means it's running.
  • Polling every 10 seconds is fine, or use callback_url to be notified instead.
GET /orders/{order_id}
curl "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "order_id": "ord_8f2c41d9a7b34e01",
  "order_number": 1042,
  "service": "people",
  "status": "completed",
  "search_url": null,
  "categories": [
    "Dentist",
    "Orthodontist"
  ],
  "locations": [
    "Austin, Texas, United States",
    "Cedar Park, Texas, United States"
  ],
  "places": [],
  "per_search": null,
  "output_format": "csv",
  "input_file": null,
  "results_file_name": "dentists-austin",
  "requested_count": 0,
  "delivered_count": 684,
  "verify_emails": false,
  "note": null,
  "credits": {
    "deducted": 40,
    "held": 0,
    "refunded": 0,
    "charged": 40
  },
  "status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
  "download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW",
  "file": {
    "name": "dentists-austin.csv",
    "rows": 684,
    "size_bytes": 264024
  },
  "files": [
    {
      "name": "dentists-austin.csv",
      "size_bytes": 264024,
      "download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW"
    }
  ],
  "callback_url": "https://example.com/webhooks/mapsdaddy",
  "cancel_reason": null,
  "created_at": "2026-11-10T09:24:11.000Z",
  "delivered_at": "2026-11-10T09:24:52.000Z",
  "expires_at": "2027-05-09T09:24:52.000Z",
  "delivery_expired": false
}

Orders

Download Result File

GEThttps://api.mapsdaddy.com/api/v1/orders/{order_id}/download

Download the file an order delivered, as it was delivered. To get a list with its enrichment results, use Download a List instead.

Path parameters

  • order_idstringrequired

    ID of a completed order.

Status codes

  • 200The file
  • 404Order not found
  • 409File not ready yet
  • 410File expired
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Add ?file=1 for the second file when an order has several. The first is ?file=0, the default.
  • Returns 409 until the order is completed and 410 after the file expires (six months after delivery).
GET /orders/{order_id}/download
curl "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01/download" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY" \
  -L -o "dentists-austin.csv"
Response · 200
search_business_type,search_business_locations,Business Name,Website,Address,Phone Number,Category,Rating,Rating Count
Dentist,"Austin, Texas, United States",Lone Star Smiles,https://lonestarsmiles.example.com/,"1200 S Lamar Blvd, Austin, TX 78704",+1 512-555-0142,Dentist,4.8,312

Orders

List Orders

GEThttps://api.mapsdaddy.com/api/v1/orders

Every order, newest first: scrapes, Local Business Database lists and enrichment runs. For just your lists, use List Lists.

Query parameters

  • statusstringoptional

    Only orders with this status.

    pendingqueuedprocessingcompletedcancelled
  • limitnumberoptional

    Page size, 1–100. Defaults to 20.

  • offsetnumberoptional

    How many to skip. Defaults to 0.

Returns

  • dataarray

    Orders in the same shape as Get Order Status.

  • total / has_morenumber / boolean

    For paging with limit and offset.

Status codes

  • 200Success
  • 400Invalid status filter
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Combine limit and offset to page through results; stop when has_more is false.
GET /orders
curl "https://api.mapsdaddy.com/api/v1/orders?status=completed&limit=20" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "data": [
    {
      "order_id": "ord_8f2c41d9a7b34e01",
      "order_number": 1042,
      "service": "people",
      "status": "completed",
      "search_url": null,
      "categories": [
        "Dentist",
        "Orthodontist"
      ],
      "locations": [
        "Austin, Texas, United States",
        "Cedar Park, Texas, United States"
      ],
      "places": [],
      "per_search": null,
      "output_format": "csv",
      "input_file": null,
      "results_file_name": "dentists-austin",
      "requested_count": 0,
      "delivered_count": 684,
      "verify_emails": false,
      "note": null,
      "credits": {
        "deducted": 40,
        "held": 0,
        "refunded": 0,
        "charged": 40
      },
      "status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
      "download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW",
      "file": {
        "name": "dentists-austin.csv",
        "rows": 684,
        "size_bytes": 264024
      },
      "files": [
        {
          "name": "dentists-austin.csv",
          "size_bytes": 264024,
          "download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW"
        }
      ],
      "callback_url": "https://example.com/webhooks/mapsdaddy",
      "cancel_reason": null,
      "created_at": "2026-11-10T09:24:11.000Z",
      "delivered_at": "2026-11-10T09:24:52.000Z",
      "expires_at": "2027-05-09T09:24:52.000Z",
      "delivery_expired": false
    }
  ],
  "total": 37,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

Account

Get Account & Balance

GEThttps://api.mapsdaddy.com/api/v1/me

The account that owns the API key and its credit balance. Handy as a connection test.

Parameters

No parameters. Just send the Authorization header.

Returns

  • id / name / emailstring

    The account.

  • credits.availablenumber

    Credits available to spend.

Status codes

  • 200Success
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Check credits.available before big orders to avoid 402 responses.
GET /me
curl "https://api.mapsdaddy.com/api/v1/me" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "id": "usr_4b1d9e2a",
  "name": "Alex Morgan",
  "email": "alex@example.com",
  "credits": {
    "available": 12400
  }
}

Account

Get Pricing

GEThttps://api.mapsdaddy.com/api/v1/pricing

Live credit costs for every service, the price of credits and the credit packages, so you can work out a cost before spending.

Parameters

No parameters. Just send the Authorization header.

Returns

  • usd_per_1000_creditsnumber

    Base price in USD of 1,000 credits, for custom amounts. Packages include bonus credits.

  • packagesarray

    Credit packages: name, credits, bonus_credits and price_usd.

  • services[].servicestring

    Service key.

    google_maps_scraperbusiness_databasewebsite_finderbiz_email_findersocial_findercontact_enrichmentemail_finderphone_finderemail_verifier
  • services[].credits_per_searchnumber

    Google Maps Scraper: credits per search.

  • services[].credits_per_deep_searchnumber

    Google Maps Scraper: credits per deep search (deep_search: true).

  • services[].credits_per_businessnumber

    Local Business Database: credits per business exported (once per account).

  • services[].credits_per_resultnumber

    Enrich Contacts: credits per result found, or per row checked.

  • services[].enabledboolean

    false when a service is switched off for now.

Status codes

  • 200Success
  • 401API key missing or invalid
  • 429Rate limit exceeded

Good to know

  • Google Maps Scraper credits = credits_per_search × searches (categories × locations), or credits_per_deep_search × searches for a deep search.
  • Local Business Database credits = credits_per_business × businesses you haven't exported before. Price an Export gives the exact number.
  • Enrichment credits = credits_per_result × results found. A dry run gives the most it could cost.
GET /pricing
curl "https://api.mapsdaddy.com/api/v1/pricing" \
  -H "Authorization: Bearer $MAPSDADDY_API_KEY"
Response · 200
{
  "usd_per_1000_credits": 3,
  "packages": [
    {
      "name": "Starter",
      "credits": 5000,
      "bonus_credits": 0,
      "price_usd": 15
    },
    {
      "name": "Growth",
      "credits": 10000,
      "bonus_credits": 1000,
      "price_usd": 30
    },
    {
      "name": "Pro",
      "credits": 25000,
      "bonus_credits": 5000,
      "price_usd": 75
    },
    {
      "name": "Scale",
      "credits": 50000,
      "bonus_credits": 12500,
      "price_usd": 150
    },
    {
      "name": "Business",
      "credits": 75000,
      "bonus_credits": 20000,
      "price_usd": 225
    },
    {
      "name": "Enterprise",
      "credits": 100000,
      "bonus_credits": 30000,
      "price_usd": 300
    }
  ],
  "services": [
    {
      "service": "google_maps_scraper",
      "endpoint": "/google-maps-scraper",
      "credits_per_search": 10,
      "credits_per_deep_search": 30,
      "enabled": true
    },
    {
      "service": "business_database",
      "endpoint": "/business-database/exports",
      "credits_per_business": 0.5,
      "max_per_export": 100000,
      "enabled": true
    },
    {
      "service": "email_finder",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 5,
      "charged_for": "results_found",
      "enabled": true
    },
    {
      "service": "personal_email",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 10,
      "charged_for": "results_found",
      "enabled": true
    },
    {
      "service": "phone_finder",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 20,
      "charged_for": "results_found",
      "enabled": true
    },
    {
      "service": "email_verifier",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 0.5,
      "charged_for": "rows_checked",
      "enabled": true
    },
    {
      "service": "website_finder",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 2,
      "charged_for": "results_found",
      "enabled": true
    },
    {
      "service": "biz_email_finder",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 5,
      "charged_for": "results_found",
      "enabled": true
    },
    {
      "service": "social_finder",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 3,
      "charged_for": "results_found",
      "enabled": true
    },
    {
      "service": "contact_enrichment",
      "endpoint": "/lists/{list_id}/enrichments",
      "credits_per_result": 20,
      "charged_for": "results_found",
      "enabled": true
    }
  ]
}

Webhook events

Pass a public HTTPS callback_url when you create a Google Maps Scraper order and we'll POST a JSON event to it whenever the order changes. Reply with any 2xx within 10 seconds. For Local Business Database exports and enrichment runs, check their status_url instead.

Events

  • order.processingevent

    The scrape started.

  • order.deliveredevent

    The file is ready. download_url is included.

  • order.cancelledevent

    The order was cancelled and its credits refunded.

Headers

  • X-MapsDaddy-Eventstring

    The event name.

  • X-MapsDaddy-Signaturestring

    sha256= followed by the HMAC-SHA256 of the raw body, keyed with your callback_signing_secret.

Failed deliveries are retried up to 5 times with exponential backoff (30s, 2m, 8m, 32m).

order.delivered payload
{
  "id": "whd_7c2e9a41f0b84d16a3c5",
  "event": "order.delivered",
  "created_at": "2026-11-10T09:24:52.000Z",
  "data": {
    "order_id": "ord_8f2c41d9a7b34e01",
    "order_number": 1042,
    "service": "people",
    "status": "completed",
    "delivered_count": 684,
    "credits": {
      "deducted": 40,
      "held": 0,
      "refunded": 0,
      "charged": 40
    },
    "status_url": "https://api.mapsdaddy.com/api/v1/orders/ord_8f2c41d9a7b34e01",
    "download_url": "https://api.mapsdaddy.com/api/orders/ord_8f2c41d9a7b34e01/download?file=0&t=8kq2XvR1mW",
    "cancel_reason": null
  }
}

Verify signatures

Every webhook is signed so you can be sure it came from us. Compute the HMAC-SHA256 of the raw request body with the callback_signing_secret you received when creating the order, and compare it to X-MapsDaddy-Signature using a constant-time check.

The signing secret is shown only once, in the create-order response. Store it alongside the order ID.
Node.js
import crypto from "node:crypto";

// Use the raw request body exactly as received (before JSON parsing).
export function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}