API documentation

{
  "job_id": "a7f3c2d1e8b94f56...",
  "status": "queued"
}

curl -X POST https://api.mapsharvest.com/scrape \
  -H "Authorization: Bearer mh_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "dentists",
    "states": "Florida,Texas",
    "preset": "standard",
    "min_rating": 4,
    "webhook_url": "https://hooks.zapier.com/hooks/catch/...",
    "webhook_trigger": "completed"
  }'

curl https://api.mapsharvest.com/jobs/a7f3c2d1e8b94f56 \
  -H "Authorization: Bearer mh_live_..."

# CSV (all plans)
curl "https://api.mapsharvest.com/jobs/a7f3c2d1e8b94f56/download?fmt=csv" \
  -H "Authorization: Bearer mh_live_..." \
  -o leads.csv

# JSON (Growth+ only)
curl "https://api.mapsharvest.com/jobs/a7f3c2d1e8b94f56/download?fmt=json" \
  -H "Authorization: Bearer mh_live_..." \
  -o leads.json

curl -X POST https://api.mapsharvest.com/scrape/a7f3c2d1e8b94f56/stop \
  -H "Authorization: Bearer mh_live_..."

curl https://api.mapsharvest.com/fields \
  -H "Authorization: Bearer mh_live_..."

curl "https://api.mapsharvest.com/cities?states=Florida,Texas" \
  -H "Authorization: Bearer mh_live_..."

{
  "keys": [
    {
      "id": "uuid",
      "name": "My Zapier integration",
      "key_prefix": "mh_live_a1b2",
      "created_at": "2026-05-24T10:00:00Z",
      "last_used_at": "2026-05-24T14:32:00Z",
      "revoked_at": null
    }
  ]
}

{
  "id": "uuid",
  "name": "My Zapier integration",
  "key_prefix": "mh_live_a1b2",
  "created_at": "2026-05-24T10:00:00Z",
  "raw_key": "mh_live_a1b2c3d4e5f6..."
}

curl -X DELETE https://api.mapsharvest.com/api-keys/key-uuid-here \
  -H "Authorization: Bearer mh_live_..."

import requests, time

API_BASE = "https://api.mapsharvest.com"
API_KEY  = "mh_live_your_key_here"
HEADERS  = {"Authorization": f"Bearer {API_KEY}"}

# 1. Start the scrape
resp = requests.post(f"{API_BASE}/scrape", headers=HEADERS, json={
    "query":  "plumbers",
    "states": "California",
    "preset": "standard",
    "min_rating": 4.0,
})
job_id = resp.json()["job_id"]
print(f"Job started: {job_id}")

# 2. Poll until done
while True:
    status = requests.get(f"{API_BASE}/jobs/{job_id}", headers=HEADERS).json()
    print(f"  {status['status']}: {status['rows_written']} leads")
    if status["status"] in ("completed", "stopped", "failed"):
        break
    time.sleep(5)

# 3. Download CSV
csv = requests.get(f"{API_BASE}/jobs/{job_id}/download?fmt=csv", headers=HEADERS)
with open("leads.csv", "wb") as f:
    f.write(csv.content)
print("Saved leads.csv")

const API_BASE = "https://api.mapsharvest.com";
const API_KEY  = "mh_live_your_key_here";
const headers  = { Authorization: `Bearer ${API_KEY}` };

async function run() {
  // 1. Start scrape
  const start = await fetch(`${API_BASE}/scrape`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ query: "plumbers", states: "California", preset: "standard" }),
  });
  const { job_id } = await start.json();
  console.log("Job started:", job_id);

  // 2. Poll until done
  let done = false;
  while (!done) {
    await new Promise(r => setTimeout(r, 5000));
    const s = await (await fetch(`${API_BASE}/jobs/${job_id}`, { headers })).json();
    console.log(`  ${s.status}: ${s.rows_written} leads`);
    if (["completed","stopped","failed"].includes(s.status)) done = true;
  }

  // 3. Download CSV
  const csv = await fetch(`${API_BASE}/jobs/${job_id}/download?fmt=csv`, { headers });
  require("fs").writeFileSync("leads.csv", Buffer.from(await csv.arrayBuffer()));
  console.log("Saved leads.csv");
}

run();

# Start scrape, poll every 5s, download when done
JOB=$(curl -s -X POST https://api.mapsharvest.com/scrape \
  -H "Authorization: Bearer mh_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"dentists","states":"Florida","preset":"essentials"}' | jq -r .job_id)

echo "Job: $JOB"

until [ "$(curl -s https://api.mapsharvest.com/jobs/$JOB -H 'Authorization: Bearer mh_live_...' | jq -r .status)" = "completed" ]; do
  sleep 5
done

curl -s "https://api.mapsharvest.com/jobs/$JOB/download?fmt=csv" \
  -H "Authorization: Bearer mh_live_..." -o leads.csv

echo "Done: leads.csv ready"

# 1. Install the CLI
pip install mapsharvest

# 2. Install Playwright's Chromium browser (one-time)
playwright install chromium

# 3. Save your Enterprise API key
mapsharvest config --api-key mh_live_your_key_here

# Scrape "roofers" across all cities in Florida, max 60 results per city
mapsharvest scrape "roofers" --states Florida

# Scrape specific cities with filters
mapsharvest scrape "dentists" \
  --states "Texas,Florida" \
  --cities "Miami,Houston,Dallas" \
  --max-results 100 \
  --min-rating 4.0 \
  --require-website \
  --output leads.csv

# Show the browser (useful for debugging)
mapsharvest scrape "plumbers" --states California --no-headless

# View your API key and config
mapsharvest config

# List your 20 most recent jobs
mapsharvest jobs list

# Download a past job as CSV / XLSX / JSON
mapsharvest jobs download <job_id>
mapsharvest jobs download <job_id> --fmt xlsx --output leads.xlsx