Documentation
BasedOnB Documentation
Automate Google Maps lead scraping with the REST API, or connect directly to your AI assistants via the MCP server.
Ready to build?
Generate your first API key in Settings and start scraping in minutes.
Automate Google Maps lead scraping with the REST API, or connect directly to your AI assistants via the MCP server.
Generate your first API key in Settings and start scraping in minutes.
curl https://www.basedonb.com/api/v1/account \
-H "Authorization: Bearer bdb_live_YOUR_KEY_HERE"All API requests (except GET /health) require an API key. Generate one from Settings β API Keys.
Pass your key in one of two ways:
Authorization header (recommended)
Authorization: Bearer bdb_live_...
X-API-Key header
X-API-Key: bdb_live_...
https://www.basedonb.com/api/v1
100 requests / minute per API key. Exceeding this returns 429.
Look up the country / state / city values accepted by the Scrapes API. States follow the GeoNames dotted code format (US.CA, TR.34, DE.BE). Countries without a state subdivision return an empty states array β submit those jobs with only country.
Webhooks deliver real-time event notifications to your endpoint. Each request includes an X-Webhook-Signature header for verification.
Example scrape.done payload delivered to your endpoint:
POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Event-Type: scrape.done
User-Agent: BasedOnB-Webhook/1.0
{
"event": "scrape.done",
"created_at": "2026-01-15T10:05:00Z",
"data": {
"scrape_id": "job-uuid",
"query": "restaurants",
"city": "Istanbul",
"country": "TR",
"state": "TR.34",
"state_name": "Δ°stanbul",
"leads_found": 47,
"credits_charged": 47
}
}Verify the X-Webhook-Signature header to ensure requests come from BasedOnB. Find your webhook secret in Settings β Webhooks.
import { createHmac } from "crypto";
function verifyWebhook(body: string, signature: string, secret: string): boolean {
const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
return expected === signature;
}
// In your endpoint handler:
const body = await req.text();
const sig = req.headers.get("X-Webhook-Signature") ?? "";
if (!verifyWebhook(body, sig, process.env.WEBHOOK_SECRET!)) {
return new Response("Unauthorized", { status: 401 });
}| HTTP Status | Code | Description |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | API key valid but not allowed for this resource |
| 404 | not_found | Resource not found |
| 400 | bad_request | Invalid request parameters |
| 402 | insufficient_credits | Not enough credits to start a scrape |
| 429 | rate_limited | Too many open scrape jobs (max 3) or too many open target leads (max 5000). Wait for jobs to finish. |
| 500 | internal_error | Unexpected server error |
Error response format:
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits. You have 3 but need 50."
}
}basedonb'a Claude.ai, ChatGPT veya n8n gibi platformlardan tek tΔ±kla yetki ver. API anahtarΔ± yapΔ±ΕtΔ±rmaya gerek yok β OAuth 2.1 + PKCE ile gΓΌvenli, refresh tokenlarΔ± arka planda Γ§alΔ±ΕΔ±r, dilediΔin zaman dashboard'dan iptal edebilirsin.
https://basedonb.com/api/mcphttps://basedonb.com/api/mcp.ChatGPT'nin custom connector ΓΆzelliΔi aynΔ± MCP URL'ini kabul eder.
https://basedonb.com/api/mcp.n8n'in dahili MCP Clientnode'unu kullan.
https://basedonb.com/api/mcp.Plug BasedOnB into Claude, Cursor, Windsurf, or any MCP-compatible AI client. Same API key, same credits, same v1 surface β exposed as 10 tools the AI can call directly.
OAuth desteklemeyen yerel istemciler (Claude Code, Claude Desktop, Cursor) iΓ§in config dosyasΔ±na MCP URL + uzun ΓΆmΓΌrlΓΌ API key gir. API anahtarΔ±nΔ± API & Webhooks sayfasΔ±ndan oluΕturabilirsin.
Pick your client, copy the snippet. Replace the placeholder key with your own.
claude mcp add basedonb https://www.basedonb.com/api/mcp \
--transport http \
--header "Authorization: Bearer bdb_live_xxxxxxxxxxxxxxxxx"Run this in any terminal. MCP becomes available across all Claude Code sessions.
All MCP tools authenticate with the same bdb_live_β¦ API key as the REST API. Pass it via the Authorization: Bearer header on the MCP transport.
MCP endpoint Γ§ift kimlik doΔrulama destekler:
Authorization: Bearer eyJ...Authorization: Bearer bdb_live_...basedonb, OAuth 2.1 + PKCE + Dynamic Client Registration (RFC 7591) + Authorization Server Metadata (RFC 8414) standartlarΔ±nΔ± uygular.
GET /.well-known/oauth-protected-resource β RFC 9728 resource metadata.GET /.well-known/oauth-authorization-server β RFC 8414 AS metadata.POST /oauth/register β Dynamic Client Registration (aΓ§Δ±k, PKCE-only public client).GET /oauth/authorize β Login + consent; redirect_uri'ye ?code=β¦&state=β¦ ile dΓΆner.POST /oauth/token β Code β access & refresh tokens; refresh rotation aktif.POST /oauth/revoke β RFC 7009 refresh token revocation.Access token JWT (HS256, 1 saat TTL). Refresh token opaque, her kullanΔ±mda rotate olur ve chain'e baΔlΔ±dΔ±r β leak ΕΓΌphesi tespit edilirse tΓΌm chain revoke edilir.