Quickstart

Mapsdata uses the same search and enrichment pipeline for API and dashboard requests. A job created here appears in Dashboard and Lead lists immediately, and new businesses appear in the UI while the job is still running.

Base URL

https://www.mapsdata.io/api/v1

Three workflows

Workflow	Endpoint	Use when
Business discovery	`POST /searches` with `enrich_contacts: false`	You need Google Maps businesses without contact enrichment.
Full pipeline	`POST /searches` with `enrich_contacts: true`	You want discovery followed by contact and people enrichment.
Standalone enrichment	`POST /enrichments`	You already have business names and website URLs.

Create an API key

Open API access, create a named key, and copy its md_live_… value. Send it in the x-api-key header on every request.

export MAPSDATA_API_KEY="md_live_your_key"

Find the UI-compatible location

Search the location catalog exactly as the Mapsdata UI does. For New York, use the returned label as input.location and country_code as input.countryCode.

curl "https://www.mapsdata.io/api/v1/locations?q=New%20York&country=US" \
  -H "x-api-key: $MAPSDATA_API_KEY"

{
  "locations": [
    {
      "location_code": 1023191,
      "city": "New York",
      "region": "New York",
      "country_code": "US",
      "full_name": "New York, New York, United States",
      "label": "New York, New York"
    }
  ]
}

Start a business search

Use one stable idempotency key for one logical search. If a network request times out, retry the same body with the same key.

curl -X POST "https://www.mapsdata.io/api/v1/searches" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MAPSDATA_API_KEY" \
  -H "Idempotency-Key: ny-plumbers-2026-10-01" \
  -d '{
    "name": "New York plumbers",
    "input": {
      "query": "plumbers",
      "location": "New York, New York",
      "countryCode": "US",
      "maxResults": 100,
      "language": "en"
    },
    "enrich_contacts": true
  }'

The API responds with 202 Accepted and a job_id.

Poll status and read live results

Poll every 5–10 seconds. The results endpoint returns businesses already found even before the job reaches completed.

curl "https://www.mapsdata.io/api/v1/searches/JOB_ID" \
  -H "x-api-key: $MAPSDATA_API_KEY"

curl "https://www.mapsdata.io/api/v1/searches/JOB_ID/results?page=1&page_size=500" \
  -H "x-api-key: $MAPSDATA_API_KEY"

Continue requesting pages while has_more is true. Stop polling when status is completed or failed, then fetch every result page once more.

Enrich businesses you already have

Submit a business name and absolute website URL for every company. This creates another asynchronous, UI-visible job without running Google Maps discovery.

curl -X POST "https://www.mapsdata.io/api/v1/enrichments" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MAPSDATA_API_KEY" \
  -H "Idempotency-Key: supplied-businesses-2026-10-01" \
  -d '{
    "name": "Businesses to enrich",
    "businesses": [
      {
        "business_name": "Plumbing NYC",
        "website_url": "https://plumbing-nyc.example.com"
      }
    ]
  }'

Poll GET /enrichments/{job_id} and read GET /enrichments/{job_id}/results using the same pagination and terminal-state rules as searches.

Before a large request, call GET /account. Set maxResults no higher than both max_results_per_search and credits_remaining.

Searches must request at least 100 businesses. Smaller requests return 422 without creating a job or reserving credits.

Next steps

Read Authentication before storing a production key.
Copy the complete Agent skill into Claude Code, Codex, or another coding agent.
Review POST /searches for credit and idempotency behavior.
Review POST /enrichments for supplied-business enrichment.

Getting started

Endpoints

Reference

Three workflows

Enrich businesses you already have

Next steps

​Three workflows

​Enrich businesses you already have

​Next steps

Three workflows

Enrich businesses you already have

Next steps