API

Three on-ramps. Same data.

Subscribers hit REST endpoints with a bearer token. AI assistants connect via MCP and get a native tool surface. One-off scripts can skip the account and pay per call via x402 in USDC. All three return the same normalized place rows.

POST/api/scrape

auth: Bearer

Start a scrape job

Returns a job_id immediately. The actual run completes async (1–3 minutes); poll /api/jobs/{id} or wait on the webhook.

Body

{
  "query": "dentists",
  "location": "Austin, TX",
  "max_places": 1000,
  "contact_details": true,
  "language": "en",
  "webhook_url": "https://your-host.com/hook"   // optional
}

Response

{ "ok": true, "job_id": "job_01HX...", "credits_reserved": 1334 }

GET/api/jobs/{id}

auth: Bearer

Check job status

Returns the job row plus a 10-minute signed download URL once succeeded.

Response

{
  "job": { "status": "succeeded", "results_count": 1248, ... },
  "preview_url": "https://...presigned..."
}

GET/api/jobs/{id}/export?format=csv|json

auth: Bearer

Download the dataset

Streams the file directly. CSV is the default; JSON returns the full normalized shape.

POST/api/x402/scrape

auth: none · x402

Pay-per-call (agents)

No account, no API key. Returns 402 with payment terms; sign and retry with X-Payment header. Synchronous; capped at 500 places per call.

Body

{
  "query": "yoga studios",
  "location": "Brooklyn, NY",
  "max_places": 50,
  "contact_details": false
}

Response

// 402 Payment Required (initial)
{ "x402Version": 1, "accepts": [{ "scheme":"exact", "network":"eip155:8453", "maxAmountRequired": "1000000", ... }] }

// 200 OK (after settled X-Payment header)
{ "ok": true, "count": 47, "places": [...], "payment": { "tx_hash": "0x..." } }

HTTP/api/mcp

MCP · Streamable HTTP + SSE

Model Context Protocol server

Drop our tool surface into any MCP host (Cursor, Claude desktop, ChatGPT GPTs, the AI SDK). Seven tools: scrape_google_maps, get_job_status, export_job_results, list_jobs, get_credit_balance, list_plans, whoami. Auth: Bearer API key minted in the dashboard.

Body

// .cursor/mcp.json (Cursor / any Streamable HTTP host)
{
  "mcpServers": {
    "google-maps-leads": {
      "url": "https://google-maps.0p.studio/api/mcp",
      "headers": { "Authorization": "Bearer gmk_live_..." }
    }
  }
}

Response

// Tool call: scrape_google_maps
{
  "query": "dentists",
  "location": "Austin, TX",
  "max_places": 250,
  "contact_details": true
}
→ { "ok": true, "job_id": "...", "credits_reserved": 334, "poll_with": { ... } }

// One request. Streaming results.
const res = await fetch("https://google-maps.0p.studio/api/scrape", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ${API_KEY}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "dentists",
    location: "Austin, TX",
    max_places: 1000,
    contact_details: true,
  }),
});

const { job_id } = await res.json();
// → poll /api/jobs/${job_id} or wait on the webhook

Schema

Every place row.

{
  "name": "...",
  "category": "...",
  "categories": ["..."],
  "address": "...",
  "city": "...", "state": "...",
  "postalCode": "...", "country": "US",
  "lat": 30.27, "lng": -97.74,
  "phone": "+1 512 ...",
  "phones": ["..."],
  "website": "https://...",
  "rating": 4.6, "reviewsCount": 1248,
  "openingHours": [{"day":"Mon","hours":"7am-8pm"}],
  "emails": ["..."],
  "socials": {
    "facebook":"...","instagram":"...",
    "twitter":"...","linkedin":"...","youtube":"..."
  },
  "googleMapsUrl": "https://google.com/maps/..."
}

Rate limits

· REST: 60 jobs / min / key
· x402: 5 req / sec / payer address
· Max places per job: 50,000 (REST) · 500 (x402)