How to get Google Maps leads through an API.

What do you need before the first call?

An account, credits and one key.

1. 1

   A Leadity account

   The account is free and needs no card. Every new account gets 300 free credits.

2. 2

   An API key

   Create it on the API screen of the Connectors page, with the read and spend scopes. It starts with lk_api_.

3. 3

   Python and requests

   Any recent Python with the requests library. Keep the key in an environment variable, never in the code.

How do you price an order?

With estimate_scrape, which takes no credits.

An order names its niches, its area and its filters. A niche is one Google Maps category: roofing_contractor is Roofing Contractor. The area names its country and region by code, and the filters are the web app's.

The estimate answers leadRateMilli, the exact price of one lead in thousandths of a credit. Any number of leads costs ceil(leads x leadRateMilli / 1000) credits, so the script works the price out before it buys anything.

How do you place the order safely?

A ceiling and a key of your own.

create_scrape takes credits, so it needs two things a read does not. The maxCredits ceiling is the most the order may cost: if the price is above it, nothing is charged. The Idempotency-Key header is a key you keep for this one order: if the connection drops, the same request with the same key answers the same scrape and charges nothing again.

The answer comes back at once with the scrape's id. The scrape then runs on Leadity's side for minutes to hours, searching Google Maps live.

The whole script

Price, order, wait, download.

import math
import os
import time
import uuid

import requests

API = "https://api.leadity.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['LEADITY_API_KEY']}"}
ORDER = {
    "nicheIds": ["roofing_contractor"],
    "selection": {"states": [{"country": "US", "state": "TX"}]},
    "filters": {"websitePresence": "any", "phoneTypeFilter": "mobile"},
}
LEADS = 1000

# 1. Price it. This call is free.
estimate = requests.post(f"{API}/scrapes/estimate", json=ORDER, headers=HEADERS).json()
price = math.ceil(LEADS * estimate["leadRateMilli"] / 1000)

# 2. Place it, never above the price just read.
key = str(uuid.uuid4())  # keep it: a retry with this key never buys twice
scrape = requests.post(
    f"{API}/scrapes",
    json={**ORDER, "targetLeads": LEADS, "maxCredits": price},
    headers={**HEADERS, "Idempotency-Key": key},
).json()

# 3. Wait for it, every 45 seconds.
while not requests.get(f"{API}/scrapes/{scrape['id']}/status", headers=HEADERS).json()["complete"]:
    time.sleep(45)

# 4. Download the leads.
csv = requests.get(f"{API}/scrapes/{scrape['id']}/leads.csv", headers=HEADERS).text
with open("roofers-tx.csv", "w") as f:
    f.write(csv)

• Step 1 prices 1,000 roofers in Texas with a mobile number, and step 2 places exactly that order with the price as its ceiling.
• uuid4() makes the key once per order. Store it with the order if your script can restart, and send the same key on a retry.
• Step 3 polls every 45 seconds, inside the 30 to 60 seconds the API asks for. Nothing is pushed to you when a scrape ends.
• Step 4 writes the same CSV the web app downloads, which loads into pandas with pd.read_csv("roofers-tx.csv").

What can go wrong?

Each refusal carries a code.

A refused call answers a JSON body with a stable error code and a message. A request over a rate limit answers 429 with a Retry-After header: wait that long and send it again, with its original Idempotency-Key if it spends. A key sent to the wrong door, an MCP key to the HTTP API, is refused with wrong_key_kind.

Every code and what to do about it is in the errors reference.

• Leadity API

Questions about getting Google Maps leads through an API

Related guides and pages