> ## Documentation Index
> Fetch the complete documentation index at: https://www.mapsdata.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Search for local businesses, enrich them by domain, and get back verified owner names, owner and decision-maker emails, phone intelligence, social profiles, Google Maps data, and website intelligence.

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.

```text Base URL theme={null}
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. |

<Steps>
  <Step title="Create an API key">
    Open [API access](https://www.mapsdata.io/api-access), create a named key, and copy its `md_live_…` value. Send it in the `x-api-key` header on every request.

    ```bash theme={null}
    export MAPSDATA_API_KEY="md_live_your_key"
    ```
  </Step>

  <Step title="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`.

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

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Poll status and read live results">
    Poll every 5–10 seconds. The results endpoint returns businesses already found even before the job reaches `completed`.

    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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.

```bash theme={null}
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.

<div className="callout mint-my-5 mint-rounded-xl mint-border mint-border-[#656c2e]/30 mint-bg-[#656c2e]/10 mint-px-5 mint-py-4 mint-text-sm mint-text-[#4d5321]">
  Before a large request, call <a href="/docs/endpoints/get-account"><code>GET /account</code></a>. Set <code>maxResults</code> no higher than both <code>max\_results\_per\_search</code> and <code>credits\_remaining</code>.
</div>

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

## Next steps

* Read [Authentication](/docs/authentication) before storing a production key.
* Copy the complete [Agent skill](/docs/agent-skill) into Claude Code, Codex, or another coding agent.
* Review [`POST /searches`](/docs/endpoints/create-search) for credit and idempotency behavior.
* Review [`POST /enrichments`](/docs/endpoints/create-enrichment) for supplied-business enrichment.