v1REST API

Sektör Bul API dokümantasyonu

Google Haritalar'daki işletmeleri il, ilçe ve sektöre göre kendi yazılımınızdan listeleyin. Bir arama başlatırsınız, durumunu sorgularsınız ve sonuçları JSON olarak alırsınız; paneldeki aramalarla aynı motor, aynı havuz ve aynı kota.

Temel URL

https://api.sektorbul.com

Tüm endpoint'ler /api/v1 önekiyle başlar. İstek ve yanıt gövdeleri JSON'dır; tarih alanları ISO 8601 (UTC) biçimindedir.

Kimlik doğrulama: X-API-Key header
Biçim: REST · JSON (UTF-8)
Hız sınırı: 1 istek / sn / anahtar
Erişim: Enterprise paket

Başlarken

Hızlı başlangıç

Dört adımda ilk işletme listenizi alın. Sağdaki örnekte dili değiştirdiğinizde sayfadaki tüm örnekler aynı dile geçer.

1
Anahtar oluşturun
Panel → API sayfasında yeni bir anahtar oluşturun. Tam anahtar yalnızca bir kez gösterilir; güvenli bir yerde saklayın.
2
Aramayı başlatın
POST/api/v1/searches
Anahtar kelimeyi ve isteğe bağlı il/ilçeyi gönderin. Yanıt 202 Accepted ve aramanın id değeridir.
3
Durumu sorgulayın
GET/api/v1/searches/{id}
status değeri Completed olana kadar 2 saniyede bir sorgulayın: Queued → Running → Completed.
4
Sonuçları alın
İşletmeler aynı yanıtın results.items dizisindedir. page / pageSize ile sayfalayın; yalnızca bölge içini istiyorsanız inRegionOnly=true gönderin.

Uçtan uca akış

# 1) Anahtarı ortam değişkenine koyun (Panel → API)
export SEKTORBUL_API_KEY="sb_live_..."

# 2) Aramayı başlatın → 202 Accepted + id
curl -X POST https://api.sektorbul.com/api/v1/searches \
  -H "X-API-Key: $SEKTORBUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"kuaför","city":"İstanbul","district":"Fatih"}'

# 3) Durumu sorgulayın (2 sn arayla, "Completed" olana kadar)
curl https://api.sektorbul.com/api/v1/searches/0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55 \
  -H "X-API-Key: $SEKTORBUL_API_KEY"

# 4) Sonuçlar: yanıttaki results.items dizisi

Başlarken

Postman koleksiyonu

Tüm uçları kod yazmadan denemek için hazır Postman koleksiyonunu kullanın. Kimlik doğrulama, hız sınırına uygun bekleme,searchId aktarımı, testler ve örnek yanıtlar içinde gelir.

Postman koleksiyonunu indir8 istek · testler · örnek yanıtlar

Kurulum

Postman'de Import ile koleksiyonu içe aktarın. Ayrı bir ortam dosyası gerekmez; temel adres (https://api.sektorbul.com) koleksiyonda hazırdır.
Koleksiyonun Variables sekmesinde apiKey değerine Panel → API'de oluşturduğunuz sb_live_… anahtarını yazıp kaydedin.
Arama başlat isteğini gönderin: dönen id otomatik olarak {{searchId}} değişkenine yazılır.
Durum ve sonuçlar isteğini gönderin; status Completed olana kadar tekrarlayın.

Tüm akışı tek tıkla çalıştırın

1 · Arama akışı klasörünü Collection Runner ile çalıştırırsanız durum isteği arama bitene kadar 2 saniye arayla kendini tekrarlar. Koleksiyon istekleri en az 1,25 saniye arayla gönderir; yine de 429 rate_limited gelirse Retry-After kadar bekleyin.

Sektör Bul API v1Postman v2.1

1 · Arama akışı

POSTArama başlatid → {{searchId}}
GETDurum ve sonuçlarRunner'da bitene kadar tekrarlar

2 · Hesap

GETAramalarım
GETKota durumu

3 · Hata örnekleri

GETAnahtar yok → 401
GETGeçersiz anahtar → 401
POSTİl eksik → 400
POSTGeçersiz il → 400

auth X-API-Key: {{apiKey}}

pre-request istekler ≥ 1,25 sn arayla; 429 gelirse bekleyip tekrar

baseUrl https://api.sektorbul.com

vars {{apiKey}} · {{searchId}}

Başlarken

Kimlik doğrulama

Her isteğe API anahtarınızı X-API-Key header'ı ile ekleyin. Anahtarlar sb_live_ önekiyle başlar ve ardından 40 rastgele karakter gelir.

X-API-Key: sb_live_••••••••••••••••••••••••••••••••••••••••

Anahtar yönetimi

Anahtarlar Panel → API sayfasından yönetilir.

Aynı anda en fazla 5 aktif anahtar tutabilirsiniz (örneğin her ortam için ayrı bir anahtar).
Her anahtara bir geçerlilik süresi verebilirsiniz: 30, 90, 180, 365 gün ya da süresiz.
Yenile (rotate): anahtara yeni bir gizli değer üretir; eski değer o anda çalışmayı bırakır.
İptal et (revoke): anahtarı kalıcı olarak devre dışı bırakır.
Tam anahtar yalnızca oluşturma ve yenileme anında bir kez gösterilir; sonradan görüntülenemez.

Anahtarınızı gizli tutun

Anahtarı yalnızca sunucu tarafında kullanın; tarayıcı koduna, mobil uygulamaya ya da herkese açık bir depoya koymayın. Sızdığından şüphelenirseniz hemen yenileyin veya iptal edin.

Enterprise paket gerekir

API erişimi Enterprise pakete dahildir. Diğer paketlerle yapılan istekler 403 (forbidden) döner.

Anahtarı deneyin: kota sorgusu

curl https://api.sektorbul.com/api/v1/quota \
  -H "X-API-Key: $SEKTORBUL_API_KEY"

{
  "title": "API anahtarı gerekli",
  "status": 401,
  "detail": "X-API-Key header'ı gönderilmedi.",
  "code": "api_key_missing"
}

Başlarken

Hız sınırı ve kota

Saniyede 1 istek

Her API anahtarı saniyede en fazla 1 istek yapabilir. Sınır aşılırsa 429 yanıtı, Retry-After: 1 header'ı ve rate_limited kodu döner. Durum sorgularını 2 saniye arayla yapmanızı öneririz.

Günlük kota

Kota, gün içinde alabileceğiniz işletme sayısıdır (istek sayısı değil). Web paneliyle ortaktır.

Paket	Günlük işletme	API
Basic	500	yok
Pro	3.000	yok
Enterprise	10.000	var

Tablodaki limitler paketlerin varsayılan değerleridir; hesabınıza tanımlı güncel limiti kota endpoint'i gösterir.
Kota her gün 00:00'da (Türkiye saati) sıfırlanır.
Yöneticiler hesabınıza tek seferlik ek kredi tanımlayabilir; günlük limit = paket limiti + kredi bakiyesi.
Havuzdan gelen sonuçlar (son 72 saatte yapılmış aynı arama) anında döner ve kotadan yine düşer.
Kota dolduğunda 429 ve daily_quota kodu döner. Güncel durumu GET /api/v1/quota ile görebilirsiniz.

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "title": "Çok fazla istek",
  "status": 429,
  "detail": "İstek sınırı aşıldı. 1 saniye sonra tekrar deneyin.",
  "code": "rate_limited"
}

Başlarken

Hatalar

Hatalar RFC 7807 tarzı JSON olarak döner: title, status, detail ve makine tarafından okunabilir code. Doğrulama hatalarında ayrıca alan bazlı mesajları içeren errors nesnesi bulunur. Kodunuzda detail metnine değil, HTTP durumuna ve code değerine göre karar verin.

HTTP	code	Ne zaman
400	errors	Gövde ya da sorgu parametreleri geçersiz (ör. keyword boş, maxResults aralık dışında).
400	`city_required`	city gönderilmedi ya da boş. Her arama bir il içinde yapılır.
400	`invalid_city`	city, Türkiye'nin 81 ilinden biri değil (ör. yazım hatası).
401	`api_key_missing`	X-API-Key header'ı gönderilmedi.
401	`invalid_api_key`	Anahtar bilinmiyor, süresi dolmuş ya da iptal edilmiş.
403	`forbidden`	Paketiniz API erişimi içermiyor (Enterprise gerekir).
404	—	Arama yok ya da size ait değil.
429	`rate_limited`	Saniyede 1'den fazla istek. Retry-After kadar bekleyip tekrar deneyin.
429	`daily_quota`	Günlük işletme kotası doldu; 00:00'da (TSİ) yenilenir.

{
  "title": "Geçersiz istek",
  "status": 400,
  "detail": "Bir veya daha fazla alan geçersiz.",
  "errors": {
    "keyword": ["Anahtar kelime zorunludur."],
    "maxResults": ["20 ile 500 arasında olmalıdır."]
  }
}

Endpoint

Arama başlat

POST/api/v1/searches

Yeni bir işletme araması kuyruğa alır. Yanıt 202 Accepted'tır; Location header'ı ve gövdedeki statusUrl aramanın durum adresini verir. Aynı arama son 72 saat içinde yapıldıysa sonuçlar havuzdan gelir ve status doğrudan Completed olabilir.

Gövde (JSON)

Ad	Tip	Zorunlu	Açıklama
`keyword`	`string`	evet	Aranacak sektör ya da anahtar kelime, ör. `"kuaför"`. En fazla 120 karakter.
`city`	`string`	evet	İl, ör. `"İstanbul"`. Türkiye'nin 81 ilinden biri olmalı; büyük/küçük harf ve Türkçe karakter farkı önemsenmez (`"istanbul"` da olur). Boş ya da geçersiz il `400` döner.
`district`	`string \| null`	hayır	İlçe, ör. `"Fatih"`. İl ile birlikte kullanılır.
`includeEmails`	`boolean`	hayır	İşletmelerin web sitelerini de ziyaret ederek e-posta ve sosyal medya hesaplarını toplar. Aramayı yavaşlatır.Varsayılan: `false`
`deepScan`	`boolean`	hayır	`includeEmails` ile birlikte, sitelerin iletişim sayfalarını da tarar.Varsayılan: `false`
`maxResults`	`integer`	hayır	Alınacak en fazla işletme sayısı: 20–500.Varsayılan: `500`

Yanıt alanları

Alan	Tip	Açıklama
`success`	`boolean`	Arama kabul edildi.
`id`	`string (uuid)`	Aramanın kimliği; sonraki isteklerde kullanılır.
`status`	`string`	Genellikle `Queued`; havuzdan geldiyse `Completed`.
`statusUrl`	`string`	Durum ve sonuç adresi (`Location` header'ı ile aynı).

Dönen işletme sayısı günlük kotanızdan düşer. maxResults ile yalnızca ihtiyacınız kadarını isteyerek kotanızı koruyun.

İstek

curl -X POST https://api.sektorbul.com/api/v1/searches \
  -H "X-API-Key: $SEKTORBUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "kuaför",
    "city": "İstanbul",
    "district": "Fatih",
    "includeEmails": true,
    "maxResults": 200
  }'

HTTP/1.1 202 Accepted
Location: https://api.sektorbul.com/api/v1/searches/0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55
Content-Type: application/json

{
  "success": true,
  "id": "0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55",
  "status": "Queued",
  "statusUrl": "https://api.sektorbul.com/api/v1/searches/0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55"
}

Endpoint

Arama durumu ve sonuçlar

GET/api/v1/searches/{id}

Aramanın durumunu ve (varsa) sonuçlarını döner. Running sırasında o ana kadar bulunan kısmi sonuçlar gelir; sorgulamaya devam edin. Completed olduğunda sonuçlar nihaidir.

Yol parametresi

Ad	Tip	Zorunlu	Açıklama
`id`	`string (uuid)`	evet	Arama başlatırken dönen `id`.

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`page`	`integer`	hayır	Sayfa numarası (1'den başlar).Varsayılan: `1`
`pageSize`	`integer`	hayır	Sayfa başına işletme: 1–1000. Bir arama en fazla 500 kayıt döndüğünden 1000 ile tek sayfada hepsini alırsınız.Varsayılan: `100`
`inRegionOnly`	`boolean`	hayır	Varsayılan `false`: aramanın bulduğu tüm işletmeler gelir; her birinde `inRegion` alanı vardır. `true` gönderirseniz yalnızca istenen il/ilçe (ya da mahalle) içindekiler döner — bu durumda sonuç boş olabilir.Varsayılan: `false`

Durum değerleri

status	Anlamı
Queued	Kuyrukta, henüz başlamadı. `results` = `null`.
Running	Çalışıyor. Kısmi sonuçlar gelir; sorgulamaya devam edin.
Completed	Tamamlandı. Sonuçlar nihai.
Failed	Başarısız. Sebep `error` alanında.
Cancelled	İptal edildi.

Yanıt alanları

Alan	Tip	Açıklama
`id`	`string (uuid)`	Aramanın kimliği.
`status`	`string`	Aşağıdaki durum değerlerinden biri.
`keyword, city, district`	`string \| null`	İstekte gönderilen arama.
`fromCache`	`boolean`	Sonuçlar havuzdan mı geldi (son 72 saatte aynı arama).
`resultCount`	`number`	Bulunan toplam işletme.
`inRegionCount`	`number`	Bunlardan istenen bölgenin içinde olanlar.
`error`	`string \| null`	Yalnızca `Failed` durumunda dolu.
`createdAt, completedAt`	`string (ISO 8601, UTC) \| null`	Oluşturulma ve bitiş zamanı.
`results`	`object \| null`	`Queued` iken `null`. Diğer durumlarda `page`, `pageSize`, `total`, `inRegionOnly` ve `items` (işletme dizisi).

İstek

curl "https://api.sektorbul.com/api/v1/searches/0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55?page=1&pageSize=100&inRegionOnly=false" \
  -H "X-API-Key: $SEKTORBUL_API_KEY"

{
  "id": "0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55",
  "status": "Completed",
  "keyword": "kuaför",
  "city": "İstanbul",
  "district": "Fatih",
  "fromCache": false,
  "resultCount": 200,
  "inRegionCount": 176,
  "error": null,
  "createdAt": "2026-11-08T09:41:12Z",
  "completedAt": "2026-11-08T09:42:03Z",
  "results": {
    "page": 1,
    "pageSize": 100,
    "total": 176,
    "inRegionOnly": false,
    "items": [
      {
        "id": 48213,
        "rank": 1,
        "inRegion": true,
        "name": "Atölye Makas Kuaför",
        "category": "Kuaför",
        "categories": ["Kuaför", "Güzellik salonu"],
        "rating": 4.8,
        "reviewCount": 312,
        "phone": "0532 ••• •• 41",
        "phoneIntl": "+90 532 ••• •• 41",
        "website": "https://atolyemakas.example",
        "email": "merhaba@atolyemakas.example",
        "emails": ["merhaba@atolyemakas.example"],
        "instagram": "https://instagram.com/atolyemakas.ornek",
        "facebook": null,
        "linkedin": null,
        "tiktok": null,
        "youtube": null,
        "x": null,
        "address": "Örnek Sk. No: 12, Balat, 34087 Fatih/İstanbul",
        "neighborhood": "Balat",
        "district": "Fatih",
        "city": "İstanbul",
        "postalCode": "34087",
        "latitude": 41.0291,
        "longitude": 28.9487,
        "todayHours": "09:00–20:00",
        "openStatus": "Açık",
        "googlePlaceId": "ChIJ-ORNEK-0000000000000",
        "cid": "1234567890123456789",
        "mapsUrl": "https://maps.google.com/?cid=1234567890123456789"
      },
      …
    ]
  }
}

Endpoint

Aramaları listele

GET/api/v1/searches

Aramalarınızı en yeniden eskiye listeler. Öğeler, sonuçlar (results) olmadan arama nesnesidir; bir aramanın işletmeleri için durum ve sonuçlar endpoint'ini kullanın.

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`page`	`integer`	hayır	Sayfa numarası.Varsayılan: `1`
`pageSize`	`integer`	hayır	Sayfa başına arama.Varsayılan: `20`

İstek

curl "https://api.sektorbul.com/api/v1/searches?page=1&pageSize=20" \
  -H "X-API-Key: $SEKTORBUL_API_KEY"

200OK

{
  "items": [
    {
      "id": "0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55",
      "status": "Completed",
      "keyword": "kuaför",
      "city": "İstanbul",
      "district": "Fatih",
      "fromCache": false,
      "resultCount": 200,
      "inRegionCount": 176,
      "error": null,
      "createdAt": "2026-11-08T09:41:12Z",
      "completedAt": "2026-11-08T09:42:03Z"
    },
    {
      "id": "0193a6f0-1b2c-7d4e-8f90-a1b2c3d4e5f6",
      "status": "Completed",
      "keyword": "diş kliniği",
      "city": "Ankara",
      "district": null,
      "fromCache": true,
      "resultCount": 500,
      "inRegionCount": 488,
      "error": null,
      "createdAt": "2026-11-07T16:05:40Z",
      "completedAt": "2026-11-07T16:05:40Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 2
}

Endpoint

Kota durumu

GET/api/v1/quota

Bugünkü kullanımınızı ve kalan işletme hakkınızı döner. Büyük bir aramadan önce kontrol etmek için idealdir.

Alan	Tip	Açıklama
`usedToday`	`number`	Bugün alınan işletme sayısı.
`dailyLimit`	`number`	`baseLimit` + `creditBalance`.
`remaining`	`number`	Bugün kalan işletme hakkı.
`resetsAt`	`string (ISO 8601)`	Kotanın sıfırlanacağı an (00:00 Türkiye saati).
`plan`	`string`	Paket kodu.
`planName`	`string`	Paketin görünen adı.
`contactData`	`boolean`	Paket e-posta ve sosyal medya verisi içeriyor mu.
`apiAccess`	`boolean`	Paket API erişimi içeriyor mu.
`baseLimit`	`number`	Paketin günlük işletme limiti.
`creditBalance`	`number`	Tek seferlik ek kredi bakiyesi.

İstek

curl https://api.sektorbul.com/api/v1/quota \
  -H "X-API-Key: $SEKTORBUL_API_KEY"

200OK

{
  "usedToday": 1240,
  "dailyLimit": 12000,
  "remaining": 10760,
  "resetsAt": "2026-11-08T21:00:00Z",
  "plan": "Enterprise",
  "planName": "Enterprise",
  "contactData": true,
  "apiAccess": true,
  "baseLimit": 10000,
  "creditBalance": 2000
}

Referans

İşletme (Place) nesnesi

results.items dizisindeki her öğe bir işletmedir. Bilinmeyen alanlar null (diziler boş) döner. Örnekteki işletme ve iletişim bilgileri hayalidir.

İletişim verisi

İletişim verisi içermeyen paketlerde e-posta ve sosyal medya alanları "***" olarak maskelenir. Enterprise pakette tam halleri gelir.

Alan	Tip	Açıklama
`id`	`number`	İşletme kaydının kimliği.
`rank`	`number`	Google Haritalar sonuç sırası (1'den başlar).
`inRegion`	`boolean`	İşletme istenen il/ilçenin içinde mi.
`name`	`string`	İşletme adı.
`category`	`string \| null`	Ana kategori.
`categories`	`string[]`	Tüm kategoriler.
`rating`	`number \| null`	Ortalama puan (1–5).
`reviewCount`	`number \| null`	Yorum sayısı.
`phone`	`string \| null`	Yerel biçimde telefon.
`phoneIntl`	`string \| null`	Uluslararası biçimde telefon (+90 …).
`website`	`string \| null`	Web sitesi.
`email`	`string \| null`	Birincil e-posta (includeEmails ile).
`emails`	`string[]`	Bulunan tüm e-postalar.
`instagram, facebook, linkedin, tiktok, youtube, x`	`string \| null`	Sosyal medya bağlantıları (includeEmails ile).
`address`	`string \| null`	Açık adres.
`neighborhood`	`string \| null`	Mahalle.
`district`	`string \| null`	İlçe.
`city`	`string \| null`	İl.
`postalCode`	`string \| null`	Posta kodu.
`latitude, longitude`	`number`	Koordinatlar (WGS84).
`todayHours`	`string \| null`	Bugünün çalışma saatleri.
`openStatus`	`string \| null`	Anlık açık/kapalı bilgisi.
`googlePlaceId`	`string \| null`	Google Place ID.
`cid`	`string \| null`	Google Haritalar CID.
`mapsUrl`	`string`	İşletmenin Google Haritalar bağlantısı.

200results.items[0]

{
  "id": 48213,
  "rank": 1,
  "inRegion": true,
  "name": "Atölye Makas Kuaför",
  "category": "Kuaför",
  "categories": ["Kuaför", "Güzellik salonu"],
  "rating": 4.8,
  "reviewCount": 312,
  "phone": "0532 ••• •• 41",
  "phoneIntl": "+90 532 ••• •• 41",
  "website": "https://atolyemakas.example",
  "email": "merhaba@atolyemakas.example",
  "emails": ["merhaba@atolyemakas.example"],
  "instagram": "https://instagram.com/atolyemakas.ornek",
  "facebook": null,
  "linkedin": null,
  "tiktok": null,
  "youtube": null,
  "x": null,
  "address": "Örnek Sk. No: 12, Balat, 34087 Fatih/İstanbul",
  "neighborhood": "Balat",
  "district": "Fatih",
  "city": "İstanbul",
  "postalCode": "34087",
  "latitude": 41.0291,
  "longitude": 28.9487,
  "todayHours": "09:00–20:00",
  "openStatus": "Açık",
  "googlePlaceId": "ChIJ-ORNEK-0000000000000",
  "cid": "1234567890123456789",
  "mapsUrl": "https://maps.google.com/?cid=1234567890123456789"
}

Referans

Polling yardımcısı

Aramalar birkaç saniye ile birkaç dakika arasında sürer (includeEmails ve deepScan süreyi uzatır). Sonucu beklemek için durumu düzenli aralıklarla sorgulayın:

2 saniyede bir sorgulayın; bu, anahtar başına 1 istek/sn sınırının güvenli tarafında kalır.
429 + rate_limited gelirse Retry-After kadar bekleyip devam edin; daily_quota gelirse durun.
Completed gelince bitirin; Failed ya da Cancelled gelince hatayı raporlayın.
Tamamlanan aramayı pageSize=1000 ile tek istekte alın.
Aynı anahtarla birden fazla aramayı paralel izliyorsanız istekleri sıraya koyun; sınır anahtar başınadır.

İpucu

POST yanıtında status zaten Completed ise (havuzdan geldiyse) beklemeden sonuçları isteyebilirsiniz.

waitForSearch

#!/usr/bin/env bash
# jq gerekir. Her 2 saniyede bir sorgular (1 istek/sn sınırının güvenli tarafı).
ID="0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55"

while true; do
  STATUS=$(curl -s "https://api.sektorbul.com/api/v1/searches/$ID?pageSize=1" \
    -H "X-API-Key: $SEKTORBUL_API_KEY" | jq -r .status)
  echo "Durum: $STATUS"
  case "$STATUS" in
    Completed) break ;;
    Failed|Cancelled) exit 1 ;;
  esac
  sleep 2
done

# Tamamlandı: tüm sonuçları tek sayfada alın (en fazla 500 kayıt)
curl -s "https://api.sektorbul.com/api/v1/searches/$ID?pageSize=1000" \
  -H "X-API-Key: $SEKTORBUL_API_KEY" | jq '.results.items'

Entegrasyona hazır mısınız?

Panelden bir API anahtarı oluşturun ve ilk aramanızı birkaç dakika içinde başlatın.

API anahtarı oluştur Paketler