Maps business leads API reference

One Maps search per search term in location; each business's own website (home plus contact/about pages) is harvested for emails and social profile links. Each lead carries the Maps row (name, category, phone, website, rating, address, coordinates, place id) plus email, its email_source page, all_emails with per-address status, and the social links found on the site.

email_status is an MX check only: valid = the domain has MX records and the address is not a generic role inbox; risky-role = MX records but a role inbox (info@, contact@, …); invalid = the domain answered and has no MX records. A lookup that failed or timed out is unverified, the same as verify_emails off. It never claims the mailbox itself exists. only_with_email (default) returns only businesses with an email; the counts (searched, with_website, with_email) always describe the whole search. A business whose site fails or publishes no email is data, not an error; an empty lead list is not billed. The whole call stops at its time budget; a harvest cut short is meta.partial and is not billed. A Maps block or a spent budget with nothing to return is 503 with Retry-After.

Request

POSThttps://api.scrapercompany.com/v1/maps/leads

Authenticate with your API key in the x-api-key header (see Authentication).

Run this request on your own API key from this page, with the values you type. Signed out? Sign in or get an API key.

Body

JSON object. Unknown fields are rejected with 422.

search_termsarray of stringrequiredmin items 1, max items 5
Business types to search (one Maps search each).
locationstringrequiredmin length 1, max length 120
City or area to search in.
max_resultsintegerdefault 10min 1, max 20
Places enriched per search term.
verify_emailsbooleandefault true
MX-check every harvested email domain (tags each address valid / risky-role / invalid). Off, or a DNS lookup that failed: unverified.
only_with_emailbooleandefault true
Return only businesses with at least one harvested email.
max_emails_per_siteintegerdefault 5min 1, max 20
Cap on addresses harvested per business site.

Example request

curl -X POST "https://api.scrapercompany.com/v1/maps/leads" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "Austin, TX",
    "max_results": 10,
    "search_terms": [
      "dentist"
    ]
  }'

Response

200 — Business leads with MX-checked emails. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response

{
  "search_parameters": {
    "engine": "maps_leads",
    "search_terms": [
      "dentist"
    ],
    "location": "Austin, TX"
  },
  "leads": [
    {
      "name": "Bright Smiles Dental",
      "category": "Dentist",
      "email": "[email protected]",
      "email_status": "valid",
      "email_source": "https://brightsmiles.example/contact",
      "all_emails": [
        {
          "email": "[email protected]",
          "status": "valid",
          "source": "https://brightsmiles.example/contact"
        },
        {
          "email": "[email protected]",
          "status": "risky-role",
          "source": "https://brightsmiles.example/"
        }
      ],
      "email_count": 2,
      "phone": "(512) 555-0142",
      "website": "https://brightsmiles.example/",
      "rating": 4.8,
      "address": "1200 S Congress Ave, Austin, TX 78704",
      "lat": 30.2461,
      "lng": -97.749,
      "place_id": "0x8644b599a60bc4cf:0x14d5e7f0a1b2c3d4",
      "maps_url": "https://www.google.com/maps/search/?api=1&query=Bright+Smiles+Dental&query_place_id=0x8644b599a60bc4cf:0x14d5e7f0a1b2c3d4",
      "search_term": "dentist",
      "facebook": "https://www.facebook.com/brightsmilesdental",
      "instagram": "https://www.instagram.com/brightsmilesdental"
    }
  ],
  "total": 1,
  "searched": 10,
  "with_website": 8,
  "with_email": 3,
  "scraped_at": "2026-11-06T12:00:00+00:00",
  "meta": {
    "source": "google_maps",
    "partial": false,
    "elapsed_s": 4.21
  }
}

Errors

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Status	Meaning	Retry?
`401`Unauthorized	Missing or invalid API key. `{"detail":"missing or invalid API key"}`	No, fix the request
`402`Payment Required	Not enough credits for this request: the account's credits mode is `enforce` (`mode` in `GET /v1/billing`) and the request costs more than the available credits. Nothing is run or charged. `{"detail":"insufficient credits: this request costs 5, 0 available. Credits renew 2026-11-01."}`	No, fix the request
`422`Unprocessable Content	Request validation failed. `detail` is a list of problems for schema errors, or a string for semantic checks performed by the endpoint. `{"detail":[{"loc":["body","name"],"msg":"Field required","type":"missing"}]}`	No, fix the request
`429`Too Many Requests	Too many requests: the key's requests-per-minute limit was exceeded, or (in `enforce` credits mode) the plan's concurrent-request limit. No rate-limit or Retry-After headers are sent; back off and retry. `{"detail":"rate limit 60/min exceeded"}`	Yes, with backoff
`503`Service Unavailable	Temporarily unavailable: a dependency of this endpoint is down, or the upstream source changed its contract. Retry later. `{"detail":"database unavailable: OperationalError"}`	Yes, with backoff

Try it

Press Try it above to run this request on your own key, with the values you type (sign in first). For a no-code walkthrough, use the workspace’s guided Try it.

Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? start a free trial).
Copy the cURL example above and run it in a terminal.

Credits

6 credits per successful call (6 (a partial or empty result and failed requests are free)). Failed, blocked and empty results are free.

Request#

Body#

Example request#

Response#

Errors#

Try it#