BasedOnBusiness

BasedOnB Dokümantasyonu

Google Maps lead çekme işlemini REST API ile otomatikleştirin veya MCP sunucusuyla doğrudan AI asistanlarınıza bağlayın.

Hızlı Başlangıç

curl https://www.basedonb.com/api/v1/account \
  -H "Authorization: Bearer bdb_live_YOUR_KEY_HERE"

Kimlik Doğrulama

Tüm API istekleri (GET /health hariç) bir API anahtarı gerektirir. API & Webhooks → API Anahtarları üzerinden oluşturun.

Anahtarınızı iki yoldan biriyle gönderin:

Authorization header (önerilen)

Authorization: Bearer bdb_live_...

X-API-Key header

X-API-Key: bdb_live_...

REST API'yi güvenilir bir backend üzerinden kullanın. Tarayıcılar arası cross-origin istekler bilinçli olarak kapalıdır; API anahtarlarını istemci tarafı kodunda asla açığa çıkarmayın.

REST yanıtları X-Request-Id içerir. Kimliği doğrulanmış isteklerde ayrıca RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset; sınıra takılan isteklerde Retry-After gönderilir.

Temel URL

https://www.basedonb.com/api/v1

Hız Limitleri

API anahtarı başına dakikada 100 istek. Bu sınırı aşmak 429 döner.

Uç Noktalar

Sağlık

Hesap

Taramalar

Coğrafi Veri

Scrapes API'nin kabul ettiği ülke / eyalet / şehir değerlerini arayın. Eyaletler GeoNames nokta kod formatını izler (US.CA, TR.34, DE.BE). Alt bölüm içermeyen ülkeler boş states dizisi döner. Bu işleri yalnızca country ile gönderin.

Krediler & Faturalama

Webhook'lar

Webhook'lar gerçek zamanlı olay bildirimlerini uç noktanıza iletir. Her istek doğrulama için bir X-Webhook-Signature başlığı içerir.

API Anahtarı Yönetimi

API keys are created and revoked only from the authenticated dashboard. Choose the minimum required scopes when creating a key: mcp, scrapes:read, scrapes:write, account:read, geodata:read, webhooks:read, and webhooks:write. Keys cannot create or manage other keys through the public API.

Webhook Yükü

Uç noktanıza iletilen örnek scrape.done yükü:

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Id: delivery-uuid
X-Webhook-Event-Id: event-uuid
X-Webhook-Timestamp: 2026-07-18T10:05:00Z
X-Webhook-Signature: v1=abc123...
X-Event-Type: scrape.done
User-Agent: BasedOnB-Webhook/2.0

{
  "id": "event-uuid",
  "event": "scrape.done",
  "created_at": "2026-01-15T10:05:00Z",
  "data": {
    "scrape_id": "job-uuid",
    "query": "restaurants",
    "queries": ["restaurants"],
    "city": "Istanbul",
    "country": "TR",
    "state": "TR.34",
    "state_name": "İstanbul",
    "status": "done",
    "leads_found": 47,
    "credits_charged": 47,
    "error": null,
    "results_path": "/api/v1/scrapes/job-uuid/results"
  }
}

Webhook İmzalarını Doğrulama

İsteklerin BasedOnB'den geldiğinden emin olmak için X-Webhook-Signature başlığını doğrulayın. Webhook oluşturulurken veya anahtarı yenilenirken yalnızca bir kez gösterilen imzalama anahtarını kaydedin.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(body: string, timestamp: string, signature: string, secret: string): boolean {
  const match = /^v1=([0-9a-f]{64})$/i.exec(signature);
  if (!match) return false;

  const expected = createHmac("sha256", secret)
    .update(timestamp + "." + body)
    .digest();
  const received = Buffer.from(match[1], "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

// In your endpoint handler:
const body = await req.text();
const sig = req.headers.get("X-Webhook-Signature") ?? "";
const timestamp = req.headers.get("X-Webhook-Timestamp") ?? "";
if (!verifyWebhook(body, timestamp, sig, process.env.WEBHOOK_SECRET!)) {
  return new Response("Unauthorized", { status: 401 });
}

Teslimatı onaylamak için herhangi bir 2xx durum kodu döndürün. Başarısız teslimatlar 1 dakika, 5 dakika, 30 dakika ve 2 saat sonra, en fazla 5 denemeye kadar tekrarlanır. X-Webhook-Event-Id değerini saklayıp daha önce işlenen olayları yok sayın. Timestamp olayın oluşturulma zamanıdır ve retry'larda değişmez; geçerli bir retry'ı yalnızca timestamp eski diye reddetmeyin.

Hata Kodları

HTTP Durum	Kod	Açıklama
400	bad_request	Invalid request parameters
401	unauthorized	Missing, invalid, expired, or revoked credential
402	insufficient_credits	Not enough credits to start a scrape
402	payment_required	Subscription payment is past due
403	forbidden	Credential is missing the required scope
404	not_found	Resource not found
409	conflict	Idempotency-key conflict or resource limit conflict
429	rate_limited	Per-key request limit, webhook-test limit, or open scrape capacity limit exceeded
500	internal_error	Unexpected server error
503	service_unavailable	A required dependency is unavailable

Hata yanıt formatı:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. You have 3 but need 50."
  }
}

Başlamaya hazır mısınız?

Ayarlar'dan ilk API anahtarınızı oluşturun ve dakikalar içinde taramaya başlayın.