The Leadity API. Google Maps leads, ordered from your own code.

Choose what to scrape

A niche is one Google Maps category, such as Roofing Contractor. list_niches finds them, and list_territories and search_areas find the countries, regions and postal codes on sale.

Price it for free

estimate_scrape answers the exact price per lead, how much of the area is still unswept and the smallest order your account can place. It takes no credits.

Place the order

create_scrape holds the price of the order up front. It needs a maxCredits ceiling and an Idempotency-Key, so a retry can never buy twice.

Watch it run

A scrape takes minutes to hours. Poll get_scrape_status every 30 to 60 seconds until complete is true.

Collect the leads

Page through them with list_leads, or take the whole list as one CSV with download_leads. Whatever the run did not deliver is refunded when it settles.

1. Price the order. This call is free. It takes the niches, the area and the filters, and answers the price of one lead.

curl -X POST "https://api.leadity.io/v1/scrapes/estimate" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nicheIds": ["roofing_contractor"],
    "selection": { "states": [{ "country": "US", "state": "TX" }] },
    "filters": { "websitePresence": "any", "phoneTypeFilter": "mobile" }
  }'

• Authorization: Bearer carries your API key, which starts with lk_api_.
• nicheIds names the Google Maps categories: roofing_contractor is Roofing Contractor.
• selection names the area by country and region code, here the whole state of Texas.
• filters are the filters of the web app: "phoneTypeFilter": "mobile" keeps only mobile numbers.

The answer carries leadRateMilli, the exact price of one lead in thousandths of a credit. Any number of leads costs ceil(leads x leadRateMilli / 1000) credits.

2. Place the order. This call takes credits, so it carries a ceiling and a key of your own.

curl -X POST "https://api.leadity.io/v1/scrapes" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Idempotency-Key: tx-roofers-2026-10-04" \
  -H "Content-Type: application/json" \
  -d '{
    "nicheIds": ["roofing_contractor"],
    "selection": { "states": [{ "country": "US", "state": "TX" }] },
    "filters": { "websitePresence": "any", "phoneTypeFilter": "mobile" },
    "targetLeads": 1000,
    "maxCredits": 1000
  }'

• targetLeads is how many leads you want.
• maxCredits is the most the order may cost. If the price is above it, nothing is charged. 1,000 mobile leads at a leadRateMilli of 1000 cost 1,000 credits.
• Idempotency-Key is a key you keep for this one order. If the connection drops, send the same request with the same key: it answers the same scrape and charges nothing again.

The answer comes back at once with the scrape's id. Poll GET /v1/scrapes/{id}/status until complete is true, then download GET /v1/scrapes/{id}/leads.csv. The quickstart shows the same calls in Node.js and Python.

Open Connectors in your Leadity account, go to its API screen and create an API key. Tick the scopes it needs. The secret is shown once, so copy it then.

An account holds at most 5 live API keys. A key cannot sign in, change the account's email or password, or delete the account, so a leaked key can never take the account. Revoke it on Connectors and it stops on its next request.

Every key and MCP key on one account shares 300 calls a minute. A request over a limit answers 429 with a Retry-After header: wait that long and send it again, with its original Idempotency-Key if it spends.

What does an order through the API cost?

An order through the API spends credits at the web app's rates: a business record from $0.0032 and a carrier-verified mobile from $0.016, with each filter adding a fixed amount per lead. Reads and estimates take no credits.

A business your account already holds, in any niche, is skipped and never charged, and whatever a run does not deliver is refunded when it settles. See every rate on the pricing page.

Ordering from an AI agent instead?

The Leadity MCP server gives Claude, Cursor and any other MCP client the same operations as tools. It takes its own MCP key from Connectors, so you can revoke an agent's access without touching your scripts.

Related guides and pages

When these API facts were read

Facts as of 24 October 2026, from the Leadity API documentation at docs.leadity.io.