Agent skill

# Mapsdata API — AI assistant instructions

Use Mapsdata to discover Google Maps businesses, enrich discovered businesses, or enrich supplied business names and websites.

Base URL: `https://www.mapsdata.io/api/v1`
Authentication: `x-api-key: md_live_...`

## Choose one workflow

- Discovery only: `POST /searches` with `enrich_contacts: false`.
- Full pipeline: `POST /searches` with `enrich_contacts: true`.
- Supplied-business enrichment: `POST /enrichments` with one or more `{business_name, website_url}` objects.
- Selective two-stage pipeline: run discovery with `enrich_contacts: false`, keep results with a useful website, then submit only those businesses to `POST /enrichments`. Search and enrichment are charged separately.

## Search workflow

1. Call `GET /account` before a search and read `max_results_per_search` and `credits_remaining`.
2. Resolve the location with `GET /locations?q=...&country=...`.
3. Copy the selected location's `label` to `input.location` and `country_code` to `input.countryCode`. This matches the Mapsdata UI.
4. Optionally normalize a business type with `GET /categories?q=...` and use its `display_name` as `input.query`.
5. Start `POST /searches` with a stable, unique `Idempotency-Key`; set `enrich_contacts` deliberately and persist the returned `job_id`.
6. Poll `GET /searches/{job_id}` every 5–10 seconds until `completed` or `failed`.
7. During processing, `GET /searches/{job_id}/results` already contains businesses found so far.
8. Fetch results with `page_size=500`, incrementing `page` until `has_more=false`.
9. After the job becomes terminal, fetch all result pages again and assert the accumulated count equals `total`.
10. Use `email_verification_status` and `email_verifications`; an address being present does not prove verification.

## Standalone enrichment workflow

1. Call `GET /account` and make the batch no larger than both `max_results_per_search` and `credits_remaining`.
2. Start `POST /enrichments` with a stable, unique `Idempotency-Key` and a `businesses` array containing unique `business_name` and absolute HTTP(S) `website_url` pairs.
3. Persist `job_id` and poll `GET /enrichments/{job_id}` every 5–10 seconds until `completed` or `failed`.
4. Read live rows from `GET /enrichments/{job_id}/results`; all submitted businesses exist immediately and enrichment fields update in place.
5. After completion, fetch all pages again and inspect per-field enrichment and verification statuses.

Do not poll an enrichment job through `/searches/{id}` or a discovery job through `/enrichments/{id}`. List each family with `GET /searches` and `GET /enrichments` respectively. Both appear in the Mapsdata dashboard and use the same lead detail UI.

Never retry the same logical job with a new idempotency key after a timeout. Status and result reads consume no lead credits. API jobs and partial leads also appear in the Mapsdata dashboard.

Set `input.maxResults` to at least 100 and no higher than the lesser of `max_results_per_search` and `credits_remaining`. The API rejects invalid or unaffordable requests before creating a job. A free account receives one 100-lead search; paid searches accept 100–700 leads per request.

The account has a shared rolling limit of 1,000 requests per 60 seconds across all keys. On `429`, honor `Retry-After`, then retry with exponential backoff and jitter. Keep the same idempotency key when retrying search or enrichment creation.

Ask for the API key at runtime. Never save it in source control, shell history, logs, reports, or this file.