Kılavuz APIv0.1.0

Doküman

Türkiye verisi için tek anahtar, tek kredi havuzu: adres, doğrulama, kamu verisi, vergi ve finans, kargo ve e-ticaret, takvim, metin, spor ve araçlar. 9 grupta 36 alan, 135 uç; 89 tanesi ücretsiz. Aynı araçlar MCP olarak da sunulur (POST /mcp). Hatalar her zaman {"hata": "…"} biçimindedir.

Bu sayfa GET /openapi.json şemasından üretildi (OpenAPI 3.1). Kendi istemcini üretmek için aynı dosyayı kullanabilirsin.

İlk istek

Anahtarını al
Kayıt formu ya da POST /v1/kayit. Anahtar bir kez gösterilir; biz yalnız özetini saklarız.

İki değişken tanımla

export KILAVUZ="https://api.kilavuzapi.com"
export KILAVUZ_ANAHTAR="ak_live_…"

Bir adres çözümle

curl -X POST "$KILAVUZ/v1/address/resolve" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"q":"kadikoy istanbul moda cad 14"}'

Kimlik ve kredi

Her istek authorization: Bearer ak_live_… başlığıyla gelir. Bütün uçlar aynı kredi havuzundan harcar: ücretsiz planda ayda 1.000 kredi. Her ucun fiyatı aşağıda kendi başlığının yanında yazar; toplu isteklerde adres ya da IBAN başına düşer. Ücretsiz (anahtarla) yazan uç kredi düşürmez ama anahtar ister; anahtarsız yazan uç anahtarsız çağrılır. Kalan krediyi GET /v1/kullanim ya da panel söyler.

Aynı araçlar uzak MCP olarak da açık: POST /mcp. İstemci kurulumu bağlan sayfasında.

Claude'a bağlan

Claude'u anahtar yapıştırmadan bağlarsın: bağlayıcı seni Kılavuz girişine gönderir, izin verince araçlar açılır. Kredi hesabından düşer; bağlantıyı panelde Bağlı uygulamalardan kesersin.

Bağlayıcı ekle
Claude.ai ya da Claude Desktop'ta Ayarlar → Bağlayıcılar → Özel bağlayıcı ekle.
Adresi yapıştır
```
https://api.kilavuzapi.com/mcp
```
Gir ve izin ver
Bağlan'a basınca Kılavuz giriş sayfası açılır. Google, Apple ya da e-posta koduyla gir, sonra izin ver.

Claude Code'da aynı adresle:

claude mcp add --transport http kilavuz https://api.kilavuzapi.com/mcp

Ardından Claude Code içinde /mcp yazıp girişi tamamla.

Hatalar

Hata her uçta aynı biçimde döner, yanında anlamlı bir HTTP durum kodu:

{ "hata": "geçersiz API anahtarı" }

400: İstek gövdesi eksik ya da hatalı; mesaj hangi alan olduğunu söyler.
401: Anahtar yok, geçersiz ya da iptal edilmiş.
429: Kredi bitti ya da hız sınırı doldu. Varsa Retry-After kaç saniye bekleneceğini söyler.
503: Hizmet geçici olarak kapalı; ödeme uçları sağlayıcı açılana kadar bunu döner.

Toplu CSV

Sipariş ya da müşteri dosyasını tek istekte temizle: POST /v1/address/temizle. Gövde dosyanın kendisidir (multipart değil). Yanıt aynı CSV'dir: senin sütunların olduğu gibi kalır, sonuna ak_ önekli 11 sütun eklenir. Aynı işi panelden dosya seçerek de yapabilirsin.

curl -X POST "$KILAVUZ/v1/address/temizle" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: text/csv" \
  --data-binary @siparisler.csv \
  -D - -o siparisler-temiz.csv

-d değil --data-binary kullan; -d satır sonlarını siler. -D - yanıt başlıklarını ekrana basar: x-adreskit-satir adresi dolu satır sayısı, x-adreskit-kredi düşen kredi, x-adreskit-kodlama dosyanın hangi kodlamayla okunduğu.

Kredi ve sınırlar

Kredi tekil dolu adres başına 1'dir. Dosyada tekrar eden adres bir kez, boş hücre hiç sayılmaz. Dosya en fazla 2,5 MB ve 10.000 veri satırı olabilir; büyüğünü parçalara böl. Dosya ya bütünüyle işlenir ya da kredi düşmez: aşağıdaki hataların hiçbiri kredi yakmaz. Dosya saklanmaz; yalnız kimlik ve adres sütunlarını göndermen yeterli.

Örnek

siparisler.csv

siparis;adres
1001;moda cad 14 kadikoy istanbul
1002;Atatürk Blv. No:5 Kızılay Çankaya Ankara
1003;moda cad 14 kadikoy istanbul
1004;Konak İzmir
1005;

siparisler-temiz.csv

siparis;adres;ak_il;ak_ilce;ak_mahalle;ak_yol;ak_bina_no;ak_daire;ak_enlem;ak_boylam;ak_hassasiyet;ak_guven;ak_durum
1001;moda cad 14 kadikoy istanbul;İstanbul;Kadıköy;;Moda Caddesi;14;;40.985993;29.024957;sokak;0.85;tamam
1002;Atatürk Blv. No:5 Kızılay Çankaya Ankara;Ankara;Çankaya;;Atatürk Bulvarı;5;;39.91933;32.854647;sokak;0.85;tamam
1003;moda cad 14 kadikoy istanbul;İstanbul;Kadıköy;;Moda Caddesi;14;;40.985993;29.024957;sokak;0.85;tamam
1004;Konak İzmir;İzmir;Konak;;;;;38.418474;27.139799;ilce;0.4;kismi
1005;;;;;;;;;;;;bos

Bu dosya için yanıt başlıkları x-adreskit-satir: 4, x-adreskit-kredi: 3 olur: 1001 ile 1003 aynı adres, 1005 boş. Çıktı her zaman UTF-8'dir ve başında BOM vardır ki Excel Türkçe karakterleri doğru açsın. Ayırıcı girdiyle aynı kalır.

Eklenen sütunlar
`ak_il`	İl, resmî yazımıyla
`ak_ilce`	İlçe
`ak_mahalle`	Mahalle; adreste yoksa ya da bulunamazsa boş
`ak_yol`	Cadde, sokak ya da bulvar, tam adıyla
`ak_bina_no`	Kapı numarası
`ak_daire`	Daire
`ak_enlem`	Enlem (WGS84)
`ak_boylam`	Boylam (WGS84)
`ak_hassasiyet`	Koordinatın inceliği: sokak, ilçe (merkez) ya da il (merkez); adresin doğrulanmasından bağımsız
`ak_guven`	0 ile 1 arası güven puanı
`ak_durum`	Satırın özeti; aşağıda

ak_durum değerleri

tamam: İl, ilçe ve yol sicilde bulundu.
kismi: İl ve ilçe bulundu; yol bulunamadı ya da adreste yazmıyor.
yalniz_il: Yalnız il bulundu. Bu satıra elle bak.
cozulemedi: İl bile bulunamadı.
bos: Adres hücresi boş; kredi düşmez.

Seçenekler

Hepsi isteğe bağlı sorgu parametresidir; varsayılanlar çoğu dosyada doğru çalışır.

sutun: Adres sütununun başlık adı ya da 1'den başlayan sırası. Verilmezse adres, address, açık adres, teslimat adresi gibi adlar aranır.
ayirici: auto (varsayılan), ,, ; ya da tab.
kodlama: auto, utf-8 ya da windows-1254. Türkçe Excel'in "CSV" kaydı windows-1254'tür; auto ikisini de tanır.
baslik: 0 verilirse ilk satır veri sayılır; o zaman sutun sıra numarası olmalı.

Hatalar

400: CSV bozuk (mesaj satır numarasını söyler) ya da adres sütunu bulunamadı. İkincisinde yanıtta basliklar da gelir; birini sutun ile seç.
413: Dosya 2,5 MB'ı ya da 10.000 satırı aşıyor.
415: Gövde CSV değil; content-type: text/csv gönder.
429: Kredi yetmiyor; mesaj bu dosyanın kaç kredi gerektirdiğini söyler.
503: Dosya süre sınırında işlenemedi. Daha küçük parçalarla dene.

Adres

Serbest yazılmış adresi çözümle, doğrula, karşılaştır; koordinattan en yakın sokak, iki nokta arası mesafe; form için il, ilçe, mahalle, sokak ve plaka listeleri.

Adres

0–1 kredi

İl, ilçe ve mahalle listeleri ücretsiz; form açılır kutuları için. Sokak tamamlama ilçe içinde arar, mahalleye göre süzmez: sicilde sokak ilçeye bağlı. Mesafe kuş uçuşu; karayolu değeri ×1,3 katsayılı tahmindir, rota değildir. Ters geokod en yakın koordinatlı sokağı döner, mahalle vermez; sonuç yoksa ücretsiz.

POST/v1/address/resolveAdres çözümle ve doğrula
POST/v1/address/parseYalnız ayrıştır (ücretsiz)
GET/v1/address/posta-kodu/{kod}Posta kodundan ilçe (ücretsiz)
GET/v1/address/plaka/{kod}Plaka kodundan il (ücretsiz)
GET/v1/address/iller81 il (ücretsiz)
GET/v1/address/ilcelerİlin ilçeleri (ücretsiz)
GET/v1/address/mahallelerİlçenin mahalle ve köyleri (ücretsiz)
GET/v1/address/sokak-tamamlaSokak adı tamamlama
GET/v1/address/tersTers geokod: koordinattan en yakın sokak
GET/v1/address/mesafeİki nokta arası mesafe (ücretsiz)
POST/v1/address/ayni-miİki adres aynı yer mi
POST/v1/address/temizleToplu adres temizleme (CSV → CSV)

POST/v1/address/resolve

1 kredi

Adres çözümle ve doğrula

Anahtar gerekli

Serbest metin adresi bileşenlerine ayırır, adları sokak sicilinde arar. adresler[] ile toplu (en fazla 1000, adres başına 1 kredi). Koordinat yalnız sokak sicilde koordinatlıysa döner.

İstek gövdesi
Alan	Tip	Açıklama
`q`	`string`
`adresler`	`string[]`	en fazla 1000

Örnek istek

curl -X POST "$KILAVUZ/v1/address/resolve" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"q":"kadikoy istanbul moda cad 14"}'

Yanıtlar

200BaşarılıAdresSonucu ya da object
400q ya da adresler eksik, boş ya da metin olmayan elemanHata
401Anahtar yok ya da geçersizHata
4131000'den fazla adresHata
429Kredi limiti aşıldıHata

Toplu yanıt
`sonuclar`	`AdresSonucu[]`

POST/v1/address/parse

ücretsiz (anahtarla)

Yalnız ayrıştır (ücretsiz)

Anahtar gerekli

Sicile bakmaz, koordinat vermez. Anahtar ister ama kredi düşmez.

İstek gövdesi
Alan	Tip	Açıklama
`q`zorunlu	`string`

Örnek istek

curl -X POST "$KILAVUZ/v1/address/parse" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"q":"ataturk bulv no:12/5 cankaya"}'

Yanıtlar

200BaşarılıAyrisma
400q eksikHata
401Anahtar geçersizHata

GET/v1/address/posta-kodu/{kod}

ücretsiz (anahtarla)

Posta kodundan ilçe (ücretsiz)

Anahtar gerekli

Kodun gözlendiği ilçeler, POI sayısına göre sıralı; kod birden çok ilçeye yayılıyorsa hepsi döner. Kaynak PTT değil: Overture Maps Places (CDLA-Permissive 2.0) işletme adreslerindeki kodlar. Kapsam eksik (yaklaşık 3.600 kod); bulunamayan kod 404. Mahalle düzeyinde eşleme yok.

Parametreler
Ad	Yer	Tip	Açıklama
`kod`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/address/posta-kodu/<kod>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400Kod 5 haneli değilHata
401Anahtar geçersizHata
404Kod kaynakta gözlenmedi (kaynak ve kapsam notuyla)Hata

Yanıt alanları
`kod`	`string`
`ilceler`	`object[]`
`ilceler[].il`	`string`
`ilceler[].ilce`	`string`
`ilceler[].poiSayisi`	`integer`	Kodu bu ilçede yazan işletme sayısı
`kaynak`	`string`
`kapsam`	`string`

GET/v1/address/plaka/{kod}

ücretsiz (anahtarla)

Plaka kodundan il (ücretsiz)

Anahtar gerekli

İl plaka kodu (01–81) → il adı; /v1/address/iller listesinin ters yönü. Kaynak aynı kamu kaydı. 82 ve üstü kodlar il değildir, 422 döner.

Parametreler
Ad	Yer	Tip	Açıklama
`kod`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/address/plaka/<kod>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400Kod 1–2 haneli sayı değilHata
401Anahtar geçersizHata
422Koda karşılık il yokHata

Yanıt alanları
`plaka`	`integer`	Sayı olarak kod (34)
`kod`	`string`	İki haneli yazım ("06")
`il`	`string`
`kaynak`	`string`
`lisans`	`string`

GET/v1/address/iller

ücretsiz (anahtarla)

81 il (ücretsiz)

Anahtar gerekli

Örnek istek

curl "$KILAVUZ/v1/address/iller" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar geçersizHata

Yanıt alanları
`toplam`	`integer`
`iller`	`object[]`
`iller[].plaka`	`integer`
`iller[].ad`	`string`
`kaynak`	`string`
`lisans`	`string`

GET/v1/address/ilceler

ücretsiz (anahtarla)

İlin ilçeleri (ücretsiz)

Anahtar gerekli

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`	Ad ya da plaka

Örnek istek

curl "$KILAVUZ/v1/address/ilceler?il=İzmir" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il eksikHata
401Anahtar geçersizHata
422il bulunamadıHata

Yanıt alanları
`il`	`string`
`plaka`	`integer`
`toplam`	`integer`
`ilceler`	`object[]`
`ilceler[].id`	`integer`
`ilceler[].ad`	`string`
`kaynak`	`string`
`lisans`	`string`

GET/v1/address/mahalleler

ücretsiz (anahtarla)

İlçenin mahalle ve köyleri (ücretsiz)

Anahtar gerekli

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`	Ad ya da plaka
`ilce`zorunlu	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/address/mahalleler?il=İstanbul&ilce=Kadıköy" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il ya da ilce eksikHata
401Anahtar geçersizHata
422il ya da ilçe bulunamadıHata

Yanıt alanları
`il`	`string`
`ilce`	`string`
`toplam`	`integer`
`mahalleler`	`object[]`
`mahalleler[].ad`	`string`
`mahalleler[].tip`	`"mahalle" \| "koy"`
`kaynak`	`string`
`lisans`	`string`

GET/v1/address/sokak-tamamla

1 kredi

Sokak adı tamamlama

Anahtar gerekli

İlçedeki sicil sokaklarından q ile başlayanlar, sonra adının bir sözcüğü q ile başlayanlar; her grupta işlek sokak önce. Türkçe karaktersiz yazılabilir. Mahalleye göre süzmez: sicilde sokak ilçeye bağlı. yollar her yol tipiyle tam ad ("Bağdat Caddesi"). Öneri yoksa kredi düşmez.

Parametreler
Ad	Yer	Tip
`il`zorunlu	sorgu	`string`
`ilce`zorunlu	sorgu	`string`
`q`zorunlu	sorgu	`string`
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/address/sokak-tamamla?il=İstanbul&ilce=Kadıköy&q=bagd&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400q, il ya da ilce eksik; limit aralık dışıHata
401Anahtar yok ya da geçersizHata
422il ya da ilçe bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`string`
`ilce`	`string`
`q`	`string`
`sokaklar`	`object[]`
`sokaklar[].ad`	`string`
`sokaklar[].tipler`	`string[]`
`sokaklar[].yollar`	`string[]`
`kaynak`	`string`
`lisans`	`string`

GET/v1/address/ters

1 kredi

Ters geokod: koordinattan en yakın sokak

Anahtar gerekli

Koordinata en yakın sicil sokağını, ilçesini ve ilini döner. Sokak koordinatı o sokağa adres yazan işletmelerin medyanıdır (kapı numarası değil), bu yüzden uzaklikM sokağın üstündeyken bile birkaç yüz metre olabilir. Arama yarıçapı 25 km (routes/ters.ts AZAMI_YARICAP_KM); içinde sokak yoksa alanlar null döner ve kredi düşmez. Mahalle verilmez (sicilde sokak ilçeye bağlı). Türkiye dışı koordinat 422.

Parametreler
Ad	Yer	Tip	Açıklama
`lat`zorunlu	sorgu	`number`
`lon`zorunlu	sorgu	`number`

Örnek istek

curl "$KILAVUZ/v1/address/ters?lat=40.9812&lon=29.0257" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400lat ya da lon eksik veya aralık dışıHata
401Anahtar yok ya da geçersizHata
422Koordinat Türkiye dışındaHata
429Kredi limiti aşıldıHata

Yanıt alanları
`konum`	`object`
`konum.lat`	`number`
`konum.lon`	`number`
`aramaYaricapiKm`	`number`
`sokak`	`object \| null`
`sokak.ad`	`string`
`sokak.tipler`	`string[]`
`sokak.yollar`	`string[]`
`sokak.lat`	`number`
`sokak.lon`	`number`
`sokak.poiSayisi`	`integer`	Koordinatın kaç işletmeden türediği
`il`	`string \| null`
`plaka`	`integer \| null`
`ilce`	`string \| null`
`mahalle`	`null`	Sicilde sokak-mahalle bağı yok; her zaman null
`uzaklikM`	`integer \| null`
`kaynak`	`string`
`lisans`	`string`
`not`	`string`

GET/v1/address/mesafe

ücretsiz (anahtarla)

İki nokta arası mesafe (ücretsiz)

Anahtar gerekli

a ve b il adı, plaka ya da "enlem,boylam" olabilir. Kuş uçuşu mesafe haversine ile; karayolu tahmini kuş uçuşunun 1,3 katı, kaba bir yaklaşıklık — rota servisi değildir. İl verilirse merkez koordinatı Overture POI medyanından gelir.

Parametreler
Ad	Yer	Tip	Açıklama
`a`zorunlu	sorgu	`string`
`b`zorunlu	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/address/mesafe?a=İstanbul&b=35" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400a ya da b eksik veya koordinat biçimi hatalıHata
401Anahtar geçersizHata
422il bulunamadıHata

Yanıt alanları
`a`	`MesafeUcu`
`b`	`MesafeUcu`
`kusUcusuKm`	`number`
`karayoluTahminiKm`	`number`
`katsayi`	`number`
`kaynak`	`string`
`not`	`string`

POST/v1/address/ayni-mi

1 kredi

İki adres aynı yer mi

Anahtar gerekli

İki adres çözümlenip bileşen bileşen karşılaştırılır. karar: ayni_adres (il, ilçe, yol, bina no aynı; daire aynı ya da ikisinde de yok), ayni_bina (daire farklı ya da birinde yok), ayni_sokak, farkli, belirsiz (ilçe ya da yol çözülemedi). Mahalle karara girmez. benzerlik 0–1: üst bileşen farklıysa alttakiler sayılmaz.

İstek gövdesi
Alan	Tip	Açıklama
`a`zorunlu	`string`	en fazla 1000 karakter
`b`zorunlu	`string`	en fazla 1000 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/address/ayni-mi" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

200Başarılı
400a ya da b eksikHata
401Anahtar yok ya da geçersizHata
413adres 1000 karakteri aşıyorHata
429Kredi limiti aşıldıHata

Yanıt alanları
`karar`	`"ayni_adres" \| "ayni_bina" \| "ayni_sokak" \| "farkli" \| "belirsiz"`
`benzerlik`	`number`
`bilesenler`	`object`	ayni; farkli; eksik (yalnız birinde var); yok (ikisinde de yok)
`bilesenler.il`	`"ayni" \| "farkli" \| "eksik" \| "yok"`
`bilesenler.ilce`	`"ayni" \| "farkli" \| "eksik" \| "yok"`
`bilesenler.mahalle`	`"ayni" \| "farkli" \| "eksik" \| "yok"`
`bilesenler.yol`	`"ayni" \| "farkli" \| "eksik" \| "yok"`
`bilesenler.binaNo`	`"ayni" \| "farkli" \| "eksik" \| "yok"`
`bilesenler.daire`	`"ayni" \| "farkli" \| "eksik" \| "yok"`
`farklar`	`string[]`
`a`	`object`
`b`	`object`

POST/v1/address/temizle

1 kredi

Toplu adres temizleme (CSV → CSV)

Anahtar gerekli

Gövde ham CSV (multipart değil). Aynı CSV döner: özgün sütunlar olduğu gibi, sona ak_il, ak_ilce, ak_mahalle, ak_yol, ak_bina_no, ak_daire, ak_enlem, ak_boylam, ak_hassasiyet, ak_guven, ak_durum (tamam: il+ilçe+yol sicilde | kismi: il+ilçe | yalniz_il | cozulemedi | bos). Kredi **tekil dolu adres** başına 1; dosya içi tekrar ve boş hücre ücretsiz. Dosya ya bütünüyle işlenir ya da kredi düşmez. En fazla 2,5 MB ve 10.000 veri satırı; büyük dosyayı bölün. Dosya saklanmaz; yalnız kimlik ve adres sütunlarını göndermeniz yeterli.

Parametreler
Ad	Yer	Tip	Açıklama
`sutun`	sorgu	`string`	Adres sütununun başlık adı ya da 1'den başlayan sırası. Verilmezse `adres`, `address`, `açık adres`, `teslimat adresi`… aranır.
`ayirici`	sorgu	`"auto" \| "," \| ";" \| "tab"`
`baslik`	sorgu	`"1" \| "0"`	0: ilk satır veri; `sutun` sıra numarası olmalı
`kodlama`	sorgu	`"auto" \| "utf-8" \| "windows-1254"`	TR Excel "CSV" kaydı windows-1254; auto ikisini de tanır. Çıktı her zaman UTF-8 (BOM ile).

Örnek istek

curl -X POST "$KILAVUZ/v1/address/temizle" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: text/csv" \
  --data-binary @siparisler.csv \
  -o siparisler-temiz.csv

Yanıtlar

200Temizlenmiş CSV
400CSV bozuk (satır numarasıyla) ya da adres sütunu bulunamadıHata
401Anahtar yok ya da geçersizHata
4132,5 MB ya da 10.000 satır aşıldıHata
415Gövde CSV değilHata
429Kredi limiti aşıldıHata
503Süre sınırı aşıldı; kredi düşülmediHata

Doğrulama

Numaraların ve barkodların biçim ve algoritma kontrolü; resmî bir kayda sorulmaz.

IBAN

0–1 kredi

POST/v1/iban/dogrulaIBAN doğrula, bankayı çöz
GET/v1/iban/bankalarTCMB banka kodu listesi (ücretsiz)

POST/v1/iban/dogrula

1 kredi

IBAN doğrula, bankayı çöz

Anahtar gerekli

ISO 13616 mod-97. ibanlar[] ile toplu (en fazla 1000, IBAN başına 1 kredi).

İstek gövdesi
Alan	Tip	Açıklama
`iban`	`string`
`ibanlar`	`string[]`	en fazla 1000

Örnek istek

curl -X POST "$KILAVUZ/v1/iban/dogrula" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"iban":"TR33 0006 1005 1978 6457 8413 26"}'

Yanıtlar

200BaşarılıIbanSonucu ya da object
400iban ya da ibanlar eksik, boş ya da metin olmayan elemanHata
401Anahtar yok ya da geçersizHata
4131000'den fazla IBANHata
429Kredi limiti aşıldıHata

Toplu yanıt
`sonuclar`	`IbanSonucu[]`
`ozet`	`object`
`ozet.toplam`	`integer`
`ozet.gecerli`	`integer`

GET/v1/iban/bankalar

ücretsiz (anahtarla)

TCMB banka kodu listesi (ücretsiz)

Anahtar gerekli

Örnek istek

curl "$KILAVUZ/v1/iban/bankalar" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar geçersizHata

Alan kodu

ücretsiz (anahtarla)

BTK’nın tahsisli numaralar raporundan. GSM öneki numaranın ilk tahsis edildiği işletmeciyi gösterir; numara taşınmışsa bugünkü işletmeci farklı olabilir.

GET/v1/telefon/alan-kodu/{kod}

ücretsiz (anahtarla)

Alan kodundan il, GSM önekinden işletmeci (ücretsiz)

Anahtar gerekli

Üç haneli coğrafi alan kodunu ile çevirir (0212 → İstanbul Avrupa Yakası, 0216 → Anadolu Yakası) ya da GSM önekinin ilk tahsis edildiği işletmeciyi söyler (0532 → Turkcell). Numara taşınabilirliği nedeniyle GSM önekinin numaranın bugünkü işletmecisini göstermediği yanıtta yazar. "+90 212", "(0212)", "212" kabul.

Parametreler
Ad	Yer	Tip	Açıklama
`kod`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/telefon/alan-kodu/<kod>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
404alan kodu tanınmadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`"cografi" \| "gsm"`
`kod`	`string`
`bolum`	`string`	Yalnız İstanbul
`il`	`object`
`il.plaka`	`integer`
`il.ad`	`string`
`il.bolge`	`string`
`alanKodlari`	`object[]`
`alanKodlari[].kod`	`string`
`alanKodlari[].bolum`	`string`
`operator`	`string`	Yalnız GSM
`kullanim`	`"mobil" \| "m2m" \| "yabanci"`	Yalnız GSM
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`not`	`string`

Barkod

0–1 kredi

EAN-13, EAN-8 ve UPC-A kontrol hanesi. GS1 öneki numaranın hangi GS1 üye kuruluşundan alındığını söyler; ürünün nerede üretildiğini söylemez.

POST/v1/urun/kdv-oraniÜrün adından KDV oranı (1/10/20) ve GTİP tahmini
GET/v1/urun/barkod/{ean}Barkod sağlaması ve GS1 öneki (ücretsiz)
GET/v1/urun/guvensizGüvensiz ürün bildirimleri (GÜBİS)

POST/v1/urun/kdv-orani

1 kredi

Ürün adından KDV oranı (1/10/20) ve GTİP tahmini

Anahtar gerekli

Ürün adını 2007/13033 BKK eki (I) ve (II) sayılı listelerden yazılmış ölçüte göre %1, %10 ya da %20'ye sınıflandırır ve gömülü TGTC 2026 cetvelinden çıkan on iki haneli adaylar arasından GTİP'i seçer (TypeSafe Jev, tek istek). Oran güveni 0,8'in altındaysa belirsiz: true; GTİP güveni 0,6 altıysa gtip.belirsiz: true, 0,3 altıysa ya da uygun aday yoksa gtip: null. GTİP fasılı oranla çelişirse (gıda fasılı ama %20 gibi) ikisi de belirsiz, gerekçe celiski'de. **Tahmindir, vergi ya da gümrük tavsiyesi değildir.** Tek ürün urun ya da en çok 100 ürün urunler; ürün başına 1 kredi, sınıflandırılamayan ürün kredisiz. Sınıflandırıcıya ulaşılamazsa 503 (kredi düşmez). Yalnız ürün adı gönderin: e-posta ya da 10+ haneli numara içeren girdi 400. Ürün adı loglanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`urun`	`string`	en fazla 200 karakter
`urunler`	`string[]`	en fazla 100

Örnek istek

curl -X POST "$KILAVUZ/v1/urun/kdv-orani" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"urun":"Organik süzme bal 850 g"}'

Yanıtlar

200Başarılı
400urun/urunler eksik ya da ürün adı değilHata
401Anahtar yok ya da geçersizHata
413100'den fazla ürünHata
429Kredi limiti aşıldıHata
503Sınıflandırıcı kapalı ya da ulaşılamıyor; kredi düşülmediHata

Yanıt alanları
`urun`	`string`
`kdvOrani`	`1 \| 10 \| 20`
`guven`	`number`
`belirsiz`	`boolean`	Oran güveni 0,8 altı ya da GTİP fasılıyla çelişiyor: mali müşavire danışın
`olasiliklar`	`object`
`olasiliklar.1`	`number`
`olasiliklar.10`	`number`
`olasiliklar.20`	`number`
`gtip`	`object \| null`	Ürün adından GTİP (TGTC 2026) tahmini: cetvelden çıkan adaylardan seçilen on iki haneli satır. Aday yoksa, sınıflandırıcı "hiçbiri" dediyse ya da güveni 0,3 altındaysa null. Gümrük beyanında kullanılmaz.
`gtip.kod`	`string`
`gtip.kodNoktali`	`string`
`gtip.tanim`	`string`	Pozisyondan satıra tanımlar, " › " ile
`gtip.guven`	`number`
`gtip.belirsiz`	`boolean`	Güven 0,6 altı ya da oranla çelişiyor
`celiski`	`string \| null`	GTİP fasılı ile oran çelişiyorsa kısa gerekçe (ör. gıda fasılı ama %20)
`onbellek`	`boolean`
`sonuclar`	`object[]`	Yalnız toplu istekte, girdi sırasıyla
`sonuclar[].urun`	`string`
`sonuclar[].kdvOrani`	`1 \| 10 \| 20`
`sonuclar[].guven`	`number`
`sonuclar[].belirsiz`	`boolean`	Oran güveni 0,8 altı ya da GTİP fasılıyla çelişiyor: mali müşavire danışın
`sonuclar[].olasiliklar`	`object`
`sonuclar[].gtip`	`object \| null`	Ürün adından GTİP (TGTC 2026) tahmini: cetvelden çıkan adaylardan seçilen on iki haneli satır. Aday yoksa, sınıflandırıcı "hiçbiri" dediyse ya da güveni 0,3 altındaysa null. Gümrük beyanında kullanılmaz.
`sonuclar[].celiski`	`string \| null`	GTİP fasılı ile oran çelişiyorsa kısa gerekçe (ör. gıda fasılı ama %20)
`sonuclar[].onbellek`	`boolean`
`sonuclar[].hata`	`string`	Yalnız toplu yanıtta, sınıflandırılamayan ürün (kredisiz)
`ozet`	`object`
`ozet.toplam`	`integer`
`ozet.basarili`	`integer`
`ozet.belirsiz`	`integer`
`kaynak`	`string`
`yontem`	`string`
`not`	`string`
`guncelleme`	`string`

GET/v1/urun/barkod/{ean}

ücretsiz (anahtarla)

Barkod sağlaması ve GS1 öneki (ücretsiz)

Anahtar gerekli

EAN-13, EAN-8 ve UPC-A kontrol hanesini doğrular; UPC-A'yı 13 haneli karşılığına çevirir ve ilk üç haneden öneki tahsis eden GS1 üye kuruluşunu söyler (868–869 = GS1 Türkiye). Boşluk ve tire yok sayılır. Önek ürünün **üretim yerini göstermez**, numarayı veren kuruluşu gösterir; yanıttaki not bunu taşır. Kontrol hanesi tutmayan barkod 200 + gecerli: false (beklenen hane ile) döner; harf ya da geçersiz uzunluk 400. Ağ isteği yok, tablo gömülü. GÜBİS güvensiz ürün tablosu varsa guvensizBildirim eklenir (bildirimde yazan barkoda göre; ayrıntı GET /v1/urun/guvensiz); tablo yoksa alan hiç gelmez.

Parametreler
Ad	Yer	Tip	Açıklama
`ean`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/urun/barkod/<ean>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400Barkod rakam dışı karakter içeriyor ya da uzunluk 8/12/13 değilHata
401Anahtar geçersizHata

Yanıt alanları
`gecerli`	`boolean`
`barkod`	`string`
`tur`	`"ean13" \| "ean8" \| "upca"`
`ean13`	`string`
`onek`	`string \| null`	İlk üç hane (EAN-8'de yok)
`ulke`	`string \| null`	Öneki tahsis eden GS1 üye kuruluşu
`turkiye`	`boolean`
`kontrolHanesi`	`object`
`kontrolHanesi.verilen`	`string`
`kontrolHanesi.beklenen`	`string`
`hata`	`string \| null`	Yalnız gecerli=false iken: kontrol_basamagi
`aciklama`	`string \| null`
`not`	`string`	Önek yorumunun sınırı; kullanıcıya iletin
`guvensizBildirim`	`object`	GÜBİS'te bu barkodu anan güvensiz ürün bildirimi var mı (yalnız tablo varken)
`guvensizBildirim.var`	`boolean`
`guvensizBildirim.bildirimler`	`object[]`
`guvensizBildirim.kaynak`	`string`
`guvensizBildirim.ayrinti`	`string`	Ayrıntılı sorgu yolu

GET/v1/urun/guvensiz

1 kredi

Güvensiz ürün bildirimleri (GÜBİS)

Anahtar gerekli

Ticaret Bakanlığı Güvensiz Ürün Bilgi Sistemi'ndeki bildirimler (2018–, ~1.000): ürün, marka, model, barkod, menşe, risk, güvensizlik nedeni, alınan önlem (toplatma, piyasaya arz yasağı…) ve mevzuat. Günde iki kez çekilir, istek anında kaynağa gidilmez. Firma adı ve adresi verilmez (şahıs ithalatçıda kişisel veri). Barkod yalnız bildirimde yazıyorsa eşleşir; çoğu bildirimde yok, marka/ara ile de sorun. marka, kategori, ara sözcükleri ürün, marka, model, etiket adı ve kategoride aranır (hepsi geçmeli). En yeni bildirim önce. Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`barkod`	sorgu	`string`	8–14 hane
`marka`	sorgu	`string`
`kategori`	sorgu	`string`
`ara`	sorgu	`string`
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/urun/guvensiz?barkod=…&marka=…&kategori=oyuncak&ara=peluş anahtarlık&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400filtre yok, barkod ya da limit geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`bildirimler`	`object[]`
`bildirimler[].rid`	`integer`	GÜBİS kayıt kimliği
`bildirimler[].bildirimNo`	`string`
`bildirimler[].bildirimTarihi`	`string (date)`
`bildirimler[].kurum`	`string \| null`
`bildirimler[].kategori`	`string \| null`
`bildirimler[].urunGrubu`	`string \| null`
`bildirimler[].urun`	`string`
`bildirimler[].marka`	`string \| null`
`bildirimler[].model`	`string \| null`
`bildirimler[].etiketAdi`	`string \| null`
`bildirimler[].barkodlar`	`string[]`
`bildirimler[].mensei`	`string \| null`
`bildirimler[].riskler`	`string \| null`
`bildirimler[].neden`	`string \| null`
`bildirimler[].onlem`	`string \| null`
`bildirimler[].onlemTarihi`	`string \| null (date)`
`bildirimler[].mevzuat`	`string \| null`
`bildirimler[].url`	`string`
`bildirimler[].detayli`	`boolean`	Ayrıntı sayfası okunduysa true; değilse yalnız RSS alanları dolu
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

TCKN, VKN, telefon

0–1 kredi

Yalnız algoritma kontrolü; resmî bir kayda sorulmaz. Gönderilen numara veritabanına yazılmaz, TCKN yanıtta dönmez.

POST/v1/dogrula/tcknTCKN doğrula
POST/v1/dogrula/vknVKN doğrula
POST/v1/dogrula/telefonTelefon doğrula ve biçimle
POST/v1/dogrula/kartÖdeme kartı numarası doğrula (ücretsiz)

POST/v1/dogrula/tckn

1 kredi

TCKN doğrula

Anahtar gerekli

11 hane, ilk hane ≠ 0, iki kontrol hanesi. Numara yanıtta dönmez. tcknler[] ile toplu (en fazla 1000, öğe başına 1 kredi).

İstek gövdesi
Alan	Tip	Açıklama
`tckn`	`string`
`tcknler`	`string[]`	en fazla 1000

Örnek istek

curl -X POST "$KILAVUZ/v1/dogrula/tckn" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"tckn":"10000000146"}'

Yanıtlar

200BaşarılıKimlikSonucu ya da object
400tckn ya da tcknler eksikHata
401Anahtar yok ya da geçersizHata
4131000'den fazla elemanHata
429Kredi limiti aşıldıHata

Toplu yanıt
`sonuclar`	`KimlikSonucu[]`	Girdi sırasıyla
`ozet`	`object`
`ozet.toplam`	`integer`
`ozet.gecerli`	`integer`

POST/v1/dogrula/vkn

1 kredi

VKN doğrula

Anahtar gerekli

GİB kontrol hanesi. 11 hane gelirse şahıs şirketi (VKN = TCKN) sayılır. vknler[] ile toplu (en fazla 1000, öğe başına 1 kredi).

İstek gövdesi
Alan	Tip	Açıklama
`vkn`	`string`
`vknler`	`string[]`	en fazla 1000

Örnek istek

curl -X POST "$KILAVUZ/v1/dogrula/vkn" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"vkn":"1234567890"}'

Yanıtlar

200BaşarılıKimlikSonucu ya da object
400vkn ya da vknler eksikHata
401Anahtar yok ya da geçersizHata
4131000'den fazla elemanHata
429Kredi limiti aşıldıHata

Toplu yanıt
`sonuclar`	`KimlikSonucu[]`	Girdi sırasıyla
`ozet`	`object`
`ozet.toplam`	`integer`
`ozet.gecerli`	`integer`

POST/v1/dogrula/telefon

1 kredi

Telefon doğrula ve biçimle

Anahtar gerekli

BTK numara planı; E.164, tür ve sabit hatta il. Operatör verilmez (numara taşıma). telefonlar[] ile toplu (en fazla 1000, öğe başına 1 kredi).

İstek gövdesi
Alan	Tip	Açıklama
`telefon`	`string`
`telefonlar`	`string[]`	en fazla 1000

Örnek istek

curl -X POST "$KILAVUZ/v1/dogrula/telefon" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"telefon":"0532 123 45 67"}'

Yanıtlar

200BaşarılıTelefonSonucu ya da object
400telefon ya da telefonlar eksikHata
401Anahtar yok ya da geçersizHata
4131000'den fazla elemanHata
429Kredi limiti aşıldıHata

Toplu yanıt
`sonuclar`	`TelefonSonucu[]`	Girdi sırasıyla
`ozet`	`object`
`ozet.toplam`	`integer`
`ozet.gecerli`	`integer`

POST/v1/dogrula/kart

ücretsiz (anahtarla)

Ödeme kartı numarası doğrula (ücretsiz)

Anahtar gerekli

Luhn sağlaması, IIN aralığından şema (Visa, Mastercard, Troy, Amex…) ve şemaya göre uzunluk. Banka (BIN) verilmez: ticari kullanıma açık güvenilir liste yok. Tam numara saklanmaz, loglanmaz ve yanıtta dönmez; yalnız maskeli (ilk 6 + son 4). Kartın var olduğunu göstermez. kartlar[] ile toplu (en fazla 1000).

İstek gövdesi
Alan	Tip	Açıklama
`kart`	`string`
`kartlar`	`string[]`	en fazla 1000

Örnek istek

curl -X POST "$KILAVUZ/v1/dogrula/kart" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"kart":"4111 1111 1111 1111"}'

Yanıtlar

200Başarılıobject ya da object
400kart ya da kartlar eksikHata
401Anahtar yok ya da geçersizHata
4131000'den fazla elemanHata
429Kredi limiti aşıldıHata

Toplu yanıt
`gecerli`	`boolean`
`maskeli`	`string`	İlk 6 + son 4 (16 haneden kısada baştan daha az); tam numara dönmez
`uzunluk`	`integer`
`luhn`	`boolean`
`sema`	`"visa" \| "mastercard" \| "amex" \| "troy" \| "discover" \| "unionpay" \| "jcb" \| "diners" \| "maestro" \| "mir" \| "uatp" \| null`
`semaAdi`	`string \| null`
`olasiSemalar`	`string[]`
`semaUzunluguUygun`	`boolean \| null`
`hata`	`"bos" \| "gecersiz_karakter" \| "uzunluk" \| "luhn" \| "sema_uzunlugu"`
`aciklama`	`string`
`not`	`string`

Toplu yanıt
`sonuclar`	`object[]`	Girdi sırasıyla
`sonuclar[].gecerli`	`boolean`
`sonuclar[].maskeli`	`string`	İlk 6 + son 4 (16 haneden kısada baştan daha az); tam numara dönmez
`sonuclar[].uzunluk`	`integer`
`sonuclar[].luhn`	`boolean`
`sonuclar[].sema`	`"visa" \| "mastercard" \| "amex" \| "troy" \| "discover" \| "unionpay" \| "jcb" \| "diners" \| "maestro" \| "mir" \| "uatp" \| null`
`sonuclar[].semaAdi`	`string \| null`
`sonuclar[].olasiSemalar`	`string[]`
`sonuclar[].semaUzunluguUygun`	`boolean \| null`
`sonuclar[].hata`	`"bos" \| "gecersiz_karakter" \| "uzunluk" \| "luhn" \| "sema_uzunlugu"`
`sonuclar[].aciklama`	`string`
`sonuclar[].not`	`string`
`ozet`	`object`
`ozet.toplam`	`integer`
`ozet.gecerli`	`integer`

Kamu verisi

Kamu kurumlarının ve meslek odalarının yayımladığı veri: günlük nöbet, fiyat, baraj ve hava durumundan İstanbul trafiğine, il kartı ve nüfusa. Yanıtta kaynağı ve güncelleme tarihi. Kaynak ve kaldırma politikası: /kaynaklar.

Nöbetçi eczane

1 kredi

Kapsam 77 il: Adana, Adıyaman, Afyonkarahisar, Ağrı, Aksaray, Ankara, Antalya, Ardahan, Artvin, Aydın, Balıkesir, Bartın, Batman, Bayburt, Bingöl, Bitlis, Bolu, Burdur, Bursa, Çanakkale, Çankırı, Çorum, Denizli, Diyarbakır, Düzce, Edirne, Elazığ, Erzincan, Erzurum, Eskişehir, Gaziantep, Giresun, Gümüşhane, Hakkari, Hatay, Iğdır, Isparta, İstanbul, İzmir, Kahramanmaraş, Karabük, Karaman, Kars, Kastamonu, Kayseri, Kırıkkale, Kırklareli, Kırşehir, Kocaeli, Konya, Kütahya, Malatya, Manisa, Mardin, Mersin, Muğla, Muş, Nevşehir, Niğde, Ordu, Osmaniye, Sakarya, Samsun, Siirt, Sinop, Sivas, Şanlıurfa, Şırnak, Tekirdağ, Tokat, Trabzon, Tunceli, Uşak, Van, Yalova, Yozgat, Zonguldak; her ilin kaynağı /kaynaklar sayfasında. Eczacı adı, sicil numarası ve cep numarası alınmaz; telefon yalnız iş yeri hattıdır.

GET/v1/eczane/nobetciNöbetçi eczaneler
GET/v1/eczane/nobetci/yakinKonuma en yakın nöbetçi eczaneler

GET/v1/eczane/nobetci

1 kredi

Nöbetçi eczaneler

Anahtar gerekli

İlin (isteğe bağlı ilçenin) en son yayımlanan nöbet listesi. Veri kaynaktan günde iki kez çekilir, istek anında kaynağa gidilmez; son başarılı çekim kaynağın tazelik süresinden eskiyse bayat: true. Eczacı adı yok; ad tabeladaki unvan, telefon sabit iş yeri hattı (cep numarası verilmez). İlçe/mahalle referans veriyle belirlenir, bulunamazsa ilçe null. Kapsam: 77 il (Kilis, Rize, Amasya, Bilecik yok). Liste boşsa kredi düşmez. Kapsam dışı il 422 ve kapsam listesi.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`
`ilce`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/eczane/nobetci?il=İzmir&ilce=Bornova" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il eksikHata
401Anahtar yok ya da geçersizHata
422Bu il için kaynak yok
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`string \| null`
`ilce`	`string \| null`
`nobetTarihi`	`string \| null`
`eczaneler`	`object[]`
`eczaneler[].ad`	`string`
`eczaneler[].ilce`	`string \| null`
`eczaneler[].mahalle`	`string \| null`
`eczaneler[].adres`	`string`
`eczaneler[].telefon`	`string \| null`
`eczaneler[].lat`	`number \| null`
`eczaneler[].lon`	`number \| null`
`eczaneler[].nobetTuru`	`string \| null`
`eczaneler[].nobetBaslangic`	`string \| null`	ISO 8601; kaynak saat vermiyorsa null
`eczaneler[].nobetBitis`	`string \| null`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/eczane/nobetci/yakin

1 kredi

Konuma en yakın nöbetçi eczaneler

Anahtar gerekli

Koordinatın düştüğü ilin en son nöbet listesini kuş uçuşu uzaklığa göre sıralar (yaricap içinde, en çok limit). İl, en yakın koordinatlı sokağın ilçesinden bulunur (25 km içinde yoksa liste boş); yalnız o ilin nöbetçileri sıralanır. Eczanenin koordinatı yoksa ilçe merkezine düşülür (konumKaynagi: "ilce_merkezi", kaba tahmin); mahalle merkezi yok. Her eczanede son30GunNobet: son 30 günde kaç ayrı gün nöbetçiydi (gecmis.veriGunu 30'dan küçükse eksik dönem). Eczacı adı ve cep telefonu yok. Liste boşsa kredi düşmez. Konumun ili kapsam dışıysa 422 ve kapsam.

Parametreler
Ad	Yer	Tip	Açıklama
`lat`zorunlu	sorgu	`number`
`lon`zorunlu	sorgu	`number`
`yaricap`	sorgu	`number`	km
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/eczane/nobetci/yakin?lat=38.4622&lon=27.2167&yaricap=…&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400lat/lon eksik ya da yaricap/limit geçersizHata
401Anahtar yok ya da geçersizHata
422Koordinat Türkiye dışında ya da ili kapsam dışı
429Kredi limiti aşıldıHata

Yanıt alanları
`konum`	`object`
`konum.lat`	`number`
`konum.lon`	`number`
`il`	`string \| null`	Konumun düştüğü il; bulunamazsa null
`yaricapKm`	`number`
`nobetTarihi`	`string \| null`
`eczaneler`	`object[]`	Uzaklığa göre artan
`eczaneler[].ad`	`string`
`eczaneler[].ilce`	`string \| null`
`eczaneler[].mahalle`	`string \| null`
`eczaneler[].adres`	`string`
`eczaneler[].telefon`	`string \| null`
`eczaneler[].lat`	`number \| null`
`eczaneler[].lon`	`number \| null`
`eczaneler[].konumKaynagi`	`"eczane" \| "ilce_merkezi"`	Uzaklığın hesaplandığı nokta
`eczaneler[].uzaklikKm`	`number`	Kuş uçuşu
`eczaneler[].nobetTuru`	`string \| null`
`eczaneler[].nobetBaslangic`	`string \| null`
`eczaneler[].nobetBitis`	`string \| null`
`eczaneler[].son30GunNobet`	`integer \| null`	Son 30 günde nöbetçi olduğu gün sayısı
`disarida`	`object`
`disarida.yaricapDisi`	`integer`
`disarida.konumsuz`	`integer`	Ne koordinatı ne ilçe merkezi olan, sıralanamayan eczane
`gecmis`	`object`
`gecmis.gun`	`integer`
`gecmis.veriGunu`	`integer`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

Akaryakıt

1 kredi

EPDK Bildirim Portalı bayi fiyatları. Birim kaynakta yazmıyor; benzin ve motorinde TL/litre ile uyumlu. İl/ürün ortancasından %25'ten fazla sapan fiyat `supheli` işaretlenir, özete katılmaz.

GET/v1/akaryakit/fiyat

1 kredi

Akaryakıt bayi fiyatları (EPDK)

Anahtar gerekli

İlin marka ve ürün bazında güncel bayi fiyatları ve ürün başına en düşük/ortalama/en yüksek. Kaynak EPDK Bildirim Portalı raporu; günde iki kez çekilir, istek anında EPDK'ya gidilmez. Her fiyatın tarihi son bildirildiği gün. İstanbul Anadolu ve Avrupa diye iki bölge (bolge). 81 il. Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`
`urun`	sorgu	`string`	Ürün adında geçen metin (Türkçe karaktersiz de olur)
`marka`	sorgu	`string`
`bolge`	sorgu	`"anadolu" \| "avrupa"`	Yalnız İstanbul

Örnek istek

curl "$KILAVUZ/v1/akaryakit/fiyat?il=Ankara&urun=motorin&marka=opet&bolge=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il eksikHata
401Anahtar yok ya da geçersizHata
422il bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`string`
`fiyatlar`	`object[]`
`fiyatlar[].bolge`	`string \| null`
`fiyatlar[].marka`	`string`
`fiyatlar[].urun`	`string`
`fiyatlar[].fiyat`	`number`
`fiyatlar[].tarih`	`string`	Fiyatın son bildirildiği gün (YYYY-AA-GG)
`fiyatlar[].supheli`	`boolean`	İl/ürün ortancasından %25'ten fazla sapıyor (kaynaktaki olası hatalı bildirim); özete katılmaz
`ozet`	`object[]`
`ozet[].urun`	`string`
`ozet[].enDusuk`	`number`
`ozet[].ortalama`	`number`
`ozet[].enYuksek`	`number`
`ozet[].markaSayisi`	`integer`
`ozet[].supheliSayisi`	`integer`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

Hal fiyatı

1 kredi

Ticaret Bakanlığı Hal Kayıt Sistemi günlük bülteni; Türkiye geneli, il ayrımı yok. Kaynak hatalı değer olabileceğini kendisi yazıyor; düşük hacimli satırlar uç değer verebilir, süzülmez.

GET/v1/hal/fiyat

1 kredi

Toptancı hal fiyat bülteni (Hal Kayıt Sistemi)

Anahtar gerekli

Türkiye geneli sebze-meyve toptancı hal ortalama fiyatları: ürün, cins, tür (konvansiyonel/iyi tarım/organik), fiyat (TL / birim), işlem hacmi. Kaynak Ticaret Bakanlığı Hal Kayıt Sistemi günlük bülteni; günde iki kez çekilir, geçmiş bültenler tutulur. tarih verilmezse en yeni bülten. Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`urun`	sorgu	`string`	Ürün ya da cins adında geçen metin (Türkçe karaktersiz de olur)
`tur`	sorgu	`"konvansiyonel" \| "iyi-tarim" \| "organik"`
`tarih`	sorgu	`string (date)`	Bülten günü (YYYY-AA-GG)

Örnek istek

curl "$KILAVUZ/v1/hal/fiyat?urun=domates&tur=…&tarih=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tur ya da tarih geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`bultenTarihi`	`string \| null`	Bülten günü
`veriTarihi`	`string \| null`	Bültenin kullandığı verinin günü (çoğunlukla önceki iş günü)
`urunler`	`object[]`
`urunler[].urun`	`string`
`urunler[].cins`	`string`
`urunler[].tur`	`string`
`urunler[].fiyat`	`number`	Ortalama fiyat, TL / birim
`urunler[].hacim`	`number`	İşlem hacmi, birim cinsinden
`urunler[].birim`	`string`	Kg, Adet, Bağ
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

İstanbul (İBB açık veri)

0–1 kredi

İBB Açık Veri Portalı, İBB Açık Veri Lisansı 1.0: ticari kullanım serbest, atıf zorunlu; atıf metni her yanıtın `atif` alanında. İBB bu hizmeti onaylamaz ya da desteklemez. Trafik, otopark, hava kalitesi ve metro istek anında, kısa önbellekle; kaynak düşerse eski veri `bayat: true`. Hava kalitesi ölçümleri ham veridir. Raylı istasyon, Wi-Fi, İstanbulkart, itfaiye ve şarj noktaları koda gömülü, ücretsiz.

GET/v1/ibb/trafikİstanbul anlık trafik indeksi (İBB)
GET/v1/ibb/otoparkİSPARK otopark doluluğu
GET/v1/ibb/otopark/{id}İSPARK otopark ayrıntısı (tarife)
GET/v1/ibb/hava/istasyonlarİBB hava kalitesi istasyonları (ücretsiz)
GET/v1/ibb/havaİstanbul hava kalitesi ölçümleri
GET/v1/ibb/metro/durumMetro İstanbul hat aksaklıkları
GET/v1/ibb/noktaİstanbul nokta verisi (ücretsiz)

GET/v1/ibb/trafik

1 kredi

İstanbul anlık trafik indeksi (İBB)

Anahtar gerekli

İBB Ulaşım Yönetim Merkezi'nin İstanbul geneli trafik yoğunluk indeksi (0–100) ve yaka indeksleri. Veri istek anında api.ibb.gov.tr'den, en çok 1 dakika önbellekli; gecmis ile son 24 saate kadar 5 dakikalık seri. İBB yanıt vermezken 30 dakikaya kadar eski veri bayat: true, hiç veri yoksa 503 (kredisiz).

Parametreler
Ad	Yer	Tip	Açıklama
`gecmis`	sorgu	`integer`	Kaç saatlik geçmiş

Örnek istek

curl "$KILAVUZ/v1/ibb/trafik?gecmis=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400gecmis 0–24 olmalıHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata
503İBB yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`indeks`	`number`
`anadolu`	`number \| null`
`avrupa`	`number \| null`
`gecmis`	`object[]`
`gecmis[].zaman`	`string`	Türkiye saati (+03:00)
`gecmis[].indeks`	`number`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`lisansUrl`	`string`
`atif`	`string`	İBB Açık Veri Lisansı gereği gösterilmesi gereken atıf metni
`guncelleme`	`string`	İBB'den son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/ibb/otopark

1 kredi

İSPARK otopark doluluğu

Anahtar gerekli

İSPARK otoparklarının anlık boş yer sayısı ve doluluğu. lat/lon verilirse yarıçap içindekiler yakından uzağa (mesafeM). İstek anında İBB'den, 1 dakika önbellek. Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`lat`	sorgu	`number`
`lon`	sorgu	`number`
`yaricap`	sorgu	`integer`	Metre
`ilce`	sorgu	`string`
`ara`	sorgu	`string`	Otopark adındaki sözcükler
`tur`	sorgu	`"acik" \| "kapali" \| "yol_ustu"`
`bos`	sorgu	`boolean`	true: yalnız boş yeri olanlar
`acik`	sorgu	`boolean`	true: yalnız şu an işletmede olanlar
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/ibb/otopark?lat=40.9903&lon=29.029&yaricap=…&ilce=Kadıköy&ara=…&tur=…&bos=…&acik=…&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
422İstanbul ilçesi bulunamadıHata
429Kredi limiti aşıldıHata
503İBB yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`toplam`	`integer`
`ozet`	`object`
`ozet.kapasite`	`integer`
`ozet.bos`	`integer`
`otoparklar`	`object[]`
`otoparklar[].id`	`integer`
`otoparklar[].ad`	`string`
`otoparklar[].tur`	`"acik" \| "kapali" \| "yol_ustu" \| "diger"`
`otoparklar[].turAdi`	`string \| null`
`otoparklar[].ilce`	`string \| null`
`otoparklar[].lat`	`number`
`otoparklar[].lon`	`number`
`otoparklar[].kapasite`	`integer`
`otoparklar[].bos`	`integer`
`otoparklar[].doluluk`	`number \| null`	Yüzde
`otoparklar[].acik`	`boolean`
`otoparklar[].calismaSaatleri`	`string \| null`
`otoparklar[].ucretsizDakika`	`number \| null`
`otoparklar[].mesafeM`	`integer`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`lisansUrl`	`string`
`atif`	`string`	İBB Açık Veri Lisansı gereği gösterilmesi gereken atıf metni
`guncelleme`	`string`	İBB'den son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/ibb/otopark/{id}

1 kredi

İSPARK otopark ayrıntısı (tarife)

Anahtar gerekli

Tek İSPARK otoparkının doluluğu, adresi, saatlik tarifesi ve aylık abonelik ücreti. Bilinmeyen numara 404, kredisiz.

Parametreler
Ad	Yer	Tip	Açıklama
`id`zorunlu	yol	`integer`

Örnek istek

curl "$KILAVUZ/v1/ibb/otopark/<id>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400id sayı olmalıHata
401Anahtar yok ya da geçersizHata
404bu numarada İSPARK otoparkı yokHata
429Kredi limiti aşıldıHata
503İBB yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`otopark`	`object`
`otopark.id`	`integer`
`otopark.ad`	`string`
`otopark.tur`	`"acik" \| "kapali" \| "yol_ustu" \| "diger"`
`otopark.turAdi`	`string \| null`
`otopark.ilce`	`string \| null`
`otopark.lat`	`number`
`otopark.lon`	`number`
`otopark.kapasite`	`integer`
`otopark.bos`	`integer`
`otopark.doluluk`	`number \| null`	Yüzde
`otopark.acik`	`boolean`
`otopark.calismaSaatleri`	`string \| null`
`otopark.ucretsizDakika`	`number \| null`
`otopark.mesafeM`	`integer`
`otopark.adres`	`string \| null`
`otopark.aylikAbonelik`	`number \| null`
`otopark.olcumZamani`	`string \| null`
`otopark.tarife`	`object[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`lisansUrl`	`string`
`atif`	`string`	İBB Açık Veri Lisansı gereği gösterilmesi gereken atıf metni
`guncelleme`	`string`	İBB'den son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/ibb/hava/istasyonlar

ücretsiz (anahtarla)

İBB hava kalitesi istasyonları (ücretsiz)

Anahtar gerekli

İBB hava kalitesi izleme istasyonları: id, ad, ilçe, konum. 24 saat önbellek.

Örnek istek

curl "$KILAVUZ/v1/ibb/hava/istasyonlar" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata
503İBB yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`toplam`	`integer`
`istasyonlar`	`object[]`
`istasyonlar[].id`	`string`
`istasyonlar[].ad`	`string`
`istasyonlar[].ilce`	`string \| null`
`istasyonlar[].lat`	`number`
`istasyonlar[].lon`	`number`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`lisansUrl`	`string`
`atif`	`string`	İBB Açık Veri Lisansı gereği gösterilmesi gereken atıf metni
`guncelleme`	`string`	İBB'den son alınma (ISO 8601)
`bayat`	`boolean`

GET/v1/ibb/hava

1 kredi

İstanbul hava kalitesi ölçümleri

Anahtar gerekli

Bir İBB istasyonunun saatlik hava kalitesi ölçümleri, yeniden eskiye: indeks, baskın kirletici, konsantrasyonlar. istasyon (ad ya da id) ya da lat/lon (en yakın sabit istasyon) gerekli. 10 dakika önbellek. Ölçüm yoksa kredi düşmez. Ham ölçümdür, resmî değerlendirme yerine geçmez.

Parametreler
Ad	Yer	Tip	Açıklama
`istasyon`	sorgu	`string`
`lat`	sorgu	`number`
`lon`	sorgu	`number`
`yaricap`	sorgu	`integer`	En yakın istasyon en çok bu kadar uzakta (metre)
`saat`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/ibb/hava?istasyon=Kadıköy&lat=…&lon=…&yaricap=…&saat=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400istasyon ya da lat/lon yok, parametre geçersizHata
401Anahtar yok ya da geçersizHata
422istasyon bulunamadı ya da yarıçapta istasyon yokHata
429Kredi limiti aşıldıHata
503İBB yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`istasyon`	`object`
`istasyon.id`	`string`
`istasyon.ad`	`string`
`istasyon.ilce`	`string \| null`
`istasyon.lat`	`number`
`istasyon.lon`	`number`
`mesafeM`	`integer`
`son`	`object \| null`
`son.zaman`	`string`	Türkiye saati (+03:00)
`son.aqi`	`number`
`son.baskinKirletici`	`string \| null`
`son.durum`	`string \| null`
`son.renk`	`string \| null`
`son.konsantrasyon`	`object`
`son.altIndeks`	`object`
`olcumler`	`object[]`
`olcumler[].zaman`	`string`	Türkiye saati (+03:00)
`olcumler[].aqi`	`number`
`olcumler[].baskinKirletici`	`string \| null`
`olcumler[].durum`	`string \| null`
`olcumler[].renk`	`string \| null`
`olcumler[].konsantrasyon`	`object`
`olcumler[].altIndeks`	`object`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`lisansUrl`	`string`
`atif`	`string`	İBB Açık Veri Lisansı gereği gösterilmesi gereken atıf metni
`guncelleme`	`string`	İBB'den son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/ibb/metro/durum

1 kredi

Metro İstanbul hat aksaklıkları

Anahtar gerekli

Metro İstanbul'un güncel hat aksaklık duyuruları. Liste boşsa (normal: true) bütün hatlar normal ve kredi düşmez. 5 dakika önbellek.

Parametreler
Ad	Yer	Tip	Açıklama
`hat`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/ibb/metro/durum?hat=M7" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata
503İBB yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`normal`	`boolean`
`duyurular`	`object[]`
`duyurular[].hat`	`string`
`duyurular[].hatId`	`integer \| null`
`duyurular[].aciklama`	`string`
`duyurular[].guncellendi`	`string \| null`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`lisansUrl`	`string`
`atif`	`string`	İBB Açık Veri Lisansı gereği gösterilmesi gereken atıf metni
`guncelleme`	`string`	İBB'den son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/ibb/nokta

ücretsiz (anahtarla)

İstanbul nokta verisi (ücretsiz)

Anahtar gerekli

İBB Açık Veri Portalı nokta listeleri: rayli raylı sistem istasyonları, wifi ibbWiFi, istanbulkart dolum noktaları, itfaiye itfaiye istasyonları, sarj elektrikli araç şarj istasyonları. lat/lon ile yakından uzağa. Veri koda gömülü (guncelleme paketlendiği gün, kaynakGuncelleme portaldaki son değişiklik).

Parametreler
Ad	Yer	Tip	Açıklama
`tur`zorunlu	sorgu	`"rayli" \| "wifi" \| "istanbulkart" \| "itfaiye" \| "sarj"`
`lat`	sorgu	`number`
`lon`	sorgu	`number`
`yaricap`	sorgu	`integer`	Metre
`ilce`	sorgu	`string`
`ara`	sorgu	`string`	Ad, hat/marka ve adresteki sözcükler (hepsi)
`altTur`	sorgu	`string`	Metro, Tramvay, Banliyö…; halka_acik\|ozel; itfaiye statüsü
`insaat`	sorgu	`boolean`	rayli: inşaattaki istasyonlar da
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/ibb/nokta?tur=…&lat=41.0369&lon=28.985&yaricap=…&ilce=…&ara=…&altTur=…&insaat=…&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tur yok ya da parametre geçersizHata
401Anahtar yok ya da geçersizHata
422İstanbul ilçesi bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`string`
`toplam`	`integer`
`sayfa`	`integer`
`noktalar`	`object[]`
`noktalar[].id`	`string \| null`
`noktalar[].ad`	`string`
`noktalar[].altTur`	`string \| null`
`noktalar[].ilce`	`string \| null`
`noktalar[].adres`	`string \| null`
`noktalar[].ek`	`string \| null`	Hat adı (rayli) ya da marka (sarj)
`noktalar[].insaat`	`boolean`
`noktalar[].lat`	`number`
`noktalar[].lon`	`number`
`noktalar[].mesafeM`	`integer`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`lisansUrl`	`string`
`atif`	`string`	İBB Açık Veri Lisansı gereği gösterilmesi gereken atıf metni
`guncelleme`	`string (date)`
`kaynakGuncelleme`	`string \| null`
`not`	`string`

Baraj doluluk

1 kredi

DSİ Türkiye geneli (yalnız aktif doluluk, il kırılımı yok) ile ASKİ (Ankara), İZSU açık verisi (İzmir, CC BY) ve GASKİ (Gaziantep). İstanbul yok: İSKİ verisi anahtarla korunuyor. İstek anında, kaynak başına 1 saat önbellek; düşen kaynak `eksik` listesinde, ötekiler gelir.

GET/v1/su/baraj-doluluk

1 kredi

Baraj doluluk oranları

Anahtar gerekli

İdarelerin kendi yayımladığı baraj doluluk oranları: Türkiye geneli (DSİ panosu), Ankara (ASKİ), İzmir (İZSU açık veri, CC BY 4.0), Gaziantep (GASKİ). İstek anında, kaynak başına 1 saat önbellek; kaynak düşerse 48 saate kadar eski veri bayat: true. il verilmezse kapsamdaki hepsi; düşen kaynak eksikte. İstanbul ve Bursa kapsam dışı (gerekçe kaynak notunda).

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`	İl adı ya da "Türkiye"; boşsa hepsi

Örnek istek

curl "$KILAVUZ/v1/su/baraj-doluluk?il=İzmir" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
422il bulunamadı ya da kapsam dışı (kapsam yanıtta)Hata
429Kredi limiti aşıldıHata
503kaynaklar yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`il`	`string \| null`
`sonuclar`	`object[]`
`sonuclar[].il`	`string`
`sonuclar[].tarih`	`string \| null`	Verinin günü (kaynağın yazdığı); yoksa null
`sonuclar[].toplamDolulukYuzde`	`number \| null`
`sonuclar[].aktifDolulukYuzde`	`number \| null`
`sonuclar[].gecenYil`	`object \| null`
`sonuclar[].barajlar`	`object[]`
`sonuclar[].amaclar`	`object[]`
`sonuclar[].aciklama`	`string`
`sonuclar[].kaynak`	`string`
`sonuclar[].kaynakUrl`	`string`
`sonuclar[].lisans`	`string`
`sonuclar[].guncelleme`	`string`	Bu kaynaktan son alınma (ISO 8601)
`sonuclar[].bayat`	`boolean`
`eksik`	`object[]`
`eksik[].il`	`string`
`eksik[].neden`	`string`
`kapsam`	`string[]`
`kaynak`	`string`
`guncelleme`	`string`	Sonuçlardaki en eski alma zamanı (ISO 8601)
`bayat`	`boolean`
`not`	`string`

Hava durumu

0–1 kredi

MET Norway sayısal model tahmini (CC BY 4.0, atıf yanıtta); MGM’nin resmî tahmini ya da uyarısı değildir. Saatler UTC; günlük özet Türkiye gününe göre. İl verilirse il merkezinin koordinatı kullanılır. Nokta başına 30 dk önbellek.

GET/v1/hava/durumHava durumu tahmini (MET Norway)
GET/v1/hava/kaliteHava kalitesi, 81 il (Çevre Bakanlığı SİM)
GET/v1/hava/kalite/istasyonlarHava kalitesi istasyonları (ücretsiz)

GET/v1/hava/durum

1 kredi

Hava durumu tahmini (MET Norway)

Anahtar gerekli

İl merkezi ya da koordinat için anlık, 24 saatlik ve 7 günlük tahmin. Kaynak MET Norway Locationforecast 2.0 (NLOD 2.0 / CC BY 4.0), istek anında, nokta başına 30 dk önbellek; koordinat 2 ondalığa yuvarlanır. MGM'nin resmî tahmini değildir. Kaynak düşerse 6 saate kadar eski tahmin bayat: true, hiç yoksa 503.

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`	İl adı ya da plaka; lat/lon ile birlikte verilmez
`lat`	sorgu	`number`
`lon`	sorgu	`number`

Örnek istek

curl "$KILAVUZ/v1/hava/durum?il=Ankara&lat=…&lon=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il ya da lat/lon eksik ya da geçersizHata
401Anahtar yok ya da geçersizHata
422il bulunamadı ya da koordinat kapsam dışıHata
429Kredi limiti aşıldıHata
503kaynak yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`il`	`string \| null`
`plaka`	`integer \| null`
`konum`	`object`
`konum.lat`	`number`
`konum.lon`	`number`
`konum.rakimM`	`number \| null`
`konum.kaynak`	`string`
`anlik`	`HavaSaati ya da null`
`saatlik`	`HavaSaati[]`
`gunluk`	`object[]`
`gunluk[].tarih`	`string`
`gunluk[].enDusukC`	`number \| null`
`gunluk[].enYuksekC`	`number \| null`
`gunluk[].yagisMm`	`number`
`gunluk[].durum`	`string \| null`
`gunluk[].durumKod`	`string \| null`
`modelGuncelleme`	`string \| null`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`	MET'ten son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/hava/kalite

1 kredi

Hava kalitesi, 81 il (Çevre Bakanlığı SİM)

Anahtar gerekli

Çevre, Şehircilik ve İklim Değişikliği Bakanlığı Sürekli İzleme Merkezi'nin ~336 istasyonundan son saatlik ölçüm: Ulusal Hava Kalitesi İndeksi (aqi), durum, baskın kirletici, PM10/PM2.5/NO2/SO2/CO/O3 konsantrasyonu ve alt indeksleri. İl (ilçe), istasyon ya da koordinatla (en yakın istasyonlar, seyyar araç hariç). Kaynak yurt dışı IP'ye kapalı: ölçümler Türkiye'deki bir makineden gündüz (08:30–20:30) iki saatte bir çekilir; son çekim 3 saatten eskiyse (gece, kaçan tur) bayat: true, hiç veri yoksa 503. Doğrulanmamış ham veri. Ölçümü olan istasyon yoksa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`	İl adı ya da plaka
`ilce`	sorgu	`string`	Yalnız il ile
`istasyon`	sorgu	`string`	İstasyon adı (parçası) ya da kimliği
`lat`	sorgu	`number`
`lon`	sorgu	`number`
`yaricapKm`	sorgu	`integer`	Koordinatla arama yarıçapı
`limit`	sorgu	`integer`	Koordinatla varsayılan 3, öteki 50

Örnek istek

curl "$KILAVUZ/v1/hava/kalite?il=Ankara&ilce=…&istasyon=…&lat=…&lon=…&yaricapKm=…&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il, istasyon ya da lat/lon eksik; parametreler çelişiyor ya da geçersizHata
401Anahtar yok ya da geçersizHata
422il ya da istasyon bulunamadı, koordinat kapsam dışı ya da yarıçapta istasyon yokHata
429Kredi limiti aşıldıHata
503hava kalitesi verisi henüz yok (hiç çekilmedi)Hata

Yanıt alanları
`il`	`string \| null`
`istasyonlar`	`object[]`
`istasyonlar[].id`	`string`
`istasyonlar[].kod`	`string \| null`
`istasyonlar[].ad`	`string`
`istasyonlar[].il`	`string`
`istasyonlar[].ilce`	`string \| null`
`istasyonlar[].lat`	`number`
`istasyonlar[].lon`	`number`
`istasyonlar[].tur`	`string \| null`
`istasyonlar[].isleten`	`string \| null`
`istasyonlar[].mobil`	`boolean`	Seyyar ölçüm aracı
`istasyonlar[].mesafeKm`	`number`	Yalnız koordinatla aramada
`istasyonlar[].olcum`	`object`
`istasyonlar[].eski`	`boolean`	Son ölçüm 3 saatten eski
`ozet`	`object`
`ozet.istasyonSayisi`	`integer`
`ozet.olcumlu`	`integer`
`ozet.enYuksek`	`object \| null`
`esikler`	`object[]`
`esikler[].kod`	`integer`
`esikler[].ad`	`string`
`esikler[].min`	`number`
`esikler[].max`	`number`
`esikler[].aciklama`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`	SİM'den son başarılı çekim (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/hava/kalite/istasyonlar

ücretsiz (anahtarla)

Hava kalitesi istasyonları (ücretsiz)

Anahtar gerekli

SİM hava kalitesi istasyonları: kimlik, ad, il, ilçe, konum, tür, işleten. İl ile süzülebilir.

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`	İl adı ya da plaka

Örnek istek

curl "$KILAVUZ/v1/hava/kalite/istasyonlar?il=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
422il bulunamadıHata
429Kredi limiti aşıldıHata
503hava kalitesi verisi henüz yok (hiç çekilmedi)Hata

Yanıt alanları
`toplam`	`integer`
`istasyonlar`	`object[]`
`istasyonlar[].id`	`string`
`istasyonlar[].kod`	`string \| null`
`istasyonlar[].ad`	`string`
`istasyonlar[].il`	`string`
`istasyonlar[].ilce`	`string \| null`
`istasyonlar[].lat`	`number`
`istasyonlar[].lon`	`number`
`istasyonlar[].tur`	`string \| null`
`istasyonlar[].isleten`	`string \| null`
`istasyonlar[].mobil`	`boolean`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`
`bayat`	`boolean`

Deprem

1 kredi

AFAD olay servisinden istek anında, 60 sn önbellek. `zaman` UTC, `zamanTr` Türkiye saati. AFAD olayları sonradan düzeltebilir. Resmî uyarı ya da erken uyarı yerine geçmez.

GET/v1/deprem/son

1 kredi

Son depremler (AFAD)

Anahtar gerekli

AFAD Deprem Dairesi olay servisinden son depremler, yeniden eskiye. Veri istek anında AFAD'dan alınır, en çok 1 dakika önbellekte tutulur; en çok 168 saat (7 gün) geriye. AFAD yanıt vermezken 6 saate kadar eski veri bayat: true ile döner, hiç veri yoksa 503. Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`saat`	sorgu	`integer`
`minBuyukluk`	sorgu	`number`
`il`	sorgu	`string`	AFAD'ın olaya yazdığı il (denizdeki olayda en yakın il)
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/deprem/son?saat=…&minBuyukluk=3&il=İzmir&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre aralık dışındaHata
401Anahtar yok ya da geçersizHata
422il bulunamadıHata
429Kredi limiti aşıldıHata
503AFAD yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`il`	`string \| null`
`toplam`	`integer`	Süzgece uyan olay sayısı (limit öncesi)
`depremler`	`object[]`
`depremler[].id`	`string`
`depremler[].zaman`	`string`	UTC, ISO 8601
`depremler[].zamanTr`	`string`	Türkiye saati (+03:00)
`depremler[].buyukluk`	`number`
`depremler[].tur`	`string`	ML, MW…
`depremler[].derinlikKm`	`number`
`depremler[].lat`	`number`
`depremler[].lon`	`number`
`depremler[].yer`	`string`
`depremler[].ulke`	`string \| null`
`depremler[].il`	`string \| null`
`depremler[].ilce`	`string \| null`
`depremler[].mahalle`	`string \| null`
`depremler[].guncellendi`	`string \| null`	AFAD olayı düzelttiyse güncelleme zamanı (UTC)
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`	AFAD'dan son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

Eğitim

ücretsiz (anahtarla)

MEB resmî okul ve kurum listesi (özel okul ve adres yok; okul türü addan çıkarılır). YÖK üniversite listesi, YÖK Atlas 2026 tercih kılavuzu ve ÖSYM sınav takvimi (başvuru, sınav, sonuç tarihleri; yalnız yayımlanmış yıllar), koda gömülü. Taban puan ve başarı sırası kılavuzdaki son yerleştirme; tercih için ÖSYM kılavuzu esastır.

GET/v1/egitim/universitelerÜniversiteler (ücretsiz)
GET/v1/egitim/universiteler/{id}Üniversite ve programları (ücretsiz)
GET/v1/egitim/okullarMEB okul ve kurumları (ücretsiz)
POST/v1/egitim/yks-puaniYKS net, OBP ve yerleştirme puanı (ücretsiz)
POST/v1/egitim/lgs-puaniLGS netleri ve katsayılar (ücretsiz)
GET/v1/egitim/sinav-takvimiÖSYM sınav takvimi (ücretsiz)
GET/v1/egitim/programlarProgram / bölüm ara (ücretsiz)

GET/v1/egitim/universiteler

ücretsiz (anahtarla)

Üniversiteler (ücretsiz)

Anahtar gerekli

YÖK listesi (devlet, vakıf, vakıf MYO, KKTC) + YÖK Atlas'taki yurt dışı kurumlar. id YÖK birim numarası; programlar için /v1/egitim/universiteler/{id}. Veri gömülü, guncelleme alındığı gün.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`	Ad içinde geçen
`il`	sorgu	`string`
`tur`	sorgu	`"devlet" \| "vakif" \| "vakif_myo" \| "kktc" \| "yurtdisi"`

Örnek istek

curl "$KILAVUZ/v1/egitim/universiteler?ara=teknik&il=Ankara&tur=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tur geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`universiteler`	`object[]`
`universiteler[].id`	`integer \| null`	YÖK birim numarası
`universiteler[].ad`	`string`
`universiteler[].il`	`string \| null`
`universiteler[].tur`	`"devlet" \| "vakif" \| "vakif_myo" \| "kktc" \| "yurtdisi"`
`universiteler[].kurulus`	`string \| null (date)`
`universiteler[].web`	`string \| null`
`universiteler[].adres`	`string \| null`
`universiteler[].programSayisi`	`object`
`kaynak`	`string`
`kaynakUrl`	`string[]`
`lisans`	`string`
`guncelleme`	`string (date)`
`kilavuzYili`	`integer \| null`

GET/v1/egitim/universiteler/{id}

ücretsiz (anahtarla)

Üniversite ve programları (ücretsiz)

Anahtar gerekli

Parametreler
Ad	Yer	Tip	Açıklama
`id`zorunlu	yol	`integer`	YÖK birim numarası
`duzey`	sorgu	`"lisans" \| "onlisans"`
`puanTuru`	sorgu	`"SAY" \| "EA" \| "SÖZ" \| "DİL" \| "TYT"`

Örnek istek

curl "$KILAVUZ/v1/egitim/universiteler/<id>?duzey=…&puanTuru=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400id ya da duzey geçersizHata
401Anahtar yok ya da geçersizHata
404bu numarada üniversite yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`universite`	`object`
`universite.id`	`integer \| null`	YÖK birim numarası
`universite.ad`	`string`
`universite.il`	`string \| null`
`universite.tur`	`"devlet" \| "vakif" \| "vakif_myo" \| "kktc" \| "yurtdisi"`
`universite.kurulus`	`string \| null (date)`
`universite.web`	`string \| null`
`universite.adres`	`string \| null`
`universite.programSayisi`	`object`
`programSayisi`	`integer`
`programlar`	`object[]`
`programlar[].kod`	`integer`	ÖSYM kılavuz kodu
`programlar[].universiteId`	`integer`
`programlar[].fakulte`	`string \| null`
`programlar[].ad`	`string`
`programlar[].grup`	`string \| null`
`programlar[].duzey`	`"lisans" \| "onlisans"`
`programlar[].ogretimTuru`	`string \| null`
`programlar[].sureYil`	`number \| null`
`programlar[].puanTuru`	`string \| null`
`programlar[].dil`	`string \| null`
`programlar[].burs`	`string \| null`
`programlar[].kontenjan`	`number \| null`
`programlar[].tabanPuan`	`number \| null`
`programlar[].tabanBasariSirasi`	`number \| null`
`programlar[].ucretTl`	`number \| null`
`programlar[].il`	`string \| null`
`programlar[].ilce`	`string \| null`
`kaynak`	`string`
`kaynakUrl`	`string[]`
`lisans`	`string`
`guncelleme`	`string (date)`
`kilavuzYili`	`integer \| null`
`uyari`	`string`

GET/v1/egitim/okullar

ücretsiz (anahtarla)

MEB okul ve kurumları (ücretsiz)

Anahtar gerekli

MEB "Okullar ve Diğer Kurumlar" listesindeki resmî okul ve kurumlar (~55 bin): ad, MEB kurum kodu, tür, il, ilçe, meb.k12.tr sitesi. il ya da ara gerekli. Adres kaynakta yok; özel okullar yok. tur addan çıkarıldı.

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`	İl adı ya da plaka
`ilce`	sorgu	`string`
`tur`	sorgu	`"anaokulu" \| "ilkokul" \| "ortaokul" \| "imam_hatip_ortaokulu" \| "anadolu_lisesi" \| "fen_lisesi" \| "sosyal_bilimler_lisesi" \| "imam_hatip_lisesi" \| "mesleki_teknik_lise" \| "guzel_sanatlar_spor_lisesi" \| "lise" \| "ozel_egitim" \| "bilsem" \| "halk_egitim" \| "mesleki_egitim_merkezi" \| "ram" \| "ogretmenevi" \| "mudurluk" \| "diger"`
`ara`	sorgu	`string`	Addaki sözcükler (hepsi)
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/egitim/okullar?il=Ankara&ilce=Çankaya&tur=…&ara=fen lisesi&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersiz ya da il/ara yokHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`sayfa`	`integer`
`limit`	`integer`
`okullar`	`object[]`
`okullar[].kurumKodu`	`integer`
`okullar[].ad`	`string`
`okullar[].tur`	`string`
`okullar[].il`	`string`
`okullar[].ilce`	`string`
`okullar[].ilKodu`	`integer`
`okullar[].web`	`string \| null`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

POST/v1/egitim/yks-puani

ücretsiz (anahtarla)

YKS net, OBP ve yerleştirme puanı (ücretsiz)

Anahtar gerekli

ÖSYM 2026 kılavuzuna göre: test ve alt alan netleri (doğru − yanlış/4), puan türü koşulları (Tablo 1D), OBP (diploma notu × 5, 50'nin altı 50) ve adayın ÖSYM sonucundaki sınav puanından yerleştirme puanı (+ OBP × 0,12; meslek lisesi ek puanı OBP × 0,06; önceki yıl yerleşenlerde yarısı). Sınav puanı netten hesaplanmaz: standart puan ve 100–500 dönüşümü aday kitlesinin istatistiğine bağlı (sinavPuaniNotu).

İstek gövdesi
Alan	Tip	Açıklama
`tyt`	`object`	turkce (40), sosyal (20), temelMatematik (40), fen (20): {dogru, yanlis}
`ayt`	`object`	matematik 40, fizik 14, kimya 13, biyoloji 13, edebiyat 24, tarih1 10, cografya1 6, tarih2 11, cografya2 11, felsefe 12, din 6
`ydt`	`object`	yabanciDil (80)
`diplomaNotu`	`number`	0–100
`sinavPuanlari`	`object`	ÖSYM sonuç belgesindeki puanlar: TYT, SAY, EA, SOZ, DIL (100–500)
`oncekiYilYerlesti`	`boolean`	2025-YKS ile yerleşen: OBP katsayıları yarıya
`meslekEkPuani`	`boolean`	Meslek lisesi mezunu, Tablo 3A/3B.1/3C/3D programı

Örnek istek

curl -X POST "$KILAVUZ/v1/egitim/yks-puani" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"tyt":{"turkce":{"dogru":32,"yanlis":6},"temelMatematik":{"dogru":28,"yanlis":8}},"ayt":{"matematik":{"dogru":20,"yanlis":8}},"diplomaNotu":85,"sinavPuanlari":{"SAY":400}}'

Yanıtlar

200Başarılı
400Girdi geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`netler`	`object`
`testNetleri`	`object`
`puanTurleri`	`object`
`obp`	`object \| null`
`obpKatsayilari`	`object`
`yerlestirme`	`object \| null`
`sinavPuani`	`null`
`sinavPuaniNotu`	`string`
`agirliklar`	`object`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`

POST/v1/egitim/lgs-puani

ücretsiz (anahtarla)

LGS netleri ve katsayılar (ücretsiz)

Anahtar gerekli

MEB 2026 kılavuzuna göre test netleri (doğru − yanlış/3), ağırlık katsayıları (Türkçe, matematik, fen 4; diğerleri 1) ve resmî formül. MSP netten hesaplanmaz: standart puan ve 100–500 dönüşümü bütün öğrencilerin istatistiğine bağlı (mspNotu).

İstek gövdesi
Alan	Tip	Açıklama
`testler`zorunlu	`object`	turkce 20, matematik 20, fen 20, inkilap 10, din 10, yabanciDil 10: {dogru, yanlis}
`muaf`	`"din" \| "yabanciDil"[]`

Örnek istek

curl -X POST "$KILAVUZ/v1/egitim/lgs-puani" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"testler":{"turkce":{"dogru":18,"yanlis":2},"matematik":{"dogru":15,"yanlis":3}}}'

Yanıtlar

200Başarılı
400Girdi geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`netler`	`object`
`toplamNet`	`number`
`verilmeyenTestler`	`string[]`
`muaf`	`string[]`
`katsayilar`	`object`
`msp`	`null`
`mspNotu`	`string`
`formul`	`object`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`

GET/v1/egitim/sinav-takvimi

ücretsiz (anahtarla)

ÖSYM sınav takvimi (ücretsiz)

Anahtar gerekli

ÖSYM yıllık sınav takvimi: başvuru başlangıç/bitiş, geç başvuru, sınav ve sonuç tarihleri; bugüne göre durum. Çok oturumlu sınavlar (YKS, KPSS…) oturumlar altında toplanır. Takvim yayımlanmamış yıl için boş liste ve yayimlanmadi notu döner. Kesin tarih için osym.gov.tr esastır.

Parametreler
Ad	Yer	Tip	Açıklama
`yil`	sorgu	`string`	Varsayılan bu yıl
`ara`	sorgu	`string`	Sınav adı ya da kısaltması

Örnek istek

curl "$KILAVUZ/v1/egitim/sinav-takvimi?yil=2026&ara=KPSS" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400yil ya da ara geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`toplam`	`integer`
`yayimlanmadi`	`string`
`sinavlar`	`object[]`
`sinavlar[].ad`	`string`
`sinavlar[].kod`	`string`
`sinavlar[].uzunAd`	`string`
`sinavlar[].basvuruBaslangic`	`string \| null`
`sinavlar[].basvuruBitis`	`string \| null`
`sinavlar[].gecBasvuru`	`object`
`sinavlar[].sinavTarihleri`	`string (date)[]`
`sinavlar[].sinavSaati`	`string`
`sinavlar[].sonucTarihi`	`string \| null`
`sinavlar[].aciklama`	`string`
`sinavlar[].durum`	`"basvuru_bekleniyor" \| "basvuru_acik" \| "sinav_bekleniyor" \| "sonuc_bekleniyor" \| "tamamlandi"`
`sinavlar[].oturumlar`	`object[]`
`sinavlar[].belirsiz`	`boolean`
`sinavlar[].not`	`string`
`bilinenYillar`	`integer[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

GET/v1/egitim/programlar

ücretsiz (anahtarla)

Program / bölüm ara (ücretsiz)

Anahtar gerekli

YÖK Atlas tercih kılavuzundaki lisans ve önlisans programları; son yerleştirmenin taban başarı sırasına göre (sırası olmayanlar sonda). ara, universite ya da ilden en az biri gerekli. Taban puan bu yılın değil, son yerleştirmenindir.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`	Program ya da program grubu adındaki sözcükler (hepsi)
`universite`	sorgu	`string`	Üniversite adı ya da YÖK birim numarası
`il`	sorgu	`string`
`puanTuru`	sorgu	`"SAY" \| "EA" \| "SÖZ" \| "DİL" \| "TYT"`
`duzey`	sorgu	`"lisans" \| "onlisans"`
`burs`	sorgu	`string`	"Burslu", "%50", "Ücretli" (içerir)
`dil`	sorgu	`string`
`universiteTuru`	sorgu	`"devlet" \| "vakif" \| "vakif_myo" \| "kktc" \| "yurtdisi"`
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/egitim/programlar?ara=bilgisayar mühendisliği&universite=…&il=…&puanTuru=…&duzey=…&burs=Burslu&dil=İngilizce&universiteTuru=…&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersiz ya da arama ölçütü yokHata
401Anahtar yok ya da geçersizHata
404üniversite bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`sayfa`	`integer`
`limit`	`integer`
`programlar`	`object[]`
`programlar[].kod`	`integer`	ÖSYM kılavuz kodu
`programlar[].universiteId`	`integer`
`programlar[].fakulte`	`string \| null`
`programlar[].ad`	`string`
`programlar[].grup`	`string \| null`
`programlar[].duzey`	`"lisans" \| "onlisans"`
`programlar[].ogretimTuru`	`string \| null`
`programlar[].sureYil`	`number \| null`
`programlar[].puanTuru`	`string \| null`
`programlar[].dil`	`string \| null`
`programlar[].burs`	`string \| null`
`programlar[].kontenjan`	`number \| null`
`programlar[].tabanPuan`	`number \| null`
`programlar[].tabanBasariSirasi`	`number \| null`
`programlar[].ucretTl`	`number \| null`
`programlar[].il`	`string \| null`
`programlar[].ilce`	`string \| null`
`programlar[].universite`	`string`
`programlar[].universiteTuru`	`string`
`kaynak`	`string`
`kaynakUrl`	`string[]`
`lisans`	`string`
`guncelleme`	`string (date)`
`kilavuzYili`	`integer \| null`
`uyari`	`string`

Otoyol ve köprü geçişi

0–1 kredi

KGM’nin 19 tarife PDF’inden, koda gömülü; araç sınıfı 1–6. İhlalli geçiş cezası, HGS/OGS kampanyaları ve Avrasya Tüneli kapsam dışı.

GET/v1/ulasim/yol-maliyetiYol maliyeti tahmini (mesafe + yakıt + geçiş)
GET/v1/ulasim/gecis-ucretleriOtoyol ve köprü geçiş ücretleri (ücretsiz)

GET/v1/ulasim/yol-maliyeti

1 kredi

Yol maliyeti tahmini (mesafe + yakıt + geçiş)

Anahtar gerekli

**Tahmindir.** a–b arası karayolu mesafesi (kuş uçuşu × 1,3; rota hesabı değil), çıkış (a) ilinin güncel EPDK bayi ortalamasıyla yakıt litresi ve tutarı, isteğe bağlı tek geçiş ücreti ve toplam. Geçiş ücreti güzergâh bilinmediği için **tahmin edilmez**: yalnız yol + giris + cikis (köprüde yalnız yol) verilirse KGM tarifesinden eklenir; verilmezse gecis: null, toplamda geçiş yok. tuketim verilmezse benzinde 7, motorinde 6 L/100 km varsayılır (tuketimVarsayilan: true). LPG EPDK bayi raporunda yok. 1 kredi; yakıt fiyatı bulunamazsa toplamTl: null ve kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`a`zorunlu	sorgu	`string`	Çıkış: il adı, plaka ya da "enlem,boylam"
`b`zorunlu	sorgu	`string`	Varış: il adı, plaka ya da "enlem,boylam"
`yakit`	sorgu	`"benzin" \| "motorin"`
`tuketim`	sorgu	`number`	L/100 km
`sinif`	sorgu	`integer`	KGM araç sınıfı (1 otomobil); yalnız geçiş ücretinde
`yol`	sorgu	`string`	Geçiş tarifesi (köprü adı ya da otoyol)
`giris`	sorgu	`string`	Otoyol giriş istasyonu; cikis ile birlikte
`cikis`	sorgu	`string`	Otoyol çıkış istasyonu; giris ile birlikte

Örnek istek

curl "$KILAVUZ/v1/ulasim/yol-maliyeti?a=İstanbul&b=Ankara&yakit=…&tuketim=…&sinif=…&yol=osmangazi&giris=…&cikis=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400a/b eksik, parametre geçersiz ya da geçiş belirsizHata
401Anahtar yok ya da geçersizHata
404geçiş tarifesi ya da giriş-çıkış çifti bulunamadıHata
422a ya da b bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`a`	`object`
`b`	`object`
`mesafe`	`object`
`mesafe.kusUcusuKm`	`number`
`mesafe.karayoluTahminiKm`	`number`
`mesafe.katsayi`	`number`
`arac`	`object`
`arac.sinif`	`integer`
`arac.sinifTanim`	`string \| null`
`arac.yakit`	`"benzin" \| "motorin"`
`arac.tuketimL100`	`number`
`arac.tuketimVarsayilan`	`boolean`
`yakit`	`object`
`yakit.il`	`string \| null`	Fiyatın alındığı il (çıkış)
`yakit.urun`	`string`
`yakit.litreFiyati`	`number \| null`	TL/litre, EPDK bayi ortalaması (şüpheli bildirimler hariç)
`yakit.enDusuk`	`number \| null`
`yakit.enYuksek`	`number \| null`
`yakit.markaSayisi`	`integer`
`yakit.fiyatTarihi`	`string \| null`
`yakit.litre`	`number`
`yakit.tutarTl`	`number \| null`
`gecis`	`object \| null`	Yalnız yol/giris/cikis verildiyse
`gecis.yol`	`object`
`gecis.giris`	`string \| null`
`gecis.cikis`	`string \| null`
`gecis.sinif`	`integer`
`gecis.ucretTl`	`number`
`gecis.gecerlilik`	`string \| null`
`gecisTl`	`number`
`toplamTl`	`number \| null`	Yakıt + geçiş; yakıt fiyatı yoksa null
`tahmin`	`boolean`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string \| null`	Yakıt fiyatlarının son başarılı çekimi (ISO 8601)
`bayat`	`boolean`
`not`	`string`

GET/v1/ulasim/gecis-ucretleri

ücretsiz (anahtarla)

Otoyol ve köprü geçiş ücretleri (ücretsiz)

Anahtar gerekli

KGM tarifeleri (15 Temmuz/FSM, Osmangazi, YSS, 1915 Çanakkale köprüleri ve otoyollar), araç sınıfı 1–6, TL, KDV dahil. Parametresiz bütün tarifeler; yol ile tek tarife; giris + cikis ile o çiftin ücreti (yol verilmezse bütün otoyollarda aranır). ucretler dizisi sınıf sırasıyla; sinif verilirse tek eleman. yonlu: false tarifede iki yön aynı ücret.

Parametreler
Ad	Yer	Tip	Açıklama
`yol`	sorgu	`string`	Tarife numarası ya da adındaki sözcükler
`giris`	sorgu	`string`	Giriş istasyonu (cikis ile birlikte)
`cikis`	sorgu	`string`
`sinif`	sorgu	`integer`	1 otomobil … 5 altı+ akslı, 6 motosiklet

Örnek istek

curl "$KILAVUZ/v1/ulasim/gecis-ucretleri?yol=izmir çeşme&giris=urla&cikis=çeşme&sinif=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersiz ya da istasyon adı birden çok istasyona uyuyor (adaylar)Hata
401Anahtar yok ya da geçersizHata
404tarife ya da giriş-çıkış çifti bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`siniflar`	`object[]`
`siniflar[].sinif`	`integer`
`siniflar[].tanim`	`string`
`tarifeler`	`object[]`
`tarifeler[].no`	`integer`
`tarifeler[].ad`	`string`
`tarifeler[].tur`	`"kopru" \| "otoyol"`
`tarifeler[].gecerlilik`	`string \| null (date)`
`tarifeler[].kdvDahil`	`boolean`
`tarifeler[].kaynakUrl`	`string`
`tarifeler[].ucretler`	`number \| null[]`
`tarifeler[].kesimler`	`object[]`
`sonuclar`	`object[]`	giris+cikis ile
`sonuclar[].yol`	`object`
`sonuclar[].kesim`	`integer`
`sonuclar[].giris`	`string`
`sonuclar[].cikis`	`string`
`sonuclar[].yonlu`	`boolean`
`sonuclar[].ucretler`	`number \| null[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

Enerji tarifeleri

ücretsiz (anahtarla)

Elektrik: EPDK tarife tablosu, vergiler ve fonlar hariç enerji ve dağıtım bedeli (kr/kWh). Doğal gaz: BOTAŞ toptan satış fiyatı ve il bazında konut kademe limiti; dağıtım şirketi bedeli, ÖTV ve KDV yok. Evdeki fatura değildir.

GET/v1/enerji/tarife

ücretsiz (anahtarla)

Elektrik ve doğal gaz tarifesi (ücretsiz)

Anahtar gerekli

Vergiler hariç resmî tarifeler. elektrik: EPDK tarife tablosu (kr/kWh), sınıf × abone grubu satırları, perakendeTekZamanli = enerji + dağıtım. dogalgaz: BOTAŞ toptan satış fiyatı (TL/Sm³; dağıtım şirketinin alış fiyatı, ev faturasına dağıtım bedeli + ÖTV + KDV eklenir); il verilirse konut kademe limiti. Tarife değişince gömülü veri güncellenir; gecerlilik.baslangic yürürlük günü.

Parametreler
Ad	Yer	Tip	Açıklama
`tur`	sorgu	`"elektrik" \| "dogalgaz"`	Verilmezse ikisi
`grup`	sorgu	`string`	Elektrik abone grubu (içerir)
`sinif`	sorgu	`string`	Elektrik tarife sınıfı (başlar)
`il`	sorgu	`string`	Doğal gaz konut kademe limiti
`ay`	sorgu	`string`	Kademe limitinin ayı; varsayılan bu ay

Örnek istek

curl "$KILAVUZ/v1/enerji/tarife?tur=…&grup=mesken&sinif=AG&il=Ankara&ay=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersiz ya da il bulunamadıHata
401Anahtar yok ya da geçersizHata
404eşleşen elektrik tarifesi yok (yanıtta gruplar ve siniflar)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`elektrik`	`object`
`elektrik.gecerlilik`	`object`
`elektrik.baslik`	`string`
`elektrik.birim`	`object`
`elektrik.satirlar`	`object[]`
`elektrik.notlar`	`string[]`
`elektrik.kaynak`	`string`
`elektrik.kaynakUrl`	`string`
`elektrik.not`	`string`
`dogalgaz`	`object`
`dogalgaz.gecerlilik`	`object`
`dogalgaz.baslik`	`string`
`dogalgaz.birim`	`string`
`dogalgaz.fiyatlar`	`object[]`
`dogalgaz.kademe`	`object`	il verilirse: aylar (12 ay, aylikSm3) ve secilenAy (aylikSm3, gunlukSm3)
`dogalgaz.notlar`	`string[]`
`dogalgaz.kaynak`	`string`
`dogalgaz.kaynakUrl`	`string`
`dogalgaz.not`	`string`
`lisans`	`string`
`uyari`	`string`

Resmî Gazete

0–1 kredi

Günlük fihrist: bölüm, kategori, başlık ve resmigazete.gov.tr bağlantısı; belge metni yok, resmî metin yerine geçmez. İlan sayfaları açılmaz; başlığında kişi adı geçen satır yalnız kategorisiyle saklanır, adla aranamaz. Geçmiş 5 yıl.

GET/v1/resmi-gazete/bugunEn yeni Resmî Gazete fihristi
GET/v1/resmi-gazeteBir günün ya da sayının fihristi
GET/v1/resmi-gazete/araFihrist başlıklarında arama ve konu süzgeci

GET/v1/resmi-gazete/bugun

ücretsiz (anahtarla)

En yeni Resmî Gazete fihristi

Anahtar gerekli

Elimizdeki en yeni günün Resmî Gazete fihristi (içindekiler): başlık, bölüm, kategori ve resmigazete.gov.tr bağlantısı. Aynı günün mükerrer sayıları ayrı girdi (mukerrer > 0). Belgelerin metni yoktur. Vitrin ucu: her zaman ücretsiz.

Örnek istek

curl "$KILAVUZ/v1/resmi-gazete/bugun" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tarih`	`string \| null (date)`	Yayım günü; kayıt yoksa null
`sayilar`	`object[]`	Gün içindeki sayılar: asıl sayı ve varsa mükerrerler
`sayilar[].tarih`	`string (date)`
`sayilar[].sayi`	`integer`	Gazete sayısı, örn. 33378
`sayilar[].mukerrer`	`integer`	0 asıl sayı, 1 birinci mükerrer…
`sayilar[].url`	`string`	Fihrist sayfasının adresi
`sayilar[].basliklar`	`object[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/resmi-gazete

1 kredi

Bir günün ya da sayının fihristi

Anahtar gerekli

Verilen günün (tarih) ya da sayının (sayi) fihristi; en az biri gerekli. Kaynak günde iki kez çekilir, geçmiş 5 yıl tutulur. Gazete o gün yayımlanmadıysa (resmî tatil) liste boş döner ve kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`tarih`	sorgu	`string (date)`	Yayım günü (YYYY-AA-GG)
`sayi`	sorgu	`integer`	Gazete sayısı; mükerrerler de gelir

Örnek istek

curl "$KILAVUZ/v1/resmi-gazete?tarih=2026-09-22&sayi=33378" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih ya da sayi gerekli / geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tarih`	`string \| null (date)`	Yayım günü; kayıt yoksa null
`sayilar`	`object[]`	Gün içindeki sayılar: asıl sayı ve varsa mükerrerler
`sayilar[].tarih`	`string (date)`
`sayilar[].sayi`	`integer`	Gazete sayısı, örn. 33378
`sayilar[].mukerrer`	`integer`	0 asıl sayı, 1 birinci mükerrer…
`sayilar[].url`	`string`	Fihrist sayfasının adresi
`sayilar[].basliklar`	`object[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/resmi-gazete/ara

1 kredi

Fihrist başlıklarında arama ve konu süzgeci

Anahtar gerekli

Başlıkta geçen metne göre (Türkçe karakter ve büyük/küçük harf ayrımı yok) ve/veya konu etiketine göre arar; q ya da etiketten en az biri gerekli. Yeniden eskiye, en çok 50 sonuç. Etiket otomatik sınıflandırmadır, yanılabilir. kisisel: true satırların başlığı kategorisine indirgenmiştir: kişi adıyla aranamaz. Sonuç boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`q`	sorgu	`string`
`etiket`	sorgu	`"egitim" \| "vergi_maliye" \| "finans" \| "enerji" \| "gida_tarim" \| "saglik" \| "cevre" \| "ulasim" \| "yargi" \| "kamu_personel" \| "kamu_idare" \| "uluslararasi" \| "ticaret_sanayi" \| "diger"`
`baslangic`	sorgu	`string (date)`	En eski gün
`bitis`	sorgu	`string (date)`	En yeni gün
`bolum`	sorgu	`"yasama" \| "yurutme" \| "yargi" \| "ilan"`

Örnek istek

curl "$KILAVUZ/v1/resmi-gazete/ara?q=tıbbi cihaz&etiket=vergi_maliye&baslangic=2026-09-18&bitis=2026-09-18&bolum=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400q ya da etiket yok, q 3 karakterden kısa / etiket, tarih ya da bolum geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`q`	`string \| null`
`etiket`	`string \| null`
`sonuclar`	`object[]`
`sonuclar[].tarih`	`string (date)`
`sonuclar[].sayi`	`integer`
`sonuclar[].mukerrer`	`integer`	0 asıl sayı, 1 birinci mükerrer…
`sonuclar[].bolum`	`string`	Yasama, Yürütme ve İdare, Yargı ya da İlan
`sonuclar[].kategori`	`string`	Alt başlık: YÖNETMELİKLER, TEBLİĞLER, ATAMA KARARLARI…
`sonuclar[].baslik`	`string`	`kisisel` ise başlık yerine kategorisi
`sonuclar[].url`	`string`	resmigazete.gov.tr'deki belge bağlantısı
`sonuclar[].kisisel`	`boolean`	Başlıkta kişi adı geçiyordu; ad saklanmadı
`sonuclar[].etiket`	`"egitim" \| "vergi_maliye" \| "finans" \| "enerji" \| "gida_tarim" \| "saglik" \| "cevre" \| "ulasim" \| "yargi" \| "kamu_personel" \| "kamu_idare" \| "uluslararasi" \| "ticaret_sanayi" \| "diger" \| null`	Otomatik konu etiketi (yanılabilir); sınıflandırılmadıysa null
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

İlaç listesi

ücretsiz (anahtarla)

TİTCK SKRS e-reçete listesi (haftalık) ve referans bazlı ilaç fiyat listesi (GKF, €), koda gömülü; yanıttaki `skrsDonemi` hangi haftanın verisi olduğunu söyler. Eczane satış fiyatı (TL) yok: o liste girişe bağlı. Tıbbi tavsiye değildir.

GET/v1/ilac/ara

ücretsiz (anahtarla)

İlaç ara: barkod, ad, ATC (ücretsiz)

Anahtar gerekli

TİTCK SKRS e-reçete listesindeki ilaç ve farmasötik ürünler (haftalık): barkod, ATC kodu ve etkin madde, firma, reçete türü (Normal/Kırmızı/Turuncu/Mor/Yeşil), aktif/pasif. Referans bazlı listedeki gerçek kaynak fiyat (gkfEuro, €) ad eşlemesiyle; eşleşmeyen üründe null. Eczane satış fiyatı yok (TİTCK fiyat listesi girişe bağlı). ara, barkod ya da atc gerekli; barkodla aranınca varsayılan durum hepsi, yoksa aktif.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`	Ürün adı ya da etkin maddedeki sözcükler (hepsi)
`barkod`	sorgu	`string`
`atc`	sorgu	`string`	ATC kodu ya da başı (N02)
`durum`	sorgu	`"aktif" \| "pasif" \| "hepsi"`
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/ilac/ara?ara=parol&barkod=8699578095307&atc=N02BE01&durum=…&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersiz ya da arama ölçütü yokHata
401Anahtar yok ya da geçersizHata
404barkod listede yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`sayfa`	`integer`
`limit`	`integer`
`ilaclar`	`object[]`
`ilaclar[].ad`	`string`
`ilaclar[].barkod`	`string`
`ilaclar[].atcKodu`	`string \| null`
`ilaclar[].atcAdi`	`string \| null`
`ilaclar[].firma`	`string \| null`
`ilaclar[].receteTuru`	`"Normal" \| "Kırmızı" \| "Turuncu" \| "Mor" \| "Yeşil" \| null`
`ilaclar[].durum`	`"aktif" \| "pasif"`
`ilaclar[].temelIlac`	`object \| null`
`ilaclar[].listeTarihi`	`string \| null (date)`
`ilaclar[].gkfEuro`	`number \| null`
`kaynak`	`string`
`kaynakUrl`	`string[]`
`lisans`	`string`
`guncelleme`	`string (date)`
`skrsDonemi`	`string \| null`
`gkfTarihi`	`string \| null (date)`
`uyari`	`string`

İl kartı ve bölgeler

ücretsiz (anahtarla)

Koda gömülü; istek anında dışarıya gidilmez. Yüzölçümü TÜİK nüfusu ve yoğunluğundan türetilir (göl ve baraj yüzeyi hariç). Merkez koordinatı yaklaşık, resmî değil. Rakım Copernicus DEM GLO-90 yüzey modelinden (bina ve ağaç dahil), MGM istasyon rakımı değildir; atıf yanıtta `rakimKaynak` alanında. Coğrafi bölge idari birim değildir.

GET/v1/il/bolgelerYedi coğrafi bölge ve illeri (ücretsiz)
GET/v1/il/ibbsİBBS/NUTS bölge birimleri (ücretsiz)
GET/v1/il/{il}/ilcelerİlin ilçeleri, nüfusu ve koordinatı (ücretsiz)
GET/v1/il/{il}İl bilgi kartı (ücretsiz)

GET/v1/il/bolgeler

ücretsiz (anahtarla)

Yedi coğrafi bölge ve illeri (ücretsiz)

Anahtar gerekli

Marmara, Ege, Akdeniz, İç Anadolu, Karadeniz, Doğu Anadolu, Güneydoğu Anadolu; her bölgenin illeri ve toplam nüfusu. Coğrafi bölge idari bir birim değildir — resmî istatistik bölgesi için /v1/il/ibbs.

Örnek istek

curl "$KILAVUZ/v1/il/bolgeler" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`bolgeler`	`object[]`
`bolgeler[].ad`	`string`
`bolgeler[].ilSayisi`	`integer`
`bolgeler[].nufus`	`integer`
`bolgeler[].iller`	`object[]`
`kaynak`	`string`
`guncelleme`	`string`
`not`	`string`

GET/v1/il/ibbs

ücretsiz (anahtarla)

İBBS/NUTS bölge birimleri (ücretsiz)

Anahtar gerekli

TÜİK İstatistiki Bölge Birimleri Sınıflaması: Düzey 1 (12 bölge, TR1…TRC), Düzey 2 (26 alt bölge) ve Düzey 3 (81 il). AB fonu, istatistik raporlaması ve bölgesel kırılım için. Düzey 3'te plaka de döner.

Parametreler
Ad	Yer	Tip	Açıklama
`duzey`	sorgu	`"1" \| "2" \| "3"`	Varsayılan 3 (il)

Örnek istek

curl "$KILAVUZ/v1/il/ibbs?duzey=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400duzey geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`duzey`	`integer`
`toplam`	`integer`
`birimler`	`IbbsBirimi[]`
`kaynak`	`string`
`guncelleme`	`string`
`lisans`	`string`
`not`	`string`

GET/v1/il/{il}/ilceler

ücretsiz (anahtarla)

İlin ilçeleri, nüfusu ve koordinatı (ücretsiz)

Anahtar gerekli

İlin tüm ilçeleri: TÜİK ADNKS nüfusu, yıllık artış hızı ve yaklaşık merkez koordinatı. Koordinat sokak sicilindeki noktaların medyanı (resmî ilçe merkezi değil); yeterli nokta yoksa merkez: null.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	yol	`string`	Plaka ya da il adı

Örnek istek

curl "$KILAVUZ/v1/il/<il>/ilceler" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
404il bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`string`
`plaka`	`integer`
`yil`	`integer`
`toplam`	`integer`
`nufus`	`integer`
`ilceler`	`IlceNufusu[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`lisans`	`string`
`not`	`string`

GET/v1/il/{il}

ücretsiz (anahtarla)

İl bilgi kartı (ücretsiz)

Anahtar gerekli

Plakadan ya da il adından tek çağrıda: coğrafi bölge, İBBS/NUTS Düzey 1-2-3 kodu, telefon alan kodu, TÜİK nüfusu (il/ilçe merkezi ve belde/köy kırılımıyla), nüfus yoğunluğu, yüzölçümü, merkez koordinatı, rakım (yüzey modelinden, yaklaşık), komşu iller, ilçe sayısı, posta kodu aralığı ve büyükşehir olup olmadığı.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	yol	`string`	Plaka ("42", "06") ya da il adı ("Konya", "afyon")

Örnek istek

curl "$KILAVUZ/v1/il/<il>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
404il bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`IlKarti`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`lisans`	`string`
`olguKaynak`	`string`
`rakimKaynak`	`object`
`rakimKaynak.kaynak`	`string`
`rakimKaynak.lisans`	`string`
`rakimKaynak.yontem`	`string`
`not`	`string`

Nüfus

ücretsiz (anahtarla)

TÜİK Adrese Dayalı Nüfus Kayıt Sistemi 2025 sonuçları. İl serisi 2000–2025 (2007 öncesi TÜİK tahmini); ilçede yalnız son yıl.

GET/v1/nufus

ücretsiz (anahtarla)

İl nüfusu, yıllara göre seri (ücretsiz)

Anahtar gerekli

TÜİK ADNKS il nüfusu ve 2000'den bu yana yıllık seri. yil verilirse yalnız o yıl. ilce verilirse ilçe nüfusu döner — ilçede yalnız son yıl var, TÜİK geçmiş yılların ilçe ekini yayımdan kaldırıyor.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`	Plaka ya da il adı
`ilce`	sorgu	`string`
`yil`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/nufus?il=Bursa&ilce=Nilüfer&yil=2015" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il gerekli ya da yil geçersizHata
401Anahtar yok ya da geçersizHata
422il ya da ilçe bulunamadı, ya da istenen yıl seride yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`string`
`plaka`	`integer`
`ilce`	`string`
`yil`	`integer`
`nufus`	`integer`
`yillikArtisHizi`	`number \| null`
`yogunluk`	`number`
`ilceSayisi`	`integer`
`seri`	`NufusYili[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`lisans`	`string`
`not`	`string`

Vergi ve finans

Kurlar, altın, enflasyon, vergi dilimleri, bordro ve tazminat; tapu, emlak, damga, veraset ve MTV hesabı; harçlar, avukatlık ve noter ücretleri, trafik cezaları ve vergi daireleri. Değerler resmî belgelerden; ikincil kaynaktan alınanlar notta işaretli. Bilgilendirme amaçlıdır.

TCMB kuru

ücretsiz (anahtarla)

GET/v1/kurTCMB döviz kurları (ücretsiz)
POST/v1/kur/cevirPara birimi çevir (TCMB kuru, ücretsiz)
GET/v1/kur/ecbECB euro referans kurları (ücretsiz)

GET/v1/kur

ücretsiz (anahtarla)

TCMB döviz kurları (ücretsiz)

Anahtar gerekli

Tatil/hafta sonunda en yakın önceki iş gününe düşer; geriyeDusuldu bunu söyler. TCMB ticari kullanımı yazılı izne bağlıyor; izin gelene kadar 0 kredi, not alanıyla.

Parametreler
Ad	Yer	Tip	Açıklama
`tarih`	sorgu	`string (date)`	YYYY-AA-GG

Örnek istek

curl "$KILAVUZ/v1/kur?tarih=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih biçimi hatalıHata
401Anahtar yok ya da geçersizHata
404Yayın bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`kaynak`	`object`
`veriKaynagi`	`string`	`kaynak` ile aynı
`not`	`string`
`tarih`	`string`
`istenenTarih`	`string`
`geriyeDusuldu`	`boolean`
`bultenNo`	`string \| null`
`kurlar`	`Kur[]`

POST/v1/kur/cevir

ücretsiz (anahtarla)

Para birimi çevir (TCMB kuru, ücretsiz)

Anahtar gerekli

Yanıttaki kaynak kaynak para birimidir; veri kaynağı veriKaynagi (TCMB).

İstek gövdesi
Alan	Tip	Açıklama
`tutar`zorunlu	`number`
`kaynak`zorunlu	`string`
`hedef`zorunlu	`string`
`kurTipi`	`"alis" \| "satis" \| "efektifAlis" \| "efektifSatis"`	varsayılan "satis"
`tarih`	`string (date)`

Örnek istek

curl -X POST "$KILAVUZ/v1/kur/cevir" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"tutar":100,"kaynak":"USD","hedef":"TRY"}'

Yanıtlar

200Başarılı
400Eksik alan, bilinmeyen para birimi ya da yayımlanmamış kurHata
401Anahtar yok ya da geçersizHata
404Yayın bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`veriKaynagi`	`object`
`not`	`string`
`tutar`	`number`
`kaynak`	`string`
`hedef`	`string`
`sonuc`	`number`
`kurTipi`	`string`
`tarih`	`string`
`geriyeDusuldu`	`boolean`
`kullanilanKur`	`object`
`kullanilanKur.kaynak`	`number`
`kullanilanKur.hedef`	`number`

GET/v1/kur/ecb

ücretsiz (anahtarla)

ECB euro referans kurları (ücretsiz)

Anahtar gerekli

29 para birimi, ECB iş günlerinde ~16:00 CET yayımlar. baz EUR ise değerler ECB'nin yayımladığı gibi; başka bazda ECB kurlarından hesaplanır ve her kurda hesaplanan: true olur. Bu veri ecb.europa.eu'dan ücretsiz alınabilir.

Parametreler
Ad	Yer	Tip	Açıklama
`baz`	sorgu	`string`	Üç harfli kod, örn. TRY

Örnek istek

curl "$KILAVUZ/v1/kur/ecb?baz=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400baz geçersiz ya da ECB listesinde yokHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata
503ECB yayını alınamıyorHata

Yanıt alanları
`kaynak`	`string`
`not`	`string`
`hesaplamaNotu`	`string`	Yalnız EUR dışı bazda
`tarih`	`string`
`baz`	`string`
`kurlar`	`object[]`
`kurlar[].kod`	`string`
`kurlar[].oran`	`number`	1 baz = oran kod
`kurlar[].hesaplanan`	`boolean`

Altın ve serbest piyasa

1 kredi

doviz.com serbest piyasa (kuyumcu, döviz bürosu) alış-satış fiyatı; banka, Kapalıçarşı ve Borsa İstanbul fiyatından farklıdır. Ons ABD doları, gerisi TL; `saat` kaynağın son fiyat saati. 2 dk önbellek; kaynak düşerse 6 saate kadar eski fiyat `bayat: true`.

GET/v1/altin/fiyat

1 kredi

Altın ve serbest piyasa döviz fiyatı

Anahtar gerekli

Serbest piyasa altın (gram, has, çeyrek, yarım, tam, cumhuriyet, ata, 14/18/22 ayar, ons, gümüş…) ve döviz alış/satış fiyatları. Kaynak doviz.com sayfaları, istek anında, en çok 2 dakika önbellek; kaynak düşerse 6 saate kadar eski veri bayat: true, hiç yoksa 503 (kredi düşmez). Banka, Kapalıçarşı ve Borsa İstanbul fiyatı değildir.

Parametreler
Ad	Yer	Tip	Açıklama
`urun`	sorgu	`string`	Virgüllü ürün kodu ya da kısa ad (gram, has, ceyrek, yarim, tam, cumhuriyet, ata, ons, bilezik); boşsa hepsi
`doviz`	sorgu	`string`	Virgüllü döviz kodu, "hepsi" ya da "yok"; varsayılan USD,EUR,GBP,CHF

Örnek istek

curl "$KILAVUZ/v1/altin/fiyat?urun=gram,ceyrek,cumhuriyet&doviz=USD,EUR" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400doviz listesi geçersizHata
401Anahtar yok ya da geçersizHata
422ürün bulunamadı (geçerli kodlar yanıtta)Hata
429Kredi limiti aşıldıHata
503kaynak yanıt vermiyor ve önbellek yokHata

Yanıt alanları
`altin`	`PiyasaFiyati[]`
`doviz`	`PiyasaFiyati[]`
`kaynak`	`string`
`kaynakUrl`	`string[]`
`lisans`	`string`
`guncelleme`	`string`	Kaynaktan son alınma (ISO 8601)
`bayat`	`boolean`
`not`	`string`

Vergi dairesi

ücretsiz (anahtarla)

GİB listesinden, koda gömülü; ücretsiz. İl merkezindeki daireler ilçe "Merkez" döner (İstanbul ve Ankara'da hangi merkez ilçe olduğu kaynakta yok); adla arayın: ara=kadikoy. Mükellefin kayıtlı olduğu daireyi söylemez.

GET/v1/vergi-dairesiVergi daireleri listesi (GİB)
GET/v1/vergi-dairesi/{kod}Muhasebe birim kodundan vergi dairesi

GET/v1/vergi-dairesi

ücretsiz (anahtarla)

Vergi daireleri listesi (GİB)

Anahtar gerekli

GİB "Defterdarlık ve Vergi Daireleri Listesi": vergi dairesi müdürlükleri (muhasebe birim koduyla), şubeleri ve Eskişehir Defterdarlığı. Süzgeçsiz tüm Türkiye (~1.100 kayıt). guncelleme kaynak listenin tarihi. Ücretsiz.

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`
`ilce`	sorgu	`string`	Kaynaktaki ilçe. İl merkezindeki (büyükşehirde merkez ilçelerdeki) daireler "Merkez"; hangi merkez ilçede oldukları listede yok
`ara`	sorgu	`string`	Ad ya da ilçede sözcük başından, Türkçe karaktersiz
`tur`	sorgu	`"mudurluk" \| "sube" \| "defterdarlik"`

Örnek istek

curl "$KILAVUZ/v1/vergi-dairesi?il=İstanbul&ilce=Silivri&ara=kadikoy&tur=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tur geçersizHata
401Anahtar yok ya da geçersizHata
422il bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`string \| null`
`toplam`	`integer`
`vergiDaireleri`	`VergiDairesi[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`	Kaynak listenin tarihi (YYYY-AA-GG)
`bayat`	`boolean`	Liste 1 yıldan eski
`not`	`string`

GET/v1/vergi-dairesi/{kod}

ücretsiz (anahtarla)

Muhasebe birim kodundan vergi dairesi

Anahtar gerekli

Parametreler
Ad	Yer	Tip	Açıklama
`kod`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/vergi-dairesi/<kod>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400kod 5 haneli değilHata
401Anahtar yok ya da geçersizHata
404kod listede yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`vergiDairesi`	`VergiDairesi`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`
`bayat`	`boolean`
`not`	`string`

TÜFE ve kira

ücretsiz (anahtarla)

TÜİK TÜFE serisi (2025=100), kaynak gösterilerek. Kira artışı TBK m.344 ve 2022–2024 konut tavanından; hukuki tavsiye değildir.

GET/v1/ekonomi/politika-faiziTCMB politika faizi, gecelik oranlar, reeskont/avans (ücretsiz)
GET/v1/ekonomi/ppk-kararlariTCMB PPK kararları (ücretsiz)
GET/v1/ekonomi/gostergelerTÜİK ana göstergeler: son açıklanan değerler (ücretsiz)
GET/v1/ekonomi/bultenlerTÜİK bülten akışı (ücretsiz)
GET/v1/ekonomi/seriTÜİK aylık seri: konut satışı, motorlu taşıt, tarım ÜFE (ücretsiz)
GET/v1/ekonomi/tufeTÜFE: aylık, yıllık, 12 aylık ortalama (TÜİK, ücretsiz)
GET/v1/ekonomi/kira-artisYasal kira artış üst sınırı (TBK m.344, ücretsiz)

GET/v1/ekonomi/politika-faizi

ücretsiz (anahtarla)

TCMB politika faizi, gecelik oranlar, reeskont/avans (ücretsiz)

Anahtar gerekli

Bir hafta vadeli repo (2010'dan politika faizi), gecelik borç alma/verme (2002'den), reeskont ve avans (1990'dan), son PPK kararı ve sonraki toplantı. Koda gömülü TCMB tablosu, guncelleme gününe kadar doğrulandı; tarih verilmezse son hâli. TCMB verisi ücretsiz ve kaynak gösterilerek verilir (not).

Parametreler
Ad	Yer	Tip	Açıklama
`tarih`	sorgu	`string (date)`

Örnek istek

curl "$KILAVUZ/v1/ekonomi/politika-faizi?tarih=2025-06-30" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih geçersizHata
401Anahtar yok ya da geçersizHata
422tarih tablo dışında (doğrulama gününden sonra ya da 1990 öncesi)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`tarih`	`string`
`politikaFaizi`	`object \| null`
`politikaFaizi.ad`	`string`
`politikaFaizi.oran`	`number`
`politikaFaizi.yururluk`	`string`
`politikaFaiziNotu`	`string`
`gecelik`	`object \| null`
`gecelik.borcAlma`	`number`
`gecelik.borcVerme`	`number`
`gecelik.yururluk`	`string`
`reeskont`	`object`
`reeskont.oran`	`number`
`reeskont.yururluk`	`string`
`avans`	`object`
`avans.oran`	`number`
`avans.yururluk`	`string`
`sonKarar`	`object ya da null`
`sonrakiToplanti`	`string \| null`
`uyari`	`string`
`kaynak`	`object`
`guncelleme`	`string (date)`
`not`	`string`

GET/v1/ekonomi/ppk-kararlari

ücretsiz (anahtarla)

TCMB PPK kararları (ücretsiz)

Anahtar gerekli

2026 için bütün toplantılar (sabit bırakılanlar dahil, basın duyurusu bağlantısıyla) ve kalan toplantı günleri; 2010–2025 için yalnız politika faizi değişiklikleri (yürürlük günü, repo ve gecelik oranlar). TCMB verisi (not).

Parametreler
Ad	Yer	Tip	Açıklama
`yil`	sorgu	`integer`	Varsayılan tablonun son yılı

Örnek istek

curl "$KILAVUZ/v1/ekonomi/ppk-kararlari?yil=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400yil geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`toplantilar`	`object[] ya da null`
`toplantiNotu`	`string`
`degisiklikler`	`object[]`
`degisiklikler[].yururluk`	`string`
`degisiklikler[].repo`	`number`
`degisiklikler[].gecelikBorcVerme`	`number \| null`
`degisiklikler[].gecelikBorcAlma`	`number \| null`
`sonrakiToplantilar`	`string[]`
`kaynak`	`object`
`guncelleme`	`string (date)`
`not`	`string`

GET/v1/ekonomi/gostergeler

ücretsiz (anahtarla)

TÜİK ana göstergeler: son açıklanan değerler (ücretsiz)

Anahtar gerekli

TÜİK haber bültenlerinin başlık cümlelerinden okunan son değerler: TÜFE, Yİ-ÜFE, Tarım-ÜFE (yıllık %), işsizlik oranı (mevsim etkisinden arındırılmış), GSYH büyümesi (çeyrek), sanayi üretimi, tüketici ve ekonomik güven endeksi, ihracat/ithalat (milyon USD), konut satışları, trafiğe kaydı yapılan taşıt. Her gösterge dönemi, öteki oranları (degisimler), bülten başlık cümlesi (ozet) ve bülten bağlantısıyla. Toplayıcı günde iki kez yeni bülten arar; tablo boşsa liste boş ve bayat: true.

Parametreler
Ad	Yer	Tip	Açıklama
`kod`	sorgu	`string`	Virgülle ayrılmış gösterge kodları; verilmezse hepsi. Geçerli: tufe, yi-ufe, tarim-ufe, issizlik, gsyh, sanayi-uretim, tuketici-guven, ekonomik-guven, ihracat, ithalat, konut-satis, motorlu-tasit

Örnek istek

curl "$KILAVUZ/v1/ekonomi/gostergeler?kod=tufe,issizlik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400bilinmeyen gösterge koduHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`gostergeler`	`object[]`
`gostergeler[].kod`	`"tufe" \| "yi-ufe" \| "tarim-ufe" \| "issizlik" \| "gsyh" \| "sanayi-uretim" \| "tuketici-guven" \| "ekonomik-guven" \| "ihracat" \| "ithalat" \| "konut-satis" \| "motorlu-tasit"`
`gostergeler[].ad`	`string`
`gostergeler[].donem`	`string`	"2026-08" ya da çeyrek için "2026-Q2"
`gostergeler[].donemAdi`	`string`	Bültendeki yazılışı: "Ağustos 2026"
`gostergeler[].deger`	`number`
`gostergeler[].birim`	`string`	"%", "endeks", "adet", "milyon USD"
`gostergeler[].degisimler`	`object`	Bültende geçen öteki değerler: aylik, yilbasindan, oniKiAylikOrtalama, istihdamOrani, ilkEl…
`gostergeler[].ozet`	`string \| null`	Bültenin başlık cümlesi
`gostergeler[].bulten`	`object`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/ekonomi/bultenler

ücretsiz (anahtarla)

TÜİK bülten akışı (ücretsiz)

Anahtar gerekli

TÜİK'in yayımladığı haber bültenleri ve veri tarayıcısı tabloları, en yeni önce: başlık, dönem, yayım anı, konu, bağlantı. Portalın son 50 yayımından birikiyor (üç yıl tutulur). Bülten içeriği verilmez, yalnız künyesi.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`	Başlıkta parça eşleşme (Türkçe karaktersiz de olur)
`konu`	sorgu	`string`	Konu adında parça eşleşme
`tur`	sorgu	`"bulten" \| "tablo"`
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/ekonomi/bultenler?ara=konut&konu=enflasyon&tur=…&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400ara/konu çok uzun, tur ya da limit geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ara`	`string \| null`
`konu`	`string \| null`
`tur`	`"bulten" \| "tablo" \| null`
`bultenler`	`object[]`
`bultenler[].baslik`	`string`
`bultenler[].donem`	`string \| null`
`bultenler[].yayinTarihi`	`string \| null`
`bultenler[].tur`	`"bulten" \| "tablo"`
`bultenler[].konu`	`string \| null`
`bultenler[].url`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/ekonomi/seri

ücretsiz (anahtarla)

TÜİK aylık seri: konut satışı, motorlu taşıt, tarım ÜFE (ücretsiz)

Anahtar gerekli

TÜİK Veri Tarayıcısı'ndan aylık seri, eskiden yeniye. konut-satis: Türkiye ya da il (il), kırılım toplam, ilk-el, ikinci-el, ipotekli, diger, yabanci. motorlu-tasit: Türkiye, araç türü kırılımı; ölçü kayit ya da silinen. tarim-ufe: Türkiye, genel ve ana gruplar; ölçü endeks, aylik, yilbasindan, yillik, ortalama. Yanıttaki kirilimlar ve olculer seri için geçerli kodları verir.

Parametreler
Ad	Yer	Tip	Açıklama
`ad`zorunlu	sorgu	`"konut-satis" \| "motorlu-tasit" \| "tarim-ufe"`
`il`	sorgu	`string`	Yalnız konut-satis: il adı ya da plaka; verilmezse Türkiye
`kirilim`	sorgu	`string`	Varsayılan toplam (tarim-ufe: genel)
`olcu`	sorgu	`string`	Varsayılan adet / kayit / yillik
`son`	sorgu	`integer`	Aralık verilmezse son kaç ay
`baslangic`	sorgu	`string`
`bitis`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/ekonomi/seri?ad=…&il=Antalya&kirilim=…&olcu=…&son=…&baslangic=…&bitis=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400ad, kirilim, olcu, il, son ya da tarih aralığı geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ad`	`"konut-satis" \| "motorlu-tasit" \| "tarim-ufe"`
`seriAdi`	`string`
`bolge`	`string \| null`
`bolgeKod`	`string`	"TR" ya da İBBS düzey-3 kodu ("TR611")
`kirilim`	`string`
`kirilimAdi`	`string`
`olcu`	`string`
`olcuAdi`	`string`
`noktalar`	`object[]`
`noktalar[].donem`	`string`
`noktalar[].deger`	`number`
`son`	`object ya da null`
`kirilimlar`	`object`
`olculer`	`object`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/ekonomi/tufe

ücretsiz (anahtarla)

TÜFE: aylık, yıllık, 12 aylık ortalama (TÜİK, ücretsiz)

Anahtar gerekli

TÜİK tüketici fiyat endeksi ve dört değişim oranı, 2005'ten bu yana aylık. ay verilmezse son açıklanan ay. son=N ile aya kadar son N ay seride. Yeni ay her ayın 3'ü 10:00'da (TR) TÜİK'ten alınır; TÜİK'e ulaşılamazsa eldeki seri bayat: true ile döner.

Parametreler
Ad	Yer	Tip	Açıklama
`ay`	sorgu	`string`
`son`	sorgu	`integer`	Seri uzunluğu (ay sayısı)

Örnek istek

curl "$KILAVUZ/v1/ekonomi/tufe?ay=2026-08&son=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400ay ya da son geçersizHata
401Anahtar yok ya da geçersizHata
422ay henüz açıklanmadı (`sonAy`) ya da seriden eskiHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ay`	`string`	YYYY-AA
`endeks`	`number`
`aylik`	`number`	Önceki aya göre, %
`aralikaGore`	`number`	Önceki yılın Aralık ayına göre, %
`yillik`	`number`	Önceki yılın aynı ayına göre, %
`oniKiAylikOrtalama`	`number`	12 aylık ortalamalara göre, %
`baz`	`string`	"2025=100"
`seri`	`object[]`
`seri[].ay`	`string`	YYYY-AA
`seri[].endeks`	`number`
`seri[].aylik`	`number`	Önceki aya göre, %
`seri[].aralikaGore`	`number`	Önceki yılın Aralık ayına göre, %
`seri[].yillik`	`number`	Önceki yılın aynı ayına göre, %
`seri[].oniKiAylikOrtalama`	`number`	12 aylık ortalamalara göre, %
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`	TÜİK bülteninin yayım anı
`bayat`	`boolean`	Açıklanmış olması gereken son ay eksik (TÜİK'e ulaşılamadı)
`not`	`string`

GET/v1/ekonomi/kira-artis

ücretsiz (anahtarla)

Yasal kira artış üst sınırı (TBK m.344, ücretsiz)

Anahtar gerekli

TÜFE on iki aylık ortalama değişimi; konutta 11.06.2022–01.07.2024 arası yenilemelerde %25 tavanı. yenileme (kira döneminin başladığı gün) verilirse önceki ayın oranı; ay verilirse o ayın oranı (yenileme izleyen ay); ikisi de yoksa son açıklanan ay. kira verilirse yeni azami kira. Hukuki tavsiye değildir.

Parametreler
Ad	Yer	Tip	Açıklama
`yenileme`	sorgu	`string (date)`
`ay`	sorgu	`string`	TÜFE ayı
`tur`	sorgu	`"konut" \| "isyeri"`	Varsayılan konut
`kira`	sorgu	`number`	Mevcut aylık kira, TL

Örnek istek

curl "$KILAVUZ/v1/ekonomi/kira-artis?yenileme=2026-09-15&ay=…&tur=…&kira=20000" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
422TÜFE ayı henüz açıklanmadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tufeAyi`	`string`
`oniKiAylikOrtalama`	`number`
`tur`	`string`
`yenileme`	`string`
`azamiOran`	`number`	Yüzde
`konutTavani`	`object \| null`
`konutTavani.oran`	`number`
`konutTavani.uygulanir`	`boolean \| null`	null: yenileme gününe bağlı
`kira`	`number \| null`
`yeniAzamiKira`	`number \| null`
`dayanak`	`object`
`dayanak.ustSinir`	`string`
`dayanak.konutTavani`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string`
`bayat`	`boolean`
`not`	`string`
`uyari`	`string`

Vergi ve SGK

0–1 kredi

Değerler resmî belgelerden elle yazıldı; her bölümde geçerlilik ve kaynak. MTV 2026 tutarları ikincil kaynaktan (tebliğin tabloları Resmî Gazete PDF’inde görüntü). Tapu harcı devir eden ve alan için ayrı ayrı binde 20; tapu döner sermaye ücreti yöresel katsayı yayımlanmadığı için hesaplanmaz. Emlak vergisinde matrah (arsa ve bina birim değeri) belediyeden alınır. Doğrulanamayan kalemler `belirsiz: true`. Hukuki ya da mali tavsiye değildir.

GET/v1/vergi/parametrelerYıllık vergi ve SGK parametreleri (ücretsiz)
GET/v1/vergi/gelir-vergisiYıllık matrahtan gelir vergisi (GVK m.103, ücretsiz)
GET/v1/vergi/kdvKDV ekle ya da ayır (ücretsiz)
GET/v1/vergi/mtvMotorlu taşıtlar vergisi (2026 tarifesi, ücretsiz)
GET/v1/vergi/takvimGİB vergi takvimi: beyanname ve ödeme son günleri (ücretsiz)
GET/v1/vergi/oranlarGecikme zammı, tecil faizi, yeniden değerleme oranları (ücretsiz)
GET/v1/vergi/gecikme-zammiVergi borcuna gecikme zammı hesabı (ücretsiz)
GET/v1/vergi/tecil-faiziTecil faizi hesabı (ücretsiz)
GET/v1/vergi/yeniden-degerlemeYeniden değerleme oranı ve güncellenmiş tutar (ücretsiz)
GET/v1/vergi/ozelge/araGİB özelgelerinde tam metin arama
GET/v1/vergi/ozelge/{id}GİB özelgesinin tam metni (ücretsiz)
POST/v1/vergi/tapuTapu harcı hesapla (ücretsiz)
POST/v1/vergi/emlakEmlak vergisi ve değerli konut vergisi (ücretsiz)
POST/v1/vergi/damgaDamga vergisi hesapla (ücretsiz)
POST/v1/vergi/verasetVeraset ve intikal vergisi hesapla (ücretsiz)

GET/v1/vergi/parametreler

ücretsiz (anahtarla)

Yıllık vergi ve SGK parametreleri (ücretsiz)

Anahtar gerekli

Gelir vergisi tarifesi (ücret ve ücret dışı), asgari ücret (brüt, net, işçi/işveren payları), prime esas kazanç alt/üst sınırı, KDV genel oranları. Her bölümde gecerlilik {baslangic, bitis} ve kaynak {belge, rg, url}; asgari ücret yıl içinde değişirse dizide yeni dönem. Bordro (brütten nete) hesabı yok.

Parametreler
Ad	Yer	Tip	Açıklama
`yil`	sorgu	`integer`	Varsayılan içinde bulunulan yıl

Örnek istek

curl "$KILAVUZ/v1/vergi/parametreler?yil=2026" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
422yıl için parametre yok (yanıtta `yillar`)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`gelirVergisiTarifesi`	`object`
`gelirVergisiTarifesi.gecerlilik`	`Gecerlilik`
`gelirVergisiTarifesi.kaynak`	`ResmiKaynak`
`gelirVergisiTarifesi.ucret`	`Dilim[]`
`gelirVergisiTarifesi.ucretDisi`	`Dilim[]`
`asgariUcret`	`object[]`
`asgariUcret[].gecerlilik`	`Gecerlilik`
`asgariUcret[].kaynak`	`ResmiKaynak`
`asgariUcret[].brutAylik`	`number`
`asgariUcret[].brutGunluk`	`number`
`asgariUcret[].netAylik`	`number`
`asgariUcret[].isciSgkOrani`	`number`
`asgariUcret[].isciIssizlikOrani`	`number`
`asgariUcret[].isverenSgkOrani`	`object`
`asgariUcret[].isverenIssizlikOrani`	`number`
`primeEsasKazanc`	`object`
`primeEsasKazanc.gecerlilik`	`Gecerlilik`
`primeEsasKazanc.kaynak`	`ResmiKaynak`
`primeEsasKazanc.gunlukAlt`	`number`
`primeEsasKazanc.gunlukUst`	`number`
`primeEsasKazanc.aylikAlt`	`number`
`primeEsasKazanc.aylikUst`	`number`
`kdvOranlari`	`object`
`kdvOranlari.gecerlilik`	`Gecerlilik`
`kdvOranlari.kaynak`	`ResmiKaynak`
`kdvOranlari.genel`	`number`
`kdvOranlari.birSayiliListe`	`number`
`kdvOranlari.ikiSayiliListe`	`number`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/gelir-vergisi

ücretsiz (anahtarla)

Yıllık matrahtan gelir vergisi (GVK m.103, ücretsiz)

Anahtar gerekli

Tarifeyi yıllık matraha uygular, dilim dökümüyle. İstisna, indirim, kümülatif bordro hesabı yapmaz.

Parametreler
Ad	Yer	Tip	Açıklama
`matrah`zorunlu	sorgu	`number`	Yıllık, TL
`tur`	sorgu	`"ucret" \| "ucret-disi"`	Varsayılan ucret-disi; ücrette 3. dilim geniş
`yil`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/vergi/gelir-vergisi?matrah=500000&tur=…&yil=2026" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400matrah ya da tur geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için parametre yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`tur`	`string`
`matrah`	`number`
`vergi`	`number`
`ortalamaOran`	`number`
`marjinalOran`	`number`
`dokum`	`object[]`
`dokum[].alt`	`number`
`dokum[].ust`	`number \| null`
`dokum[].oran`	`number`
`dokum[].matrah`	`number`
`dokum[].vergi`	`number`
`gecerlilik`	`Gecerlilik`
`kaynak`	`ResmiKaynak`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/kdv

ücretsiz (anahtarla)

KDV ekle ya da ayır (ücretsiz)

Anahtar gerekli

Oran (I) ve (II) sayılı listelere göre kullanıcı seçer; uç hangi malın hangi orana tabi olduğunu söylemez.

Parametreler
Ad	Yer	Tip	Açıklama
`tutar`zorunlu	sorgu	`number`
`oran`	sorgu	`1 \| 10 \| 20`	Varsayılan genel oran
`dahil`	sorgu	`"true" \| "false"`	true: tutar KDV dahil, ayrıştır
`yil`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/vergi/kdv?tutar=1200&oran=…&dahil=…&yil=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tutar, oran ya da dahil geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için parametre yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`oran`	`number`
`kdvHaric`	`number`
`kdv`	`number`
`kdvDahil`	`number`
`gecerlilik`	`Gecerlilik`
`kaynak`	`ResmiKaynak`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/mtv

ücretsiz (anahtarla)

Motorlu taşıtlar vergisi (2026 tarifesi, ücretsiz)

Anahtar gerekli

197 sayılı Kanun m.5/6 ve geçici m.8 tarifeleri (58 Seri No.lu MTV Genel Tebliği). Otomobilde 1/1/2018 ve sonrası tescilliler (I) sayılı tarifeye göre taşıt değeriyle birlikte, öncekiler (I/A) sayılı tarifeye göre yalnız motor hacmi ve yaşla vergilendirilir. deger verilmezse vergi yerine o motor hacmine ait değer bantları döner. Yaş = vergilendirme yılı − model yılı + 1. Taksitler Ocak ve Temmuz.

Parametreler
Ad	Yer	Tip	Açıklama
`tur`	sorgu	`"otomobil" \| "motosiklet" \| "minibus" \| "panelvan" \| "otobus" \| "kamyon"`	Varsayılan otomobil
`modelYili`zorunlu	sorgu	`integer`
`motorHacmi`	sorgu	`number`	cm³; otomobil, motosiklet ve panelvanda zorunlu
`deger`	sorgu	`number`	Taşıt değeri (TL); (I) sayılı tarifede bant seçer
`koltuk`	sorgu	`integer`	Otobüste oturma yeri sayısı
`agirlik`	sorgu	`number`	Kamyon/kamyonet/çekicide azami toplam ağırlık (kg)
`tescilYili`	sorgu	`integer`	2018 öncesi tescilli otomobilde (I/A) tarifesi; verilmezse model yılı kullanılır
`yil`	sorgu	`integer`	Varsayılan 2026; başka yıl 422

Örnek istek

curl "$KILAVUZ/v1/vergi/mtv?tur=…&modelYili=2024&motorHacmi=1600&deger=…&koltuk=…&agirlik=…&tescilYili=…&yil=2026" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tur, modelYili ya da ölçü geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için tarife yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`string`
`yil`	`integer`
`modelYili`	`integer`
`yas`	`integer`
`yasGrubu`	`string`
`tarife`	`"I" \| "I/A" \| "II"`
`olcu`	`object`
`olcu.ad`	`string`
`olcu.deger`	`number`
`olcu.bant`	`string`
`vergi`	`number \| null`	Yıllık TL; değer bandı seçilemediyse null
`taksitler`	`object[]`
`taksitler[].ay`	`string`
`taksitler[].tutar`	`number`
`degerBandi`	`string \| null`
`bantlar`	`object[]`
`bantlar[].deger`	`string`
`bantlar[].vergi`	`number`
`gecerlilik`	`Gecerlilik`
`kaynak`	`ResmiKaynak`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/takvim

ücretsiz (anahtarla)

GİB vergi takvimi: beyanname ve ödeme son günleri (ücretsiz)

Anahtar gerekli

"Bu hafta hangi beyannamelerin son günü?", "Eylül KDV ne zaman ödenir?". Kaynak GİB vergi takvimi; yıl başına istek anında GİB'den (6 saat önbellek, süre uzatmaları yansır), ulaşılamazsa koda gömülü anlık görüntü (durum: gomulu). Aralık ay, hafta, tarih ya da baslangic+bitis (en çok 400 gün) ile; hiçbiri yoksa bugünden 30 gün. Varsayılan kapsam=son-gun: son günü aralıkta olanlar; acik: dönemi aralıkla örtüşenler.

Parametreler
Ad	Yer	Tip	Açıklama
`ay`	sorgu	`string`	YYYY-AA
`hafta`	sorgu	`string`	ISO hafta ya da "bu"
`tarih`	sorgu	`string (date)`	Tek gün
`baslangic`	sorgu	`string (date)`
`bitis`	sorgu	`string (date)`
`ara`	sorgu	`string`	Başlık, vergi türü ya da açıklamada geçen metin
`konu`	sorgu	`string`	Beyan ve Ödeme, Ödeme, Bildirim, Berat…
`kapsam`	sorgu	`"son-gun" \| "acik"`

Örnek istek

curl "$KILAVUZ/v1/vergi/takvim?ay=2026-09&hafta=2026-W39&tarih=2026-09-18&baslangic=2026-09-18&bitis=2026-09-18&ara=katma değer&konu=Beyan ve Ödeme&kapsam=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih/ay/hafta ya da kapsam geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata
503GİB'e ulaşılamadı ve gömülü kopyada bu yıl yokHata

Yanıt alanları
`sorgu`	`object`
`sorgu.ne`	`string`
`sorgu.baslangic`	`string`
`sorgu.bitis`	`string`
`sorgu.kapsam`	`string`
`sorgu.ara`	`string \| null`
`sorgu.konu`	`string \| null`
`sayi`	`integer`
`kayitlar`	`object[]`
`kayitlar[].id`	`integer`
`kayitlar[].baslik`	`string`
`kayitlar[].aciklama`	`string \| null`
`kayitlar[].baslangic`	`string (date)`
`kayitlar[].sonGun`	`string (date)`
`kayitlar[].vergiTuru`	`string \| null`
`kayitlar[].donem`	`string \| null`
`kayitlar[].konu`	`string \| null`
`kayitlar[].oncelik`	`integer \| null`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`durum`	`"canli" \| "bayat" \| "gomulu"`
`eksikYil`	`integer[]`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/oranlar

ücretsiz (anahtarla)

Gecikme zammı, tecil faizi, yeniden değerleme oranları (ücretsiz)

Anahtar gerekli

GİB "Yararlı Bilgiler" tabloları: gecikme zammı (6183 m.51, aylık %; 20.01.2000'den), tecil faizi (6183 m.48, yıllık %; 25.01.2000'den), yeniden değerleme oranı (VUK mük. m.298; 2010–). tarih verilirse yalnız o gün geçerli oran.

Parametreler
Ad	Yer	Tip	Açıklama
`tur`	sorgu	`"gecikme-zammi" \| "tecil-faizi" \| "yeniden-degerleme"`	Yoksa üçü
`tarih`	sorgu	`string (date)`	Geçerli oran; yoksa bugün ve bütün dönemler

Örnek istek

curl "$KILAVUZ/v1/vergi/oranlar?tur=…&tarih=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tur ya da tarih geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tarih`	`string`
`gecikmeZammi`	`object`
`gecikmeZammi.birim`	`string`
`gecikmeZammi.dayanakKanun`	`string`
`gecikmeZammi.gecerli`	`OranDonemi`
`gecikmeZammi.donemler`	`OranDonemi[]`
`gecikmeZammi.kaynakUrl`	`string`
`gecikmeZammi.not`	`string`
`tecilFaizi`	`object`
`tecilFaizi.birim`	`string`
`tecilFaizi.dayanakKanun`	`string`
`tecilFaizi.gecerli`	`OranDonemi`
`tecilFaizi.donemler`	`OranDonemi[]`
`tecilFaizi.kaynakUrl`	`string`
`yenidenDegerleme`	`object`
`yenidenDegerleme.birim`	`string`
`yenidenDegerleme.dayanakKanun`	`string`
`yenidenDegerleme.kaynakUrl`	`string`
`yenidenDegerleme.not`	`string`
`yenidenDegerleme.oranlar`	`object[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`uyari`	`string`

GET/v1/vergi/gecikme-zammi

ücretsiz (anahtarla)

Vergi borcuna gecikme zammı hesabı (ücretsiz)

Anahtar gerekli

6183 s.K. m.51: vadeyi izleyen her tam ay için o dönemin aylık oranı, ay kesri için günlük (oran/30); oran değiştiyse süre bölünür, parça parça döküm. Yaklaşık hesap, kuruş farkı olabilir.

Parametreler
Ad	Yer	Tip	Açıklama
`tutar`zorunlu	sorgu	`number`	Amme alacağının aslı, TL
`vade`zorunlu	sorgu	`string (date)`	Son ödeme günü (2000-01-20 ve sonrası)
`odeme`	sorgu	`string (date)`	Varsayılan bugün

Örnek istek

curl "$KILAVUZ/v1/vergi/gecikme-zammi?tutar=10000&vade=2025-06-26&odeme=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tutar ya da tarih geçersizHata
401Anahtar yok ya da geçersizHata
422vade 20.01.2000 öncesiHata
429Kredi limiti aşıldıHata

Yanıt alanları
`anapara`	`number`
`vade`	`string`
`odeme`	`string`
`gecikmeGunu`	`integer`
`gecikmeZammi`	`number`
`toplam`	`number`
`dokum`	`OranParcasi[]`
`yontem`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/tecil-faizi

ücretsiz (anahtarla)

Tecil faizi hesabı (ücretsiz)

Anahtar gerekli

6183 s.K. m.48: yıllık oranla gün esaslı basit faiz (tutar × oran × gün / 36500); oran değiştiyse süre bölünür.

Parametreler
Ad	Yer	Tip
`tutar`zorunlu	sorgu	`number`
`baslangic`zorunlu	sorgu	`string (date)`
`bitis`zorunlu	sorgu	`string (date)`

Örnek istek

curl "$KILAVUZ/v1/vergi/tecil-faizi?tutar=50000&baslangic=2026-01-15&bitis=2026-07-15" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tutar ya da tarih geçersizHata
401Anahtar yok ya da geçersizHata
422başlangıç 25.01.2000 öncesiHata
429Kredi limiti aşıldıHata

Yanıt alanları
`anapara`	`number`
`baslangic`	`string`
`bitis`	`string`
`gun`	`integer`
`tecilFaizi`	`number`
`toplam`	`number`
`dokum`	`OranParcasi[]`
`yontem`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/yeniden-degerleme

ücretsiz (anahtarla)

Yeniden değerleme oranı ve güncellenmiş tutar (ücretsiz)

Anahtar gerekli

VUK mükerrer m.298 oranı; yil oranın ait olduğu yıl, ertesi yılın maktu tutarlarına uygulanır. Yeni tutar yuvarlanmaz.

Parametreler
Ad	Yer	Tip	Açıklama
`yil`	sorgu	`integer`	Varsayılan en son ilan edilen yıl
`tutar`	sorgu	`number`

Örnek istek

curl "$KILAVUZ/v1/vergi/yeniden-degerleme?yil=2025&tutar=1000" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tutar geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için oran yok (yanıtta `yillar`)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`oran`	`number`
`dayanak`	`string`
`uygulanacakYil`	`integer`
`tutar`	`number`
`yeniTutar`	`number`
`kaynak`	`string`
`kaynakUrl`	`string`
`guncelleme`	`string`
`not`	`string`
`uyari`	`string`

GET/v1/vergi/ozelge/ara

1 kredi

GİB özelgelerinde tam metin arama

Anahtar gerekli

Gelir İdaresi'nin yayımladığı özelgelerde (~18.000) konu + metin araması. Türkçe karakter ve büyük/küçük harf ayrımı yok; sözcüklerin ilk 5 harfi eşleşir ("harcından" = "harcı"), 5 harften kısa sözcük ön ek. Bütün sözcükler geçmeli. Konusunda geçenler önce, sonra yeniden eskiye. En çok 50 sonuç, 20 sayfa. Sonuç boşsa kredi düşmez. Metinler kişisel veri taramasından geçmiştir.

Parametreler
Ad	Yer	Tip	Açıklama
`q`zorunlu	sorgu	`string`
`kanun`	sorgu	`string`	Kanun numarası (3065) ya da kısaltma: kdv, gv, kv, vuk, harc, damga, mtv, otv, emlak, veraset, amme, bsmv, smmm
`yil`	sorgu	`integer`	Özelge tarihinin yılı
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/vergi/ozelge/ara?q=riskli yapı tapu harcı&kanun=kdv&yil=…&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400q boş / kanun, yil, limit ya da sayfa geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`q`	`string`
`kanun`	`string \| null`
`yil`	`integer \| null`
`sayfa`	`integer`
`limit`	`integer`
`toplam`	`integer`	Bütün eşleşen özelge sayısı
`sonuclar`	`object[]`
`sonuclar[].id`	`integer`	GİB kayıt kimliği; tam metin için /v1/vergi/ozelge/{id}
`sonuclar[].no`	`string \| null`	Özelge (evrak) sayısı
`sonuclar[].tarih`	`string \| null (date)`
`sonuclar[].konu`	`string`
`sonuclar[].kanun`	`object`
`sonuclar[].maddeler`	`string[]`
`sonuclar[].birim`	`string \| null`	Özelgeyi veren vergi dairesi başkanlığı / defterdarlık
`sonuclar[].url`	`string`	gib.gov.tr sayfası
`sonuclar[].ozet`	`string`	İlk eşleşmenin çevresi
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/vergi/ozelge/{id}

ücretsiz (anahtarla)

GİB özelgesinin tam metni (ücretsiz)

Anahtar gerekli

Arama sonucundaki id ile tam metin. maskelenen: yayın öncesi taramada * ile kapatılan bulgu sayısı.

Parametreler
Ad	Yer	Tip	Açıklama
`id`zorunlu	yol	`integer`

Örnek istek

curl "$KILAVUZ/v1/vergi/ozelge/<id>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400id geçersizHata
401Anahtar yok ya da geçersizHata
404bu id ile özelge yokHata
429Kredi limiti aşıldıHata
503arşiv okunamıyorHata

Yanıt alanları
`id`	`integer`	GİB kayıt kimliği; tam metin için /v1/vergi/ozelge/{id}
`no`	`string \| null`	Özelge (evrak) sayısı
`tarih`	`string \| null (date)`
`konu`	`string`
`kanun`	`object`
`kanun.no`	`string \| null`
`kanun.ad`	`string \| null`
`maddeler`	`string[]`
`birim`	`string \| null`	Özelgeyi veren vergi dairesi başkanlığı / defterdarlık
`url`	`string`	gib.gov.tr sayfası
`metin`	`string`
`maskelenen`	`integer`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

POST/v1/vergi/tapu

ücretsiz (anahtarla)

Tapu harcı hesapla (ücretsiz)

Anahtar gerekli

Alıcı ve satıcıdan ayrı ayrı binde 20; matrah emlak vergisi değerinden az olamaz (Harçlar K. m.63).

İstek gövdesi
Alan	Tip	Açıklama
`satisBedeli`zorunlu	`number`
`emlakVergisiDegeri`	`number`
`taraf`	`"alici" \| "satici" \| "ikisi"`	Varsayılan "ikisi"
`indirimli`	`boolean`	Oran indirimi varsayımı (binde 15); 2026 yılında yürürlükte indirim yok

Örnek istek

curl -X POST "$KILAVUZ/v1/vergi/tapu" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"satisBedeli":4500000,"taraf":"alici"}'

Yanıtlar

200Başarılı
400satisBedeli, taraf ya da indirimli geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`matrah`	`number`
`matrahKaynagi`	`string`
`binde`	`number`
`taraf`	`string`
`aliciHarci`	`number`
`saticiHarci`	`number`
`toplamHarc`	`number`
`odenecek`	`number`
`asgariUygulandi`	`boolean`
`donerSermaye`	`object`	Harç değil; yöresel katsayı yayımlanmadığı için tutar hesaplanmaz
`gecerlilik`	`Gecerlilik`
`kaynak`	`ResmiKaynak[]`
`guncelleme`	`string (date)`
`aciklama`	`string`
`not`	`string`
`uyari`	`string`

POST/v1/vergi/emlak

ücretsiz (anahtarla)

Emlak vergisi ve değerli konut vergisi (ücretsiz)

Anahtar gerekli

Mesken binde 1, işyeri binde 2, arsa binde 3, arazi binde 1; büyükşehirde iki katı (1319 s.K. m.8 ve m.18).

İstek gövdesi
Alan	Tip	Açıklama
`rayicDeger`zorunlu	`number`	Belediyenin belirlediği vergi değeri, TL
`tur`zorunlu	`"konut" \| "isyeri" \| "arsa" \| "arazi"`
`buyuksehir`	`boolean`
`yil`	`integer`	Şimdilik yalnız 2026

Örnek istek

curl -X POST "$KILAVUZ/v1/vergi/emlak" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"rayicDeger":3200000,"tur":"konut","buyuksehir":true}'

Yanıtlar

200Başarılı
400rayicDeger, tur ya da buyuksehir geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için oran ve had yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`tur`	`string`
`turAdi`	`string`
`rayicDeger`	`number`
`buyuksehir`	`boolean`
`binde`	`number`
`vergi`	`number`
`taksitler`	`object[]`
`taksitler[].sira`	`integer`
`taksitler[].tutar`	`number`
`taksitler[].donem`	`string`
`degerliKonutVergisi`	`object`
`degerliKonutVergisi.tabi`	`boolean`
`degerliKonutVergisi.esik`	`number`
`degerliKonutVergisi.matrah`	`number`
`degerliKonutVergisi.vergi`	`number`
`degerliKonutVergisi.binde`	`number \| null`
`degerliKonutVergisi.not`	`string`
`gecerlilik`	`Gecerlilik`
`kaynak`	`ResmiKaynak[]`
`guncelleme`	`string (date)`
`aciklama`	`string`
`not`	`string`
`uyari`	`string`

POST/v1/vergi/damga

ücretsiz (anahtarla)

Damga vergisi hesapla (ücretsiz)

Anahtar gerekli

Konut kira sözleşmesi istisnadır (tur: "kira-konut"). 2026 azami tutar 29.115.961,10 TL (488 s.K. m.14).

İstek gövdesi
Alan	Tip	Açıklama
`tur`zorunlu	`"sozlesme" \| "kira" \| "kira-konut" \| "ihale" \| "ihale-sozlesmesi" \| "maas" \| "kefalet" \| "fesihname" \| "ikinci-el-arac"`
`tutar`zorunlu	`number`	Kirada sözleşme süresinin tamamına ait bedel

Örnek istek

curl -X POST "$KILAVUZ/v1/vergi/damga" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"tur":"sozlesme","tutar":250000}'

Yanıtlar

200Başarılı
400tur ya da tutar geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`string`
`ad`	`string`
`matrah`	`number`
`binde`	`number`
`hamVergi`	`number`
`azami`	`number`
`azamiUygulandi`	`boolean`
`vergi`	`number`
`istisna`	`boolean`
`dayanak`	`string`
`turler`	`string[]`
`azamiTutar`	`number`
`maktuKalemler`	`object[]`
`maktuKalemler[].ad`	`string`
`maktuKalemler[].tutar`	`number`
`maktuKalemler[].dayanak`	`string`
`gecerlilik`	`Gecerlilik`
`kaynak`	`ResmiKaynak[]`
`guncelleme`	`string (date)`
`aciklama`	`string`
`not`	`string`
`uyari`	`string`

POST/v1/vergi/veraset

ücretsiz (anahtarla)

Veraset ve intikal vergisi hesapla (ücretsiz)

Anahtar gerekli

İstisnayı düşüp artan oranlı tarifeyi dilim dilim uygular (7338 s.K.). İstisna her mirasçının hissesine ayrı uygulanır.

İstek gövdesi
Alan	Tip	Açıklama
`tutar`zorunlu	`number`	Mirasçıya isabet eden hisse, TL
`tur`	`"veraset" \| "ivazsiz"`	Varsayılan "veraset"
`yakinlik`	`"furu" \| "es-furu-var" \| "es-furu-yok" \| "diger"`	Varsayılan "diger"

Örnek istek

curl -X POST "$KILAVUZ/v1/vergi/veraset" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"tutar":6000000,"tur":"veraset","yakinlik":"furu"}'

Yanıtlar

200Başarılı
400tutar, tur ya da yakinlik geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`string`
`yakinlik`	`string \| null`
`tutar`	`number`
`istisna`	`number`
`istisnaAdi`	`string`
`matrah`	`number`
`dilimler`	`object[]`
`dilimler[].dilim`	`string`
`dilimler[].oran`	`number`
`dilimler[].matrah`	`number`
`dilimler[].vergi`	`number`
`vergi`	`number`
`efektifOran`	`number`
`taksit`	`object`
`taksit.sayi`	`integer`
`taksit.tutar`	`number`
`taksit.donem`	`string`
`tarife`	`object[]`
`istisnalar`	`object`
`beyanSuresi`	`string`
`gecerlilik`	`Gecerlilik`
`kaynak`	`ResmiKaynak[]`
`guncelleme`	`string (date)`
`aciklama`	`string`
`not`	`string`
`uyari`	`string`

Bordro ve tazminat

ücretsiz (anahtarla)

Brütten nete, netten brüte, kıdem, ihbar, yıllık izin ve asgari ücret tarihçesi. Teşvikler, eksik gün ve kısmi süreli çalışma yok. Kıdem tavanı tarihçesi ve SGDP oranı ikincil kaynaktan. Bilgilendirme amaçlıdır; kesin hesap için mali müşavire danışın.

POST/v1/bordro/hesaplaBrütten nete / netten brüte ücret (ücretsiz)
POST/v1/bordro/tazminatKıdem, ihbar ve yıllık izin ücreti (ücretsiz)
GET/v1/bordro/asgari-ucretAsgari ücret tarihçesi (ücretsiz)

POST/v1/bordro/hesapla

ücretsiz (anahtarla)

Brütten nete / netten brüte ücret (ücretsiz)

Anahtar gerekli

Aylık bordro: SGK ve işsizlik işçi payı, kümülatif matrahla gelir vergisi, asgari ücret gelir ve damga vergisi istisnası, damga vergisi, isteğe bağlı otomatik katılım (OKS) kesintisi, işveren payları ve işverene maliyet. brut ya da net alanlarından tam olarak biri verilir; net verilirse brüt aranır. aylik: true ile o aydan yıl sonuna 12 aylık tablo ve yıllık toplam. Girdi saklanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`brut`	`number`	Aylık brüt ücret; `net` ile birlikte verilemez
`net`	`number`	Hedef net ücret; brüt aranır
`ay`	`integer`	Varsayılan 1. 1–12
`yil`	`integer`
`kumulatifMatrah`	`number`	Önceki aylardan devreden gelir vergisi matrahı
`engelIndirimi`	`number`	Aylık engellilik indirimi (TL)
`engelDerecesi`	`1 \| 2 \| 3`	GVK m.31 derecesi; tutar tebliğden okunur
`sgkTuru`	`"4a" \| "emekli"`	"emekli": sosyal güvenlik destek primi
`bes`	`boolean`	Otomatik katılım çalışan katkı payı kesilsin mi
`besPuanIndirimi`	`boolean`	İşveren SGK payında 5 puanlık indirim (5510 m.81/ı)
`aylik`	`boolean`	12 aylık tablo

Örnek istek

curl -X POST "$KILAVUZ/v1/bordro/hesapla" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"brut":75000,"ay":1,"yil":2026}'

Yanıtlar

200Başarılı
400girdi geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için parametre yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`yon`	`"brutten-nete" \| "netten-brute"`
`sgkTuru`	`string`
`brut`	`number`
`sgkMatrahi`	`number`
`sgkIsci`	`number`
`issizlikIsci`	`number`
`gelirVergisiMatrahi`	`number`
`kumulatifMatrah`	`number`
`hesaplananGelirVergisi`	`number`
`asgariUcretGelirVergisiIstisnasi`	`number`
`gelirVergisi`	`number`
`hesaplananDamgaVergisi`	`number`
`asgariUcretDamgaIstisnasi`	`number`
`damgaVergisi`	`number`
`besKesintisi`	`number`
`kesintiToplami`	`number`
`net`	`number`
`isverenSgk`	`number`
`isverenIssizlik`	`number`
`isvereneMaliyet`	`number`
`aylik`	`object[]`	`aylik: true` verildiyse 12 aylık tablo
`yillikToplam`	`object`
`parametreler`	`object`
`kaynak`	`object`
`not`	`string`

POST/v1/bordro/tazminat

ücretsiz (anahtarla)

Kıdem, ihbar ve yıllık izin ücreti (ücretsiz)

Anahtar gerekli

Kıdem tazminatı (1475 s.K. m.14, dönem tavanıyla sınırlı, yalnız damga vergisi kesilir), ihbar tazminatı (4857 m.17 önelleri; gelir + damga) ve isteğe bağlı kullanılmayan yıllık izin ücreti (4857 m.53/59; SGK + gelir + damga). cikisNedeni hangi kalemin doğduğunu belirler. Girdi saklanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`iseGiris`zorunlu	`string (date)`
`isCikis`zorunlu	`string (date)`
`brutUcret`zorunlu	`number`	Aylık çıplak brüt ücret
`ekOdemeler`	`number`	Giydirilmiş ücrete eklenen aylık düzenli ödemeler
`cikisNedeni`	`"isveren_fesih" \| "isveren_hakli_fesih" \| "isci_istifa" \| "isci_hakli_fesih" \| "emeklilik" \| "askerlik" \| "evlilik" \| "olum" \| "belirli_sure_bitimi"`	Varsayılan isveren_fesih
`kullanilmayanIzinGun`	`integer`	0–1000
`kumulatifMatrah`	`number`
`tavanTutari`	`number`	Kıdem tavanı tabloda yoksa elle

Örnek istek

curl -X POST "$KILAVUZ/v1/bordro/tazminat" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"iseGiris":"2015-03-01","isCikis":"2026-09-30","brutUcret":60000}'

Yanıtlar

200Başarılı
400tarih ya da tutar geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için parametre ya da kıdem tavanı yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`yil`	`integer`
`cikisNedeni`	`string`
`kidemGun`	`integer`
`kidemYili`	`object`
`kidemYili.yil`	`integer`
`kidemYili.ay`	`integer`
`kidemYili.gun`	`integer`
`giydirilmisAylikUcret`	`number`
`giydirilmisGunlukUcret`	`number`
`kidemTavani`	`object`
`hak`	`object`
`hak.kidem`	`boolean`
`hak.ihbar`	`boolean`
`hak.aciklama`	`string`
`kidem`	`object \| null`
`ihbar`	`object \| null`
`yillikIzin`	`object \| null`
`toplamNet`	`number`
`kaynak`	`object`
`not`	`string`

GET/v1/bordro/asgari-ucret

ücretsiz (anahtarla)

Asgari ücret tarihçesi (ücretsiz)

Anahtar gerekli

2016'dan bugüne asgari ücret dönemleri: brüt, net, işçi ve işveren payları, işverene maliyet (indirimsiz ve 5 puan indirimli). Net tutarlar 2022 öncesinde AGİ dahildir. Kaynak her dönemde Asgari Ücret Tespit Komisyonu Kararı; Resmî Gazete tarihi doğrulanamayan dönemlerde rg null.

Parametreler
Ad	Yer	Tip	Açıklama
`yil`	sorgu	`integer`	Verilmezse tüm tarihçe

Örnek istek

curl "$KILAVUZ/v1/bordro/asgari-ucret?yil=2026" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400yil geçersizHata
401Anahtar yok ya da geçersizHata
422yıl için asgari ücret kaydı yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`yillar`	`integer[]`
`donemler`	`object[]`
`donemler[].donem`	`string`
`donemler[].gecerlilik`	`Gecerlilik`
`donemler[].kaynak`	`ResmiKaynak`
`donemler[].brutAylik`	`number`
`donemler[].brutGunluk`	`number`
`donemler[].netAylik`	`number`
`donemler[].isciSgkOrani`	`number`
`donemler[].isciIssizlikOrani`	`number`
`donemler[].isverenSgkOrani`	`object`
`donemler[].isverenIssizlikOrani`	`number`
`donemler[].isvereneMaliyet`	`object`
`not`	`string`
`aciklama`	`string`

Harçlar

ücretsiz (anahtarla)

2026 tarifeleri: pasaport, sürücü belgesi, kimlik kartı, noter, tapu, yargı, çalışma ve ikamet izni. Maktu harçlar 2026’da %18,95 arttı (%25,49 değil: o, trafik cezalarının oranı). Polis Vakfı payı ikincil kaynaktan, `belirsiz: true`.

GET/v1/harc

ücretsiz (anahtarla)

2026 harç ve değerli kâğıt tarifeleri (ücretsiz)

Anahtar gerekli

2026 maktu harçlar yeniden değerleme oranıyla (%25,49) değil, 10783 sayılı Cumhurbaşkanı Kararıyla %18,95 oranında artırıldı. tur verilmezse bütün gruplar döner.

Parametreler
Ad	Yer	Tip	Açıklama
`tur`	sorgu	`"pasaport" \| "ehliyet" \| "kimlik" \| "noter" \| "tapu" \| "mahkeme" \| "calisma-izni"`
`sure`	sorgu	`"6ay" \| "1yil" \| "2yil" \| "3yil" \| "10yil" \| "suresiz"`	Pasaport ve çalışma izninde

Örnek istek

curl "$KILAVUZ/v1/harc?tur=…&sure=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
422tur ya da sure bilinmiyorHata
429Kredi limiti aşıldıHata

Yanıt alanları
`turler`	`string[]`
`sureler`	`string[]`
`adet`	`integer`
`belirsizSayisi`	`integer`
`gruplar`	`object[]`
`gruplar[].tur`	`string`
`gruplar[].baslik`	`string`
`gruplar[].gecerlilik`	`Gecerlilik`
`gruplar[].kaynak`	`ResmiKaynak[]`
`gruplar[].kalemler`	`HarcKalemi[]`
`gruplar[].not`	`string`
`kaynak`	`ResmiKaynak[]`	Döndürülen grupların kaynakları, tekil
`guncelleme`	`string (date)`
`not`	`string`
`uyari`	`string`

Trafik cezası

ücretsiz (anahtarla)

27.02.2026’dan itibaren 7574 sayılı Kanun tutarları, öteki kalemler EGM 2026 ceza rehberinden; ceza puanı Karayolları Trafik Yönetmeliği Ek-35 cetvelinden. %25 indirim tebliğden itibaren 1 ay içinde ödemede. Tekerrür kademesini ve puan bakiyesini uç bilemez. Hukuki tavsiye değildir.

GET/v1/ceza/trafik2026 trafik cezası tutarları (ücretsiz)
POST/v1/ceza/trafik/indirimPeşin ödeme indirimi ve gecikme faizi (ücretsiz)

GET/v1/ceza/trafik

ücretsiz (anahtarla)

2026 trafik cezası tutarları (ücretsiz)

Anahtar gerekli

Tutarların çoğu 7574 sayılı Kanunla (RG 27.02.2026 / 33181) yeniden belirlendi; yeniden değerleme sonucu değildir; kalan tutarlar ve ceza puanları EGM 2026 Trafik İdari Para Ceza Rehberinden. puanCetveli Karayolları Trafik Yönetmeliği Ek-35 (128 satır); 7574 ile yeniden yazılan maddelere dayanan satırlar uyari taşır.

Parametreler
Ad	Yer	Tip	Açıklama
`madde`	sorgu	`string`	KTK madde/fıkra ön eki
`ara`	sorgu	`string`	Başlık, not ve etiketlerde serbest metin

Örnek istek

curl "$KILAVUZ/v1/ceza/trafik?madde=47/1-b&ara=kirmizi isik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400ara en az 2 karakter olmalıHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`adet`	`integer`
`belirsizSayisi`	`integer`
`cezalar`	`TrafikCezasi[]`
`puanSistemi`	`object`	KTK m.118 eşik ve kademeler
`puanCetveli`	`object`	KTY Ek-35 ceza puanı cetveli; madde/ara süzgeci burada da uygulanır
`puanCetveli.adet`	`integer`
`puanCetveli.uyariSayisi`	`integer`
`puanCetveli.satirlar`	`object[]`
`puanCetveli.kaynak`	`ResmiKaynak`
`indirim`	`object`
`indirim.oran`	`number`
`indirim.sureGun`	`integer`
`indirim.aciklama`	`string`
`kaynak`	`ResmiKaynak[]`
`guncelleme`	`string (date)`
`not`	`string`
`uyari`	`string`

POST/v1/ceza/trafik/indirim

ücretsiz (anahtarla)

Peşin ödeme indirimi ve gecikme faizi (ücretsiz)

Anahtar gerekli

Bir ay içinde ödemede %25 indirim (5326 s.K. m.17/6); sonrasında KTK m.115 uyarınca aylık %5 faiz, ay kesri tam ay, tavan cezanın iki katı.

İstek gövdesi
Alan	Tip	Açıklama
`tutar`zorunlu	`number`	Ceza aslı, TL
`odemeGunu`	`integer`	Tebliğden itibaren geçen gün; varsayılan 0. 0–3650

Örnek istek

curl -X POST "$KILAVUZ/v1/ceza/trafik/indirim" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"tutar":5000,"odemeGunu":10}'

Yanıtlar

200Başarılı
400tutar ya da odemeGunu geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tutar`	`number`
`odemeGunu`	`integer`
`indirimli`	`boolean`
`indirim`	`number`
`gecikmeAy`	`integer`
`faiz`	`number`
`tavanUygulandi`	`boolean`
`odenecek`	`number`
`kural`	`object`
`kural.indirimOrani`	`number`
`kural.odemeSuresiGun`	`integer`
`kural.aylikFaiz`	`number`
`kural.aciklama`	`string`
`kaynak`	`ResmiKaynak[]`
`guncelleme`	`string (date)`
`not`	`string`
`uyari`	`string`

Avukatlık ve noter ücretleri

ücretsiz (anahtarla)

Avukatlık Asgari Ücret Tarifesi 2025–2026 (RG 04.11.2025) ve 2026 Noterlik Ücret Tarifesi ile noter harçları, koda gömülü. Tarifenin hesaba giren kuralları uygulanır, ötekiler `kurallar` alanında özet olarak durur. Doğrulanamayan kalemler (noter KDV’si, taşınmaz satışında noter harcı) `belirsiz: true`. Hukuki tavsiye değildir.

GET/v1/hukuk/faizYasal faiz ve ticari temerrüt faizi oranı (ücretsiz)
POST/v1/hukuk/faizYasal / ticari temerrüt faizi hesapla (ücretsiz)
GET/v1/hukuk/avukatlik-ucretiAvukatlık Asgari Ücret Tarifesi kalemleri (ücretsiz)
POST/v1/hukuk/avukatlik-ucretiAsgari avukatlık ücreti hesapla (ücretsiz)
GET/v1/hukuk/noter-ucretiNoterlik ücret tarifesi ve noter harçları (ücretsiz)
POST/v1/hukuk/noter-ucretiNoter harcı ve ücreti hesapla (ücretsiz)

GET/v1/hukuk/faiz

ücretsiz (anahtarla)

Yasal faiz ve ticari temerrüt faizi oranı (ücretsiz)

Anahtar gerekli

3095 sayılı Kanun: m.1 kanuni faiz (5335 %12, BKK 2005/9831 %9, CBK 8485 %24; 7589 ile 31.07.2026'dan TCMB reeskont oranının %80'i) ve m.2/2 ticari temerrüt faizi (TCMB kısa vadeli avans oranı, kanuni faizden yüksekse). Yarıyıl kuralı: 30 Haziran oranı 31 Aralık'takinden 5 puan ya da daha çok farklıysa ikinci yarıda o. tarih verilmezse bütün dönemler. Kapsam 01.05.2005–31.12.2026. TCMB verisi içerir (not). Hukuki tavsiye değildir.

Parametreler
Ad	Yer	Tip	Açıklama
`tarih`	sorgu	`string (date)`

Örnek istek

curl "$KILAVUZ/v1/hukuk/faiz?tarih=2025-09-01" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih geçersizHata
401Anahtar yok ya da geçersizHata
422tarih kapsam dışında (oran henüz belirlenmedi ya da 2005 öncesi)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`tarih`	`string`
`yasal`	`object`
`yasal.oran`	`number`	Yıllık %
`yasal.dayanak`	`object`
`yasal.tcmbOrani`	`object`
`yasal.avansOrani`	`number`
`yasal.yasalOrani`	`number`
`yasal.aciklama`	`string`
`ticari`	`object`
`ticari.oran`	`number`	Yıllık %
`ticari.dayanak`	`object`
`ticari.tcmbOrani`	`object`
`ticari.avansOrani`	`number`
`ticari.yasalOrani`	`number`
`ticari.aciklama`	`string`
`donem`	`object`
`donem.baslangic`	`string`
`donem.bitis`	`string`
`adet`	`integer`
`donemler`	`object[]`
`donemler[].baslangic`	`string`
`donemler[].bitis`	`string`
`donemler[].yasal`	`number`
`donemler[].ticari`	`number`
`donemler[].avans`	`number`
`donemler[].yasalDayanak`	`string`
`donemler[].ticariDayanak`	`string`
`aciklama`	`object`
`kapsam`	`object`
`kapsam.baslangic`	`string`
`kapsam.bitis`	`string`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`
`not`	`string`

POST/v1/hukuk/faiz

ücretsiz (anahtarla)

Yasal / ticari temerrüt faizi hesapla (ücretsiz)

Anahtar gerekli

Basit faiz: anapara × oran × gün / 365, oran değiştiği günlerde parçalanır; başlangıç günü sayılmaz, bitiş sayılır. Mürekkep faiz yok (3095 m.3). Sözleşme faizi ve yabancı para borcu hesaba girmez. Hukuki tavsiye değildir.

İstek gövdesi
Alan	Tip	Açıklama
`anapara`zorunlu	`number`	TL
`baslangic`zorunlu	`string (date)`	Temerrüt / faiz başlangıç günü
`bitis`zorunlu	`string (date)`	Ödeme ya da hesap günü (en geç 2026-12-31)
`tur`	`"yasal" \| "ticari"`	Varsayılan yasal

Örnek istek

curl -X POST "$KILAVUZ/v1/hukuk/faiz" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"anapara":100000,"baslangic":"2025-01-15","bitis":"2026-03-01","tur":"ticari"}'

Yanıtlar

200Başarılı
400anapara, tarih ya da tur geçersizHata
401Anahtar yok ya da geçersizHata
422tarih aralığı kapsam dışındaHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`string`
`anapara`	`number`
`baslangic`	`string`
`bitis`	`string`
`gun`	`integer`
`faiz`	`number`
`toplam`	`number`
`parcalar`	`object[]`
`parcalar[].baslangic`	`string`
`parcalar[].bitis`	`string`
`parcalar[].gun`	`integer`
`parcalar[].oran`	`number`
`parcalar[].faiz`	`number`
`aciklama`	`string`
`varsayimlar`	`string[]`
`kapsam`	`object`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`
`not`	`string`

GET/v1/hukuk/avukatlik-ucreti

ücretsiz (anahtarla)

Avukatlık Asgari Ücret Tarifesi kalemleri (ücretsiz)

Anahtar gerekli

AAÜT 2025–2026 (RG 04.11.2025/33067, değişiklik 08.01.2026/33131): kalemler, nispi dilimler, hesap kuralları. Hukuki tavsiye değildir.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`	Kalem adında arama (2–100 karakter)

Örnek istek

curl "$KILAVUZ/v1/hukuk/avukatlik-ucreti?ara=tüketici" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400ara geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`adet`	`integer`
`kalemler`	`object[]`
`kalemler[].kod`	`string`
`kalemler[].bolum`	`string`
`kalemler[].ad`	`string`
`kalemler[].tutar`	`number \| null`
`kalemler[].birim`	`string`
`kalemler[].not`	`string`
`dilimler`	`object[]`
`dilimler[].ustSinir`	`number \| null`
`dilimler[].oran`	`number`
`kurallar`	`object[]`
`kurallar[].madde`	`string`
`kurallar[].metin`	`string`
`hesapTurleri`	`string[]`
`sonrakiDonem`	`string`
`belirsizSayisi`	`integer`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`

POST/v1/hukuk/avukatlik-ucreti

ücretsiz (anahtarla)

Asgari avukatlık ücreti hesapla (ücretsiz)

Anahtar gerekli

dava: nispi dilimlerle mahkemenin maktu tabanından büyüğü (md. 13/1), hüküm altına alınan miktarı geçemez (13/2). icra: 56.250 TL'ye kadar maktu 9.000 TL, üstü nispi (md. 11). arabuluculuk: md. 16/2. KDV ve stopaj dahil değil. Hukuki tavsiye değildir.

İstek gövdesi
Alan	Tip	Açıklama
`deger`zorunlu	`number`	Dava değeri / takip miktarı, TL
`tur`	`"dava" \| "icra" \| "arabuluculuk"`	Varsayılan "dava"
`mahkeme`	`string`	İkinci kısım ikinci bölüm kodu; varsayılan "2.2.10" (asliye hukuk)
`onIncelemedenOnce`	`boolean`
`suresindeOdendi`	`boolean`
`anlasma`	`boolean`

Örnek istek

curl -X POST "$KILAVUZ/v1/hukuk/avukatlik-ucreti" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"deger":1000000,"tur":"dava","mahkeme":"2.2.10"}'

Yanıtlar

200Başarılı
400deger, tur ya da mahkeme geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`string`
`deger`	`number`
`nispi`	`number`
`ucret`	`number`
`dilimler`	`object[]`
`maktu`	`object`
`maktu.kod`	`string`
`maktu.ad`	`string`
`maktu.tutar`	`number`
`adimlar`	`string[]`
`maddeler`	`string[]`
`not`	`string`
`belirsizSayisi`	`integer`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`

GET/v1/hukuk/noter-ucreti

ücretsiz (anahtarla)

Noterlik ücret tarifesi ve noter harçları (ücretsiz)

Anahtar gerekli

2026 Noterlik Ücret Tarifesi (RG 30.12.2025/33123, değişiklik 26.08.2026/33352) ve 492 s. Kanun (2) sayılı tarife 2026 tutarları (HKGT 98). Hukuki tavsiye değildir.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`	Kalem adında arama (2–100 karakter)

Örnek istek

curl "$KILAVUZ/v1/hukuk/noter-ucreti?ara=vekaletname" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400ara geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`adet`	`integer`
`kalemler`	`object[]`
`kalemler[].kod`	`string`
`kalemler[].bolum`	`string`
`kalemler[].ad`	`string`
`kalemler[].tutar`	`number \| null`
`kalemler[].birim`	`string`
`kalemler[].not`	`string`
`kalemler[].belirsiz`	`boolean`
`yapi`	`string`
`vergiNotu`	`object`
`islemTurleri`	`string[]`
`sonrakiDonem`	`string`
`belirsizSayisi`	`integer`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`

POST/v1/hukuk/noter-ucreti

ücretsiz (anahtarla)

Noter harcı ve ücreti hesapla (ücretsiz)

Anahtar gerekli

Harç + noter ücreti (harcın %30'u, en az 58,82 TL) + yazı ücreti + KDV (belirsiz). Taşınmaz satışında ücret binde 1 (500–4.000 TL). Damga vergisi dahil değil (/v1/vergi/damga). Hukuki tavsiye değildir.

İstek gövdesi
Alan	Tip	Açıklama
`islem`zorunlu	`"degerli" \| "degersiz" \| "vekaletname" \| "ihtarname" \| "tasinmaz_satis" \| "arac_satis"`
`deger`	`number`	degerli, tasinmaz_satis, arac_satis için TL
`imza`	`integer`	1–1000
`tebligNushasi`	`integer`	1–1000
`sayfa`	`integer`	1–1000
`kdv`	`boolean`	Varsayılan true

Örnek istek

curl -X POST "$KILAVUZ/v1/hukuk/noter-ucreti" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"islem":"degerli","deger":500000,"imza":2,"sayfa":9}'

Yanıtlar

200Başarılı
400islem, deger ya da sayı alanları geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`islem`	`string`
`harc`	`object`
`harc.ad`	`string`
`harc.tutar`	`number`
`harc.hesap`	`string`
`harc.belirsiz`	`boolean`
`harc.not`	`string`
`noterUcreti`	`object`
`yaziUcreti`	`object`
`kdv`	`object`
`toplam`	`number`
`belirsiz`	`boolean`
`belirsizSayisi`	`integer`
`notlar`	`string[]`
`kaynak`	`object`
`guncelleme`	`string (date)`
`uyari`	`string`

Kargo ve e-ticaret

Kargo takibi, takip numarasından taşıyıcı, etiket adres bloğu ve teslim tahmini; mesafeli satış süreleri, müşteri listesinde tekrar bulma.

Kargo

0–1 kredi

Takip şimdilik yalnız Yurtiçi Kargo; gönderen ve alıcı adı yanıtta yer almaz. Teslim tahmini ve desi taşıyıcıdan bağımsız hesaptır; tahmin taahhüt değildir. Takip numarası tanıma olası taşıyıcıları güvene göre sıralar, kesin değildir. Etikette kişi adı yalnız geçirilir; saklanmaz, loglanmaz.

GET/v1/kargo/takipKargo takip
GET/v1/kargo/tasiyicilarTaşıyıcılar ve destek durumu
POST/v1/kargo/desiDesi ve ücretlendirilen ağırlık (ücretsiz)
POST/v1/kargo/etiketKargo etiketi için adres bloğu
POST/v1/kargo/takip-taniTakip numarasından olası taşıyıcı (ücretsiz)
POST/v1/kargo/teslim-tahminiTeslim tarihi tahmini (il→il iş günü)

GET/v1/kargo/takip

1 kredi

Kargo takip

Anahtar gerekli

Şu an yalnız Yurtiçi. Gönderici/alıcı adı döndürülmez. 5 dakika önbellek.

Parametreler
Ad	Yer	Tip	Açıklama
`tasiyici`zorunlu	sorgu	`"yurtici"`
`no`zorunlu	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/kargo/takip?tasiyici=…&no=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200BaşarılıKargoSonucu
400Eksik ya da hatalı parametreHata
401Anahtar yok ya da geçersizHata
422Taşıyıcı desteklenmiyorHata
429Kredi limiti aşıldıHata
502Taşıyıcıya ulaşılamıyorHata

GET/v1/kargo/tasiyicilar

anahtarsız

Taşıyıcılar ve destek durumu

Anahtarsız

Örnek istek

curl "$KILAVUZ/v1/kargo/tasiyicilar"

Yanıtlar

200Başarılı

Yanıt alanları
`tasiyicilar`	`object[]`

POST/v1/kargo/desi

ücretsiz (anahtarla)

Desi ve ücretlendirilen ağırlık (ücretsiz)

Anahtar gerekli

desi = en × boy × yükseklik (cm) / bölen; bölen varsayılan 3000 (yurt içi yaygın), 4000–6000 seçilebilir. Ücretlendirilen ağırlık = max(desi, ağırlık). Taşıyıcı tarifesi esastır.

İstek gövdesi
Alan	Tip	Açıklama
`en`zorunlu	`number`	cm
`boy`zorunlu	`number`	cm
`yukseklik`zorunlu	`number`	cm
`agirlik`zorunlu	`number`	kg
`bolen`	`3000 \| 4000 \| 5000 \| 6000`	varsayılan 3000

Örnek istek

curl -X POST "$KILAVUZ/v1/kargo/desi" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"en":40,"boy":30,"yukseklik":25,"agirlik":3.5}'

Yanıtlar

200Başarılı
400Ölçü eksik, pozitif değil ya da bölen geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`en`	`number`
`boy`	`number`
`yukseklik`	`number`
`agirlik`	`number`
`bolen`	`integer`
`hacimCm3`	`number`
`desi`	`number`
`ucretlendirilenAgirlik`	`number`
`esas`	`"desi" \| "agirlik"`

POST/v1/kargo/etiket

1 kredi

Kargo etiketi için adres bloğu

Anahtar gerekli

Gönderen ve alıcı adresini çözümler (il/ilçe/mahalle/sokak resmî yazımıyla) ve etikete basılacak satırlara indirir: uzun yazımlar kısaltılır ("Caddesi" → "Cad."), kalan taşma sözcük sınırından sarılır, her satır en çok 35 karakter. desi verilirse desi ve ücretlendirilen ağırlık da hesaplanır. Çözülemeyen kritik bileşenler eksikler ve uyarilar ile bildirilir. Kişi/firma adı yalnız geçirilir: çözümlenmez, saklanmaz, loglanmaz. Gönderi başına 1 kredi (iki adres birden).

İstek gövdesi
Alan	Tip	Açıklama
`alici`zorunlu	`EtiketTarafGirdisi`
`gonderen`zorunlu	`EtiketTarafGirdisi`
`desi`	`object`
`desi.en`zorunlu	`number`
`desi.boy`zorunlu	`number`
`desi.yukseklik`zorunlu	`number`
`desi.agirlik`zorunlu	`number`
`desi.bolen`	`3000 \| 4000 \| 5000 \| 6000`	varsayılan 3000
`tasiyici`	`string`	Yalnız yanıta aktarılır. en fazla 40 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/kargo/etiket" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"alici":{"ad":"Ayşe Yılmaz","adres":"moda cad 14/5 kadikoy istanbul"},"gonderen":{"ad":"Örnek Ltd. Şti.","adres":"ataturk bulv no:12 cankaya ankara"},"desi":{"en":30,"boy":40,"yukseklik":20,"agirlik":4}}'

Yanıtlar

200Başarılı
400alici/gonderen eksik ya da desi ölçüsü geçersizHata
401Anahtar yok ya da geçersizHata
413adres 1000, ad 100 karakteri aşıyorHata
429Kredi limiti aşıldıHata

Yanıt alanları
`gonderen`	`EtiketTaraf`
`alici`	`EtiketTaraf`
`tasiyici`	`string`
`desi`	`object`
`satirUzunlugu`	`integer`
`uyarilar`	`string[]`
`not`	`string`

POST/v1/kargo/takip-tani

ücretsiz (anahtarla)

Takip numarasından olası taşıyıcı (ücretsiz)

Anahtar gerekli

Numaranın biçiminden (uzunluk, önek, varsa kontrol hanesi) olası taşıyıcıları güvene göre sıralar. **Kesinlik iddiası yok**: taşıyıcılar numara şemalarını resmî olarak yayımlamıyor ve uzunluklar örtüşüyor; kurallar kamuya açık örneklerden çıkarıldı. UPS 1Z… kontrol hanesi ve DHL Express 10 hane mod-7 sağlaması hesaplanır, tutarsa güven yükselir. Boşluk, tire ve nokta yok sayılır. takipDestegi: true olan taşıyıcıda GET /v1/kargo/takip ile gerçek durum sorulabilir. Her adayda takipUrl: taşıyıcının herkese açık takip sayfası, numara bağlantıya gömülü; yalnız resmî sitede doğrulanmış kalıplarda dolu (şimdilik Yurtiçi, Aras), sayfası numarayı bağlantıdan almayan taşıyıcıda null. Kredi harcamaz.

İstek gövdesi
Alan	Tip	Açıklama
`numara`zorunlu	`string`	en fazla 60 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/kargo/takip-tani" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"numara":"1Z999AA10123456784"}'

Yanıtlar

200Başarılı
400numara eksik ya da 6–35 karakter harf/rakam değilHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`numara`	`string`	Normalize hâli (büyük harf, ayraçsız)
`bicim`	`"rakam" \| "upu" \| "ups" \| "alfanumerik"`
`uzunluk`	`integer`
`adaylar`	`object[]`	Güvene göre azalan; boş olabilir
`adaylar[].kod`	`string`
`adaylar[].ad`	`string`
`adaylar[].guven`	`number`	Sıralama ölçüsü, olasılık değil. 0–1
`adaylar[].gerekce`	`string`
`adaylar[].takipDestegi`	`boolean`
`adaylar[].takipUrl`	`string \| null (uri)`	Taşıyıcının takip sayfası, numara gömülü; doğrulanmış kalıp yoksa null
`not`	`string`

POST/v1/kargo/teslim-tahmini

1 kredi

Teslim tarihi tahmini (il→il iş günü)

Anahtar gerekli

Gönderim tarihi ve iki ilden tahmini teslim ve en geç tarih. Tablo: aynı il 1, aynı/komşu bölge 2, uzak bölge 3 iş günü; Doğu/Güneydoğu Anadolu +1. Hafta sonu, resmî tatil ve arife dağıtım günü sayılmaz; tatil günü verilen gönderi sonraki iş gününde kabul edilir. **Tahmindir, taşıyıcı taahhüdü değildir**; tasiyici yalnız yanıta aktarılır. Kapsam 2022–2028 (tatil tablosu).

İstek gövdesi
Alan	Tip	Açıklama
`gonderimTarihi`zorunlu	`string (date)`
`gonderenIl`zorunlu	`string`
`aliciIl`zorunlu	`string`
`tasiyici`	`string`	Yalnız yanıta aktarılır; hesabı değiştirmez. en fazla 40 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/kargo/teslim-tahmini" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"gonderimTarihi":"2026-05-22","gonderenIl":"İstanbul","aliciIl":"Van"}'

Yanıtlar

200BaşarılıTeslimTahmini
400Tarih biçimi hatalı ya da il tanınmadıHata
401Anahtar yok ya da geçersizHata
422Yıl kapsam dışında (2022–2028)Hata
429Kredi limiti aşıldıHata

E-ticaret kuralları

ücretsiz (anahtarla)

Mesafeli Sözleşmeler Yönetmeliği ve VUK'tan hesaplanır; hukuki tavsiye değildir. Dayanak /kaynaklar sayfasında.

GET/v1/ticaret/caymaCayma hakkı süresi ve istisnaları (ücretsiz)
GET/v1/ticaret/fatura-suresiFatura düzenleme süresinin son günü (ücretsiz)

GET/v1/ticaret/cayma

ücretsiz (anahtarla)

Cayma hakkı süresi ve istisnaları (ücretsiz)

Anahtar gerekli

Mesafeli Sözleşmeler Yönetmeliği m.9: teslimden itibaren 14 gün (teslim günü sayılmaz); m.10: eksik bilgilendirmede sürenin mutlak sonu (+1 yıl); m.15 istisnaları urunTuru ile (caymaHakkiVar: false + bent). Mühürlü hijyen ürünü ve medya gibi koşullu istisnalarda istisna.kosul yazar. Hukuki tavsiye değildir (uyari).

Parametreler
Ad	Yer	Tip	Açıklama
`teslimTarihi`zorunlu	sorgu	`string (date)`	Mal: teslim günü; hizmet: sözleşme günü
`urunTuru`	sorgu	`"standart" \| "hizmet" \| "finansal_dalgalanma" \| "kisiye_ozel" \| "cabuk_bozulan" \| "muhurlu_hijyen" \| "karisan_mal" \| "muhru_acilmis_medya" \| "sureli_yayin" \| "tarihli_hizmet" \| "anlik_dijital" \| "onayla_baslanan_hizmet"`

Örnek istek

curl "$KILAVUZ/v1/ticaret/cayma?teslimTarihi=2026-09-18&urunTuru=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400teslimTarihi hatalı ya da urunTuru bilinmiyorHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`teslimTarihi`	`string`
`urunTuru`	`string`
`caymaHakkiVar`	`boolean`
`sure`	`object`
`sonGun`	`string (date)`
`sonGunTatil`	`boolean`	Yalnız 2022–2028
`eksikBilgilendirmedeSonGun`	`string (date)`	m.10: sonGun + 1 yıl
`istisna`	`object`
`istisna.bent`	`string`
`istisna.aciklama`	`string`
`istisna.kosul`	`string`
`sureBaslangici`	`string`
`mevzuat`	`object`
`mevzuat.ad`	`string`
`mevzuat.resmiGazete`	`string`
`mevzuat.maddeler`	`string[]`
`mevzuat.kaynak`	`string`
`yururlukNotu`	`string`
`uyari`	`string`

GET/v1/ticaret/fatura-suresi

ücretsiz (anahtarla)

Fatura düzenleme süresinin son günü (ücretsiz)

Anahtar gerekli

VUK m.231/5: malın teslimi ya da hizmetin yapıldığı tarihten itibaren azami 7 gün (teslim günü sayılmaz); süresinde düzenlenmeyen fatura hiç düzenlenmemiş sayılır. Son gün tatile rastlarsa VUK m.18 gereği izleyen ilk iş günü (sonGunIsGunu, 2022–2028). Hukuki tavsiye değildir (uyari).

Parametreler
Ad	Yer	Tip	Açıklama
`teslimTarihi`zorunlu	sorgu	`string (date)`

Örnek istek

curl "$KILAVUZ/v1/ticaret/fatura-suresi?teslimTarihi=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400teslimTarihi hatalıHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`teslimTarihi`	`string`
`sure`	`object`
`sonGun`	`string (date)`
`sonGunIsGunu`	`string (date)`	VUK m.18; yalnız 2022–2028
`ayDegisiyor`	`boolean`	Son gün teslim ayından sonraki aya taşıyor (KDV dönemi teslim ayı)
`sonuc`	`string`
`mevzuat`	`object`
`mevzuat.ad`	`string`
`mevzuat.maddeler`	`string[]`
`mevzuat.kaynak`	`string`
`yururlukNotu`	`string`
`uyari`	`string`

Müşteri tekilleştirme

1 kredi

Aynı GSM, aynı e-posta, aynı ad ve sabit hat ya da aynı ad ve bina aynı kişi sayılır; yalnız aynı adres ya da yalnız aynı ad bağlamaz. Liste saklanmaz, loglanmaz.

POST/v1/musteri/tekillestir

1 kredi

Müşteri listesinde aynı kişileri kümele

Anahtar gerekli

Dolu kayıt başına 1 kredi; bakiye işten önce denetlenir, kredi iş bitince düşer. Bağlar: aynı GSM (E.164), aynı e-posta (Gmail nokta/+etiket yok sayılır), aynı ad + sabit hat, aynı ad + bina (adres çözümlenir; daire çelişmiyorsa). Yalnız aynı adres ya da yalnız aynı ad bağlamaz. JSON gövde JSON, CSV gövde (ilk satır başlık) CSV döner: sona ak_kume, ak_kume_boyut, ak_ilk, ak_neden, ak_ad, ak_telefon, ak_eposta. En çok 10.000 kayıt, 2,5 MB, 20 sn. Girdi saklanmaz.

Parametreler
Ad	Yer	Tip	Açıklama
`ad`	sorgu	`string`	CSV: sütun adı ya da 1'den sıra (verilmezse başlıktan bulunur)
`soyad`	sorgu	`string`	CSV: sütun adı ya da 1'den sıra (verilmezse başlıktan bulunur)
`telefon`	sorgu	`string`	CSV: sütun adı ya da 1'den sıra (verilmezse başlıktan bulunur)
`eposta`	sorgu	`string`	CSV: sütun adı ya da 1'den sıra (verilmezse başlıktan bulunur)
`adres`	sorgu	`string`	CSV: sütun adı ya da 1'den sıra (verilmezse başlıktan bulunur)

İstek gövdesi
Alan	Tip	Açıklama
`kayitlar`zorunlu	`object[]`	en fazla 10000
`kayitlar[].ad`	`string`
`kayitlar[].telefon`	`string`
`kayitlar[].eposta`	`string`
`kayitlar[].adres`	`string`

Örnek istek

curl -X POST "$KILAVUZ/v1/musteri/tekillestir" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{}' \
  -H "content-type: text/csv" \
  --data-binary @siparisler.csv \
  -o siparisler-temiz.csv

Yanıtlar

200Kümeler
400girdi hatalı ya da sütun bulunamadı (yanıtta basliklar)Hata
401Anahtar yok ya da geçersizHata
413liste çok büyükHata
415gövde JSON ya da CSV değilHata
429Kredi limiti aşıldıHata
503süre aşıldı, kredi düşülmediHata

Yanıt alanları
`toplam`	`integer`
`tekilKisi`	`integer`
`tekrar`	`integer`
`kumeler`	`object[]`
`kumeler[].kume`	`integer`
`kumeler[].sira`	`integer[]`
`kumeler[].nedenler`	`"telefon" \| "eposta" \| "ad+telefon" \| "ad+adres"[]`
`kayitlar`	`object[]`
`kayitlar[].sira`	`integer`
`kayitlar[].kume`	`integer`
`kayitlar[].ilk`	`boolean`
`not`	`string`

Takvim

Resmî tatil listesi ve tatilleri bilen iş günü hesabı, namaz vakitleri ve hicri takvim.

Tatil, iş günü, namaz, hicri

ücretsiz (anahtarla)

Resmî tatiller 2022–2028, arife yarım günleri dahil; bayram tarihleri Diyanet’ten, 2027–2028 Diyanet’in ileri tarihli takvimi. Köprü günleri (idari izin) tatil sayılmaz. İş gününde hafta sonu ve resmî tatiller sayılmaz. Namaz vakitleri astronomik hesap (Diyanet açıları, temkin 0); Diyanet takvimiyle birkaç dakika fark olabilir. Hicri tarih tablosal hesap; gözleme dayanan Diyanet takviminden 1 gün farklı olabilir.

GET/v1/takvim/is-gunu-ekleTarihe iş günü ekle/çıkar (ücretsiz)
GET/v1/takvim/tatillerResmî tatil listesi (ücretsiz)
GET/v1/takvim/gunGün bilgisi: iş günü mü, tatil mi (ücretsiz)
GET/v1/takvim/is-gunu/sayİki tarih arası iş günü sayısı, ikisi dahil (ücretsiz)
GET/v1/takvim/namazNamaz vakitleri (ücretsiz)
GET/v1/takvim/hicriHicri ↔ miladi tarih (ücretsiz)

GET/v1/takvim/is-gunu-ekle

ücretsiz (anahtarla)

Tarihe iş günü ekle/çıkar (ücretsiz)

Anahtar gerekli

Başlangıç günü sayılmaz: Cuma + 1 = Pazartesi. Negatif gün geri gider. Resmî tatiller 2429 sayılı Kanun, dini bayramlar Diyanet takvimi; kapsam 2022–2028. Köprü günleri (idari izin) dahil değil.

Parametreler
Ad	Yer	Tip	Açıklama
`tarih`zorunlu	sorgu	`string (date)`	Başlangıç
`gun`zorunlu	sorgu	`integer`
`yarimGun`	sorgu	`"is" \| "tatil"`	Arife gibi yarım günler iş günü sayılsın mı

Örnek istek

curl "$KILAVUZ/v1/takvim/is-gunu-ekle?tarih=2026-09-18&gun=…&yarimGun=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400Parametre hatalıHata
401Anahtar yok ya da geçersizHata
422Yıl kapsam dışında (2022–2028)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`baslangic`	`string`
`gun`	`integer`
`sonuc`	`string`
`yarimGunIsGunu`	`boolean`
`kapsam`	`object`
`kapsam.ilk`	`integer`
`kapsam.son`	`integer`
`kaynak`	`string`
`guncelleme`	`string`

GET/v1/takvim/tatiller

ücretsiz (anahtarla)

Resmî tatil listesi (ücretsiz)

Anahtar gerekli

Millî bayramlar, dini bayramlar (Diyanet takvimi) ve 13.00'te başlayan yarım günler. Kapsam 2022–2028 (2027–2028 Diyanet'in ileri tarihli takvimi). Köprü günleri (idari izin) dahil değil.

Parametreler
Ad	Yer	Tip	Açıklama
`yil`	sorgu	`integer`	Varsayılan: içinde bulunulan yıl

Örnek istek

curl "$KILAVUZ/v1/takvim/tatiller?yil=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400yil biçimi hatalıHata
401Anahtar geçersizHata
422Yıl kapsam dışında (2022–2028)Hata

Yanıt alanları
`kaynak`	`string`
`guncelleme`	`string`
`yil`	`integer`
`kapsam`	`object`
`tatiller`	`Tatil[]`

GET/v1/takvim/gun

ücretsiz (anahtarla)

Gün bilgisi: iş günü mü, tatil mi (ücretsiz)

Anahtar gerekli

Parametreler
Ad	Yer	Tip	Açıklama
`tarih`zorunlu	sorgu	`string (date)`	YYYY-AA-GG

Örnek istek

curl "$KILAVUZ/v1/takvim/gun?tarih=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih hatalıHata
401Anahtar yok ya da geçersizHata
422Yıl kapsam dışında (2022–2028)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`kaynak`	`string`
`guncelleme`	`string`
`tarih`	`string`
`haftaninGunu`	`integer`	1=Pazartesi … 7=Pazar
`haftaSonu`	`boolean`
`tatiller`	`Tatil[]`
`tatil`	`boolean`
`yarimGun`	`boolean`
`isGunu`	`boolean`

GET/v1/takvim/is-gunu/say

ücretsiz (anahtarla)

İki tarih arası iş günü sayısı, ikisi dahil (ücretsiz)

Anahtar gerekli

Parametreler
Ad	Yer	Tip	Açıklama
`baslangic`zorunlu	sorgu	`string (date)`	Dahil
`bitis`zorunlu	sorgu	`string (date)`	Dahil
`yarimGun`	sorgu	`"is" \| "tatil"`	Yarım günler (arife) iş günü sayılsın mı

Örnek istek

curl "$KILAVUZ/v1/takvim/is-gunu/say?baslangic=2026-09-18&bitis=2026-09-18&yarimGun=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400Parametre hatalıHata
401Anahtar yok ya da geçersizHata
422Yıl kapsam dışında (2022–2028)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`kaynak`	`string`
`guncelleme`	`string`
`baslangic`	`string`
`bitis`	`string`
`isGunu`	`integer`
`yarimGunIsGunu`	`boolean`

GET/v1/takvim/namaz

ücretsiz (anahtarla)

Namaz vakitleri (ücretsiz)

Anahtar gerekli

Güneşin konumundan hesaplanan vakitler; kazıma ya da dış istek yok. Diyanet açıları: imsak 18°, yatsı 17°, güneş/akşam ufkun 0,833° altı, ikindi gölge katsayısı 1 (Şafii, asr=standart) ya da 2 (asr=hanefi). Konum il verilirse il merkezi koordinatı (Overture POI medyanı), yoksa lat/lon. Saat dilimi sabit UTC+03:00; kapsam 2017–2050 (öncesinde yaz saati vardı). Temkin (ihtiyat) dakikası eklenmez, yanıtta söylenir. İbadet için resmî Diyanet takvimi esastır.

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`	Ad ya da plaka; lat/lon ile birlikte verilmez
`lat`	sorgu	`number`
`lon`	sorgu	`number`
`tarih`	sorgu	`string (date)`	Varsayılan bugün (Türkiye saati)
`asr`	sorgu	`"standart" \| "hanefi"`	İkindi gölge katsayısı

Örnek istek

curl "$KILAVUZ/v1/takvim/namaz?il=İstanbul&lat=41.0082&lon=28.9784&tarih=2026-09-18&asr=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il ile lat/lon birlikte, ikisi de eksik, ya da tarih/asr hatalıHata
401Anahtar geçersizHata
422il bulunamadı ya da yıl kapsam dışında (2017–2050)Hata

Yanıt alanları
`tarih`	`string`
`il`	`string \| null`
`plaka`	`integer \| null`
`konum`	`object`
`konum.lat`	`number`
`konum.lon`	`number`
`konum.kaynak`	`string`
`saatDilimi`	`string`
`yontem`	`object`
`yontem.ad`	`string`
`yontem.imsakAcisi`	`number`
`yontem.yatsiAcisi`	`number`
`yontem.ufukAcisi`	`number`
`yontem.ikindi`	`"standart" \| "hanefi"`
`yontem.ikindiGolgeKatsayisi`	`integer`
`vakitler`	`object`	SS:DD, Türkiye saati. Vakit oluşmuyorsa null (Türkiye'de olmaz).
`vakitler.imsak`	`string \| null`
`vakitler.gunes`	`string \| null`
`vakitler.ogle`	`string \| null`
`vakitler.ikindi`	`string \| null`
`vakitler.aksam`	`string \| null`
`vakitler.yatsi`	`string \| null`
`temkin`	`object`
`temkin.dakika`	`integer`
`temkin.not`	`string`
`kapsam`	`object`
`kapsam.ilk`	`integer`
`kapsam.son`	`integer`
`not`	`string`

GET/v1/takvim/hicri

ücretsiz (anahtarla)

Hicri ↔ miladi tarih (ücretsiz)

Anahtar gerekli

tarih verilirse miladiden hicriye, hicri verilirse hicriden miladiye; ikisi de yoksa bugün (Türkiye saati). Yöntem tablosal (aritmetik) hicri takvim — 30 yıllık devrede 11 artık yıl. Diyanet takvimi hilalin gözlenmesine dayandığı için 1 gün farklı olabilir; yanıttaki not bunu söyler.

Parametreler
Ad	Yer	Tip	Açıklama
`tarih`	sorgu	`string (date)`	Miladi; hicri ile birlikte verilmez
`hicri`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/takvim/hicri?tarih=2026-09-22&hicri=1448-03-01" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih ile hicri birlikte ya da biçim hatalıHata
401Anahtar geçersizHata
422Yıl kapsam dışında ya da o ayda olmayan günHata

Yanıt alanları
`miladi`	`string`
`hicri`	`object`
`hicri.yil`	`integer`
`hicri.ay`	`integer`
`hicri.gun`	`integer`
`hicri.ayAdi`	`string`
`hicri.metin`	`string`	"10 Rebiülevvel 1448"
`hicri.iso`	`string`
`hicri.artikYil`	`boolean`
`hicri.ayGunSayisi`	`integer`
`yontem`	`string`
`kapsam`	`object`
`kapsam.miladi`	`object`
`kapsam.hicri`	`object`
`not`	`string`

Metin

Türkçe metin için yazım araçları: çekim eki, doğal dil tarihi, Türkçe harfleri geri koyma; serbest metinden alan çıkarma ve kişisel veri maskeleme.

KVKK maskeleme

1 kredi

Kural tabanlı; yüzde yüz değildir, ad ve adres aranmaz. Metin saklanmaz, ham değer yanıtta dönmez.

POST/v1/kvkk/maskeleMetinde kişisel veri bul ve maskele
GET/v1/kvkk/ihlallerKVKK veri ihlali bildirimleri

POST/v1/kvkk/maskele

1 kredi

Metinde kişisel veri bul ve maskele

Anahtar gerekli

TCKN, IBAN, telefon, e-posta, kredi kartı ve plakayı bulur, harf/rakamları * yapar (uzunluk korunur). TCKN/IBAN/kredi kartı/telefon sağlamalı, e-posta ve plaka biçimsel. Ad-soyad ve adres aranmaz. Yanıt ham değeri değil yalnız yerini verir; metin saklanmaz. En fazla 100.000 karakter; kredi metin başına.

İstek gövdesi
Alan	Tip	Açıklama
`metin`zorunlu	`string`	en fazla 100000 karakter
`turler`	`"tckn" \| "iban" \| "telefon" \| "eposta" \| "kredi_karti" \| "plaka"[]`	Verilmezse hepsi

Örnek istek

curl -X POST "$KILAVUZ/v1/kvkk/maskele" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"metin":"Müşteri 0532 123 45 67 aradı, IBAN TR33 0006 1005 1978 6457 8413 26"}'

Yanıtlar

200Başarılı
400metin eksik ya da turler geçersizHata
401Anahtar yok ya da geçersizHata
413100.000 karakterden uzunHata
429Kredi limiti aşıldıHata

Yanıt alanları
`metin`	`string`	Maskelenmiş metin, girdiyle aynı uzunlukta
`bulgular`	`object[]`
`bulgular[].tur`	`"tckn" \| "iban" \| "telefon" \| "eposta" \| "kredi_karti" \| "plaka"`
`bulgular[].baslangic`	`integer`	JS dizi konumu, dahil
`bulgular[].bitis`	`integer`	Hariç
`sayim`	`object`
`not`	`string`

GET/v1/kvkk/ihlaller

1 kredi

KVKK veri ihlali bildirimleri

Anahtar gerekli

KVKK Kurulu'nun kamuoyuna ilan ettiği veri ihlali bildirimleri (kvkk.gov.tr), en yeni önce. Duyuru metni değil, yapılandırılmış özet: neden türleri, tespit ve ihlal tarihleri, etkilenen kişi sayısı ve niteleyicisi, kişi grupları, veri kategorileri ve etiketleri, Kurul kararı. Günde iki kez çekilir, istek anında kaynağa gidilmez. Veri sorumlusu şahıs şirketiyse (unvanda tüzel kişilik işareti yok) adı, duyuru bağlantısı ve neden cümlesi verilmez (sahisSirketi: true). ara sözcükleri unvan, kategori, kişi grubu ve neden türünde aranır (hepsi geçmeli, Türkçe karaktersiz de olur). Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`
`baslangic`	sorgu	`string (date)`	Yayım tarihi, dahil
`bitis`	sorgu	`string (date)`	Yayım tarihi, dahil
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/kvkk/ihlaller?ara=fidye&baslangic=2026-09-18&bitis=2026-09-18&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400ara çok uzun, tarih ya da limit geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ara`	`string \| null`
`baslangic`	`string \| null`
`bitis`	`string \| null`
`toplam`	`integer`
`ihlaller`	`object[]`
`ihlaller[].id`	`integer`	kvkk.gov.tr içerik numarası
`ihlaller[].yayinTarihi`	`string (date)`
`ihlaller[].veriSorumlusu`	`string \| null`	Şahıs şirketinde null
`ihlaller[].sahisSirketi`	`boolean`
`ihlaller[].url`	`string`	Duyuru; şahıs şirketinde liste sayfası
`ihlaller[].ayrintiAlindi`	`boolean`	false ise yalnız tarih ve unvan dolu
`ihlaller[].neden`	`string \| null`	Nedeni anlatan madde, en çok 300 karakter; şahıs şirketinde null
`ihlaller[].nedenTurleri`	`"fidye" \| "kimlik-avi" \| "siber-saldiri" \| "yetkisiz-erisim" \| "zafiyet" \| "veri-isleyen" \| "yanlis-gonderim" \| "kayip-calinti" \| "calisan"[]`
`ihlaller[].tespitTarihi`	`string \| null (date)`
`ihlaller[].ihlalBaslangic`	`string \| null (date)`
`ihlaller[].ihlalBitis`	`string \| null (date)`
`ihlaller[].kisiSayisi`	`integer \| null`
`ihlaller[].kisiSayisiNiteleyici`	`"kesin" \| "yaklasik" \| "en_fazla" \| "belirlenemedi" \| null`
`ihlaller[].kisiGruplari`	`string[]`
`ihlaller[].veriKategorileri`	`string[]`	Duyurudaki yazımıyla
`ihlaller[].veriEtiketleri`	`string[]`	ad-soyad, kimlik, iletisim, e-posta, telefon, adres, dogum-tarihi, sifre, kullanici-adi, finans, saglik, konum, pasaport, gorsel, ozluk, musteri-islem
`ihlaller[].kurulKarari`	`object \| null`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

Metin araçları

0–1 kredi

Adres kısaltmada "İst." bilerek açılmaz (adreste çoğunlukla İstanbul, yol adında İstiklal); gerçek sözcük olan kısaltmalar (bul, koy, kat) yalnız noktalıysa açılır. Türkçeleştirme sözlükte olmayan sözcüğe dokunmaz, iki okunuşlu sözcüğü (diş/dış) belirsiz bırakır. Tarih çözümleme her sonuca güven puanı verir. Alan çıkarmada TCKN yalnız maskeli döner; metin saklanmaz.

POST/v1/metin/yaziylaTutarı yazıyla yaz (ücretsiz)
POST/v1/metin/slugURL dostu slug (ücretsiz)
POST/v1/metin/siralaTürkçe alfabe sırasıyla sırala (ücretsiz)
POST/v1/metin/ad-normalizeAd-soyad yazımını düzelt (ücretsiz)
POST/v1/metin/kisaltmaAdres kısaltmalarını aç ya da kısalt (ücretsiz)
POST/v1/metin/ekTürkçe çekim eki üret (ücretsiz)
POST/v1/metin/tarihDoğal dil tarihini çözümle (ücretsiz)
POST/v1/metin/turkcelestirASCII metne Türkçe harfleri geri koy (ücretsiz)
POST/v1/metin/ayiklaSerbest metinden alan çıkar (telefon, IBAN, tutar, tarih, adres)

POST/v1/metin/yaziyla

ücretsiz (anahtarla)

Tutarı yazıyla yaz (ücretsiz)

Anahtar gerekli

12.345,50 → "on iki bin üç yüz kırk beş TL elli kuruş". Metin girdide Türkçe yazım (nokta binlik, virgül ondalık); sayı girdide kuruş yuvarlanır. En fazla 15 hane. bitisik çek/senet yazımı, buyukHarf Türkçe büyük harf.

İstek gövdesi
Alan	Tip	Açıklama
`tutar`zorunlu	`number ya da string`
`paraBirimi`	`"TRY" \| "USD" \| "EUR" \| "GBP" \| "yok"`	`yok`: "… virgül elli". varsayılan "TRY"

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/yaziyla" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"tutar":"12.345,50"}'

Yanıtlar

200Başarılı
400tutar eksik/biçimsiz ya da paraBirimi bilinmiyorHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tutar`	`string`	Türkçe biçim "12.345,50"
`paraBirimi`	`string`
`yazi`	`string`
`buyukHarf`	`string`
`bitisik`	`string`

POST/v1/metin/slug

ücretsiz (anahtarla)

URL dostu slug (ücretsiz)

Anahtar gerekli

Türkçe harfler ASCII'ye iner (ç→c, ı/İ→i, ş→s…), harf-rakam dışı her şey ayırıcı. En fazla 1000 karakter.

İstek gövdesi
Alan	Tip	Açıklama
`metin`zorunlu	`string`	en fazla 1000 karakter
`ayirici`	`"-" \| "_"`	varsayılan "-"

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/slug" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"metin":"Çankaya'da Yeni Dükkân!"}'

Yanıtlar

200Başarılı
400metin eksik ya da ayirici geçersizHata
401Anahtar yok ya da geçersizHata
4131000 karakterden uzunHata
429Kredi limiti aşıldıHata

Yanıt alanları
`slug`	`string`

POST/v1/metin/sirala

ücretsiz (anahtarla)

Türkçe alfabe sırasıyla sırala (ücretsiz)

Anahtar gerekli

ICU Türkçe sıralama (a b c ç … ı i … o ö … s ş … u ü …); büyük/küçük harf duyarsız, sayılar sayı olarak ("Sokak 2" < "Sokak 10"). En fazla 10.000 eleman.

İstek gövdesi
Alan	Tip	Açıklama
`liste`zorunlu	`string[]`	en fazla 10000
`yon`	`"artan" \| "azalan"`	varsayılan "artan"

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/sirala" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"liste":["şeker","çay","ırmak","iğne","ada"]}'

Yanıtlar

200Başarılı
400liste boş, metin olmayan eleman ya da yon geçersizHata
401Anahtar yok ya da geçersizHata
41310.000'den fazla elemanHata
429Kredi limiti aşıldıHata

Yanıt alanları
`liste`	`string[]`
`yon`	`string`

POST/v1/metin/ad-normalize

ücretsiz (anahtarla)

Ad-soyad yazımını düzelt (ücretsiz)

Anahtar gerekli

"MEHMET ALİ yılmaz" → "Mehmet Ali Yılmaz": Türkçe büyük/küçük harf (İ/ı), fazla boşluk, tire ve kesme. Ad/soyad ayırmaz, cinsiyet tahmini yapmaz. En fazla 200 karakter; girdi saklanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`ad`zorunlu	`string`	en fazla 200 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/ad-normalize" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"ad":"MEHMET ALİ  yılmaz"}'

Yanıtlar

200Başarılı
400ad eksikHata
401Anahtar yok ya da geçersizHata
413200 karakterden uzunHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ad`	`string`

POST/v1/metin/kisaltma

ücretsiz (anahtarla)

Adres kısaltmalarını aç ya da kısalt (ücretsiz)

Anahtar gerekli

yon: "ac" (varsayılan): "Cad." → Caddesi, "Mah." → Mahallesi, "Sk." → Sokak, "Şht." → Şehit, "K:3" → Kat:3. yon: "kisalt": etiket uzunluğu için ters yön (Caddesi → Cad., Organize Sanayi Bölgesi → OSB). Gerçek sözcük de olan kısaltmalar ("Bul", "Sit") yalnız noktalıysa açılır; "K", "D" yalnız ardından sayı gelirse. Metnin geri kalanına dokunulmaz, sicille eşleştirmez (bunun için /v1/address/parse). En fazla 2.000 karakter; girdi saklanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`metin`zorunlu	`string`	en fazla 2000 karakter
`yon`	`"ac" \| "kisalt"`	varsayılan "ac"

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/kisaltma" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"metin":"Atatürk Cad. Şht. Ali Sk. No:5 D:3","yon":"ac"}'

Yanıtlar

200Başarılı
400metin eksik ya da yon geçersizHata
401Anahtar yok ya da geçersizHata
4132.000 karakterden uzunHata
429Kredi limiti aşıldıHata

Yanıt alanları
`metin`	`string`
`yon`	`string`
`degisiklikler`	`object[]`
`degisiklikler[].once`	`string`
`degisiklikler[].sonra`	`string`

POST/v1/metin/ek

ücretsiz (anahtarla)

Türkçe çekim eki üret (ücretsiz)

Anahtar gerekli

"Ankara" + yonelme → "Ankara'ya", "kitap" + belirtme → "kitabı", "2026" + bulunma → "2026'da". Ünlü uyumu, ünsüz sertleşmesi ("40'ta"), ünsüz yumuşaması ("kitap → kitabı", "renk → rengi") ve kaynaştırma harfi (araba+yı, araba+nın, araba+sı). ozelIsim verilmezse baş harfi büyük yazılanlar özel isim sayılır: kesme işareti konur ve yumuşama yazıya geçmez (TDK). Sayı okunuşuna göre çekilir ve hep kesme alır; soru eki ayrı sözcüktür ("Volkan mı"). kelimeler ile en fazla 1.000 sözcük tek çağrıda. İkizleşme ("hak → hakkı") ve ünlü düşmesi kapsam dışı; girdi saklanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`kelime`	`string`	en fazla 100 karakter
`kelimeler`	`string[]`	`kelime` yerine; toplu üretim. en fazla 1000
`ek`zorunlu	`"yonelme" \| "bulunma" \| "ayrilma" \| "belirtme" \| "ilgi" \| "iyelik" \| "ile" \| "mi"`
`ozelIsim`	`boolean`	Verilmezse baş harfe bakılır

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/ek" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"kelime":"Ankara","ek":"yonelme"}'

Yanıtlar

200Başarılı
400kelime/ek eksik ya da geçersizHata
401Anahtar yok ya da geçersizHata
413100 karakterden uzun ya da 1.000'den fazla sözcükHata
429Kredi limiti aşıldıHata

Yanıt alanları
`kelime`	`string`
`ek`	`string`
`sonuc`	`string`	"Ankara'ya"
`eklenen`	`string`	Yalnız ek: "'ya"
`ozelIsim`	`boolean`
`kesme`	`boolean`
`okunus`	`string`	Yalnız sayıda: "iki bin yirmi altı"
`uyari`	`string`
`not`	`string`
`sonuclar`	`object[]`	Yalnız `kelimeler` verildiğinde

POST/v1/metin/tarih

ücretsiz (anahtarla)

Doğal dil tarihini çözümle (ücretsiz)

Anahtar gerekli

"3 Ekim 2026", "03.10.2026", "3/10/26", "yarın", "önümüzdeki salı", "3 gün sonra", "haftaya", "ayın 15'i", "gelecek ay", "saat 14:30" → ISO tarih. Türkiye yazımı esas: gün önce, ay sonra (Date.parse "3.10.2026"yı 10 Mart okur). Takvim Europe/Istanbul; simdi ile göreli ifadelerin dayanağı verilebilir (testte ve geçmiş bir mesajı işlerken). guven 1'e yakınsa tarih metinde açıkça yazılı, düştükçe yorum payı artar; eslesmeler hangi parçanın hangi kurala takıldığını söyler. Tarih bulunamazsa hata değil, bulundu: false. Tarih aralığı ("3–5 Ekim"), tekrar eden ifade ("her salı") ve saat dilimi seçimi kapsam dışı. En fazla 500 karakter; girdi saklanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`metin`zorunlu	`string`	en fazla 500 karakter
`simdi`	`string`	ISO 8601; verilmezse şimdiki an

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/tarih" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"metin":"önümüzdeki salı saat 14:30 teslim","simdi":"2026-09-22T09:00:00+03:00"}'

Yanıtlar

200Başarılı
400metin eksik ya da simdi geçersizHata
401Anahtar yok ya da geçersizHata
413500 karakterden uzunHata
429Kredi limiti aşıldıHata

Yanıt alanları
`bulundu`	`boolean`
`tarih`	`string (date)`
`saat`	`string`	SS:DD
`iso`	`string`	"2026-10-03" ya da "2026-10-03T14:30"
`guven`	`number`	0–1
`eslesmeler`	`object[]`
`eslesmeler[].tur`	`"tarih" \| "saat"`
`eslesmeler[].metin`	`string`
`eslesmeler[].baslangic`	`integer`
`eslesmeler[].bitis`	`integer`
`eslesmeler[].kural`	`string`	iso, gun_ay_yil, gorece_gun, hafta_gunu…
`simdi`	`string`
`not`	`string`

POST/v1/metin/turkcelestir

ücretsiz (anahtarla)

ASCII metne Türkçe harfleri geri koy (ücretsiz)

Anahtar gerekli

"Istanbul Sisli Cumhuriyet Cad" → "İstanbul Şişli Cumhuriyet Cad". Sözlük eşleşmesiyle çalışır: koda gömülü sık sözcükler ve 81 il + paketlenmiş sicildeki il/ilçe/mahalle adları. Sözlükte olmayan sözcüğe dokunmaz, uydurmaz. İki Türkçe okunuşu olan sözcüğü (diş/dış, kar/kâr, sık/sik) değiştirmez, belirsiz listesine yazar. Büyük harfle başlayan sözcükte yer adı öncelikli ("Sisli" → "Şişli"); cümle başındaki sözcük de büyük yazıldığı için bu kural yanılabilir. Büyük/küçük harf düzeni korunur; yazım denetimi değildir. En fazla 5.000 karakter; girdi saklanmaz.

İstek gövdesi
Alan	Tip	Açıklama
`metin`zorunlu	`string`	en fazla 5000 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/turkcelestir" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"metin":"Istanbul Sisli Cumhuriyet Cad"}'

Yanıtlar

200Başarılı
400metin eksikHata
401Anahtar yok ya da geçersizHata
4135.000 karakterden uzunHata
429Kredi limiti aşıldıHata

Yanıt alanları
`metin`	`string`	Türkçeleştirilmiş metin
`degisiklikler`	`object[]`
`degisiklikler[].once`	`string`
`degisiklikler[].sonra`	`string`
`degisiklikler[].kaynak`	`"ad" \| "sozcuk"`
`belirsiz`	`object[]`	Dokunulmayan çok okunuşlu sözcükler
`belirsiz[].sozcuk`	`string`
`belirsiz[].adaylar`	`string[]`
`not`	`string`

POST/v1/metin/ayikla

1 kredi

Serbest metinden alan çıkar (telefon, IBAN, tutar, tarih, adres)

Anahtar gerekli

E-posta gövdesi, WhatsApp siparişi ya da destek kaydından yapılandırılmış alanlar. Model çağrılmaz: telefon BTK planıyla, IBAN mod-97 ile, TCKN ve VKN kontrol haneleriyle doğrulanır, e-posta biçimle bulunur; aynı girdi hep aynı çıktıyı verir. Tarih /v1/metin/tarih kurallarıyla ("yarın", "3 Ekim 2026", "saat 14:30") — simdi verilerek sabitlenebilir. Adres adayı il ya da ilçe adı geçen parçadır; il/ilçe resmî sicilden, mahalle/yol/bina ayrıştırıcıdan gelir, kesin çözüm için /v1/address/resolve. **TCKN ham döndürülmez** (ilk 3 + son 2 hane maskeli); 10 haneli VKN tüzel kişi bilgisi olduğu için açık döner. Ad-soyad çıkarılmaz. En fazla 5.000 karakter; metin saklanmaz. Metnin uzunluğundan bağımsız 1 kredi.

İstek gövdesi
Alan	Tip	Açıklama
`metin`zorunlu	`string`	en fazla 5000 karakter
`simdi`	`string`	Göreli tarihlerin başlangıç anı (ISO 8601); yoksa şimdi

Örnek istek

curl -X POST "$KILAVUZ/v1/metin/ayikla" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"metin":"Sipariş: Moda Cad. No:14 Kadıköy İstanbul, 0532 123 45 67, 1.250,50 TL, yarın teslim"}'

Yanıtlar

200Başarılı
400metin eksik ya da simdi geçersizHata
401Anahtar yok ya da geçersizHata
4135.000 karakterden uzunHata
429Kredi limiti aşıldıHata

Yanıt alanları
`telefonlar`	`object[]`
`telefonlar[].e164`	`string \| null`	444 numaralarında null
`telefonlar[].ulusal`	`string`
`telefonlar[].tur`	`string`
`telefonlar[].metin`	`string`
`telefonlar[].baslangic`	`integer`
`telefonlar[].bitis`	`integer`
`epostalar`	`object[]`
`epostalar[].eposta`	`string`
`epostalar[].baslangic`	`integer`
`epostalar[].bitis`	`integer`
`ibanlar`	`object[]`
`ibanlar[].iban`	`string`
`ibanlar[].bicimli`	`string`
`ibanlar[].banka`	`string`
`ibanlar[].metin`	`string`
`ibanlar[].baslangic`	`integer`
`ibanlar[].bitis`	`integer`
`tcknler`	`object[]`	Ham numara dönmez
`tcknler[].maskeli`	`string`	İlk 3 + son 2 hane: 100******46
`tcknler[].gecerli`	`boolean`
`tcknler[].baslangic`	`integer`
`tcknler[].bitis`	`integer`
`vknler`	`object[]`
`vknler[].vkn`	`string`
`vknler[].gecerli`	`boolean`
`vknler[].baslangic`	`integer`
`vknler[].bitis`	`integer`
`tutarlar`	`object[]`
`tutarlar[].tutar`	`string`	Makine biçimi: "1250.50"
`tutarlar[].bicimli`	`string`	Türkçe biçim: "1.250,50"
`tutarlar[].paraBirimi`	`"TRY" \| "USD" \| "EUR" \| "GBP"`
`tutarlar[].metin`	`string`
`tutarlar[].baslangic`	`integer`
`tutarlar[].bitis`	`integer`
`tarih`	`object`
`tarih.bulundu`	`boolean`
`tarih.tarih`	`string \| null`
`tarih.saat`	`string \| null`
`tarih.iso`	`string \| null`
`tarih.guven`	`number`
`tarih.eslesmeler`	`object[]`
`adresAdaylari`	`object[]`	Puana göre; sicil bağlı değilse boş
`adresAdaylari[].metin`	`string`
`adresAdaylari[].il`	`string`
`adresAdaylari[].ilce`	`string`
`adresAdaylari[].mahalle`	`string`
`adresAdaylari[].yol`	`string`
`adresAdaylari[].binaNo`	`string`
`adresAdaylari[].daire`	`string`
`adresAdaylari[].kat`	`string`
`adresAdaylari[].puan`	`integer`	il/ilçe 2, mahalle/yol 1 puan
`not`	`string`

Spor

Türkiye futbol ligleri (TFF: Süper Lig’den Bölgesel Amatör Lig’e, kadın ligleri ve U19) ile beş büyük Avrupa ligi ve Rusya (Understat): puan durumu, fikstür, sonuçlar, gol krallığı, maç ayrıntısı, form, karşılaşma geçmişi, sezon sonu olasılıkları ve xG. Kaynak ve kaldırma politikası: /kaynaklar.

Futbol

0–1 kredi

TFF lig sayfaları ve Understat, günde iki tur; yanıtta `lisans`, `guncelleme` ve `bayat`. Oyuncu adı yalnız profesyonel liglerde ve Kadın Futbol Süper Ligi’nde; U19, Bölgesel Amatör Lig ve kadın alt liglerinde hiç alınmaz, bu liglerde gol krallığı 422 döner. Hakem ve görevli adı hiçbir ligde tutulmaz. xG yalnız Understat liglerinde. Olasılıklar Monte Carlo tahminidir.

GET/v1/futbol/liglerFutbol ligleri ve tabloda bulunan sezonlar
GET/v1/futbol/takimlarLigin takımları ve kimlikleri
GET/v1/futbol/puan-durumuPuan durumu
GET/v1/futbol/fiksturOynanmamış maçlar
GET/v1/futbol/sonuclarOynanmış maçlar ve skorlar
GET/v1/futbol/gol-kralligiGol krallığı
GET/v1/futbol/mac/{id}Maç detayı
GET/v1/futbol/takim/{id}/formTakımın son maçları (form)
GET/v1/futbol/h2hİki takımın birbiriyle maçları
GET/v1/futbol/olasilikŞampiyonluk, yükselme, play-off ve düşme olasılıkları
GET/v1/futbol/xgxG: takım, oyuncu ya da beklenen puan tablosu

GET/v1/futbol/ligler

ücretsiz (anahtarla)

Futbol ligleri ve tabloda bulunan sezonlar

Anahtar gerekli

Kapsanan ligler: TFF (Süper Lig, 1. Lig, 2. Lig, 3. Lig, BAL, Kadın Süper Lig, Kadın 1./2./3. Lig, U19 PAF) ve Understat (Premier League, La Liga, Bundesliga, Serie A, Ligue 1, RFPL; xG). oyuncuAdi: false liglerde (U19, BAL, kadın alt ligleri) yalnız takım düzeyi veri tutulur. kural: Monte Carlo için varsayılan statü.

Örnek istek

curl "$KILAVUZ/v1/futbol/ligler" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ligler`	`object[]`
`ligler[].kod`	`string`
`ligler[].ad`	`string`
`ligler[].kaynak`	`"tff" \| "understat"`
`ligler[].ulke`	`string`
`ligler[].kademe`	`"profesyonel" \| "amator" \| "genc" \| "kadin"`
`ligler[].oyuncuAdi`	`boolean`
`ligler[].xg`	`boolean`
`ligler[].golKralligi`	`boolean`
`ligler[].kural`	`object`
`ligler[].sezonlar`	`string[]`
`ligler[].kaynakAdi`	`string`
`ligler[].lisans`	`string`
`not`	`string`

GET/v1/futbol/takimlar

ücretsiz (anahtarla)

Ligin takımları ve kimlikleri

Anahtar gerekli

Form, H2H ve takim süzgeci için takım kimlikleri (tff-3604, us-83). ara Türkçe karakter duyarsız.

Parametreler
Ad	Yer	Tip	Açıklama
`lig`zorunlu	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon
`ara`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/futbol/takimlar?lig=super-lig&sezon=2026-2027&ara=galatasaray" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400lig ya da sezon geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`lig`	`string`
`sezon`	`string`
`takimlar`	`object[]`
`takimlar[].takim_id`	`string`
`takimlar[].takim`	`string`
`takimlar[].grup`	`string`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/puan-durumu

1 kredi

Puan durumu

Anahtar gerekli

TFF liglerinde kaynağın puan cetveli (puan silme cezaları dahil); Understat liglerinde sonuçlardan hesaplanır (puan > averaj > atılan gol). Gruplu liglerde (2. Lig, 3. Lig, BAL, kadın alt ligleri) grup grup. Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`lig`zorunlu	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon
`grup`	sorgu	`string`	Gruplu ligde grup adı ("Kırmızı", "Beyaz", "1"…)

Örnek istek

curl "$KILAVUZ/v1/futbol/puan-durumu?lig=super-lig&sezon=2026-2027&grup=Kırmızı" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400lig ya da sezon geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`lig`	`string`
`ligAdi`	`string`
`sezon`	`string`
`gruplar`	`object[]`
`gruplar[].grup`	`string`
`gruplar[].takimlar`	`object[]`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/fikstur

1 kredi

Oynanmamış maçlar

Anahtar gerekli

Sezonun oynanmamış maçları, en yakından. TFF sezon listesi tarih vermiyor: tarih ve saat yalnız seçili hafta ile detayı çekilmiş maçlarda dolu, ötekinde hafta var. Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`lig`zorunlu	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon
`grup`	sorgu	`string`	Gruplu ligde grup adı ("Kırmızı", "Beyaz", "1"…)
`hafta`	sorgu	`integer`
`takim`	sorgu	`string`	Takım kimliği (bkz. /v1/futbol/takimlar)
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/futbol/fikstur?lig=super-lig&sezon=2026-2027&grup=Kırmızı&hafta=…&takim=tff-3604&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`lig`	`string`
`ligAdi`	`string`
`sezon`	`string`
`maclar`	`object[]`
`maclar[].id`	`string`
`maclar[].grup`	`string \| null`
`maclar[].hafta`	`integer \| null`
`maclar[].tarih`	`string \| null (date)`	Türkiye günü
`maclar[].saat`	`string \| null`	Türkiye saati
`maclar[].ev`	`object`
`maclar[].dep`	`object`
`maclar[].skor`	`object \| null`
`maclar[].xg`	`object`	Yalnız Understat liglerinde
`maclar[].stad`	`string \| null`
`maclar[].lig`	`string`
`maclar[].sezon`	`string`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/sonuclar

1 kredi

Oynanmış maçlar ve skorlar

Anahtar gerekli

Sezonun sonuçları, en yeniden. Understat liglerinde maç xG değeri de gelir. Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`lig`zorunlu	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon
`grup`	sorgu	`string`	Gruplu ligde grup adı ("Kırmızı", "Beyaz", "1"…)
`hafta`	sorgu	`integer`
`takim`	sorgu	`string`	Takım kimliği (bkz. /v1/futbol/takimlar)
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/futbol/sonuclar?lig=super-lig&sezon=2026-2027&grup=Kırmızı&hafta=…&takim=tff-3604&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`lig`	`string`
`ligAdi`	`string`
`sezon`	`string`
`maclar`	`object[]`
`maclar[].id`	`string`
`maclar[].grup`	`string \| null`
`maclar[].hafta`	`integer \| null`
`maclar[].tarih`	`string \| null (date)`	Türkiye günü
`maclar[].saat`	`string \| null`	Türkiye saati
`maclar[].ev`	`object`
`maclar[].dep`	`object`
`maclar[].skor`	`object \| null`
`maclar[].xg`	`object`	Yalnız Understat liglerinde
`maclar[].stad`	`string \| null`
`maclar[].lig`	`string`
`maclar[].sezon`	`string`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/gol-kralligi

1 kredi

Gol krallığı

Anahtar gerekli

Yalnız oyuncu adı tutulan liglerde (profesyonel erkek ligleri, Kadın Süper Lig, Understat ligleri); U19, BAL ve kadın alt liglerinde 422. Understat liglerinde oyuncu toplamlarından (xG ile). Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`lig`zorunlu	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/futbol/gol-kralligi?lig=super-lig&sezon=2026-2027&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400lig ya da sezon geçersizHata
401Anahtar yok ya da geçersizHata
422Bu ligde oyuncu adı tutulmuyorHata
429Kredi limiti aşıldıHata

Yanıt alanları
`lig`	`string`
`ligAdi`	`string`
`sezon`	`string`
`oyuncular`	`object[]`
`oyuncular[].sira`	`integer`
`oyuncular[].oyuncu`	`string`
`oyuncular[].takim`	`string`
`oyuncular[].gol`	`integer`
`oyuncular[].xg`	`number \| null`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/mac/{id}

1 kredi

Maç detayı

Anahtar gerekli

Skor, goller (dakika, tür), kartlar, oyuncu değişiklikleri; profesyonel liglerde ilk 11 ve yedekler, Understat liglerinde şut haritası (x, y, xG) ve oyuncu xG/xA. U19, BAL ve kadın alt liglerinde olaylar yalnız taraf ve dakikayla, ad yok. Hakem ve gözlemci hiç yok. Bulunamazsa 404, kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`id`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/futbol/mac/<id>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400Kimlik biçimi geçersizHata
401Anahtar yok ya da geçersizHata
404Maç bulunamadıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`mac`	`object`
`mac.id`	`string`
`mac.grup`	`string \| null`
`mac.hafta`	`integer \| null`
`mac.tarih`	`string \| null (date)`	Türkiye günü
`mac.saat`	`string \| null`	Türkiye saati
`mac.ev`	`object`
`mac.dep`	`object`
`mac.skor`	`object \| null`
`mac.xg`	`object`	Yalnız Understat liglerinde
`mac.stad`	`string \| null`
`mac.lig`	`string`
`mac.sezon`	`string`
`detay`	`object \| null`	goller, kartlar, degisiklikler, kadro?, sutlar?, xgKadro?
`detayYok`	`string`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/takim/{id}/form

1 kredi

Takımın son maçları (form)

Anahtar gerekli

Son n oynanmış maç (varsayılan 5); dizi en yeni sağda (G galibiyet, B beraberlik, M mağlubiyet). Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`id`zorunlu	yol	`string`
`n`	sorgu	`integer`
`lig`	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon

Örnek istek

curl "$KILAVUZ/v1/futbol/takim/<id>/form?n=…&lig=super-lig&sezon=2026-2027" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`takim_id`	`string`
`takim`	`string \| null`
`dizi`	`string`
`mac`	`integer`
`puan`	`integer`
`atilan`	`integer`
`yenilen`	`integer`
`lig`	`string \| null`
`maclar`	`object[]`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/h2h

1 kredi

İki takımın birbiriyle maçları

Anahtar gerekli

Tablodaki bütün sezonlar (lig maçları; geri doldurma en az son 5 sezon), en yeniden. Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip
`a`zorunlu	sorgu	`string`
`b`zorunlu	sorgu	`string`
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/futbol/h2h?a=tff-3604&b=tff-3589&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400a/b geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`a`	`object`
`a.id`	`string`
`a.ad`	`string \| null`
`a.galibiyet`	`integer`
`a.gol`	`integer`
`b`	`object`
`b.id`	`string`
`b.ad`	`string \| null`
`b.galibiyet`	`integer`
`b.gol`	`integer`
`mac`	`integer`
`beraberlik`	`integer`
`maclar`	`object[]`
`maclar[].id`	`string`
`maclar[].grup`	`string \| null`
`maclar[].hafta`	`integer \| null`
`maclar[].tarih`	`string \| null (date)`	Türkiye günü
`maclar[].saat`	`string \| null`	Türkiye saati
`maclar[].ev`	`object`
`maclar[].dep`	`object`
`maclar[].skor`	`object \| null`
`maclar[].xg`	`object`	Yalnız Understat liglerinde
`maclar[].stad`	`string \| null`
`maclar[].lig`	`string`
`maclar[].sezon`	`string`
`kapsam`	`string`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/olasilik

1 kredi

Şampiyonluk, yükselme, play-off ve düşme olasılıkları

Anahtar gerekli

Poisson Monte Carlo (yöntem yanıtta, yontemAciklama): takım güçleri bu sezonun gollerinden, kalan maçlar simüle edilir, başlangıç kaynağın puan tablosu. Statü varsayılanı lig kataloğundan; yukselme, playoff, dusme ile ezilir (0 kapatır). Tohumlu: aynı girdi aynı sonuç. Tahmindir, bahis tavsiyesi değildir. Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`lig`zorunlu	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon
`grup`	sorgu	`string`	Gruplu ligde grup adı ("Kırmızı", "Beyaz", "1"…)
`simulasyon`	sorgu	`integer`
`tohum`	sorgu	`integer`
`yukselme`	sorgu	`integer`	Doğrudan çıkan takım sayısı
`playoff`	sorgu	`string`	Play-off sıraları
`dusme`	sorgu	`integer`	Doğrudan düşen takım sayısı

Örnek istek

curl "$KILAVUZ/v1/futbol/olasilik?lig=super-lig&sezon=2026-2027&grup=Kırmızı&simulasyon=…&tohum=…&yukselme=…&playoff=3-6&dusme=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`lig`	`string`
`ligAdi`	`string`
`sezon`	`string`
`yontem`	`"poisson-monte-carlo"`
`yontemAciklama`	`string`
`simulasyon`	`integer`
`tohum`	`integer`
`kural`	`object`
`kural.yukselme`	`integer`
`kural.dusme`	`integer`
`kural.playoff`	`integer[]`	en fazla 2
`gruplar`	`object[]`
`gruplar[].grup`	`string`
`gruplar[].kalanMac`	`integer`
`gruplar[].uyari`	`string`
`gruplar[].takimlar`	`object[]`
`gruplar[].guc`	`object`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/futbol/xg

1 kredi

xG: takım, oyuncu ya da beklenen puan tablosu

Anahtar gerekli

Yalnız Understat ligleri (xG değerleri Understat'ın modeli). kapsam=takim: sezon toplamları (xG, xGA, npxG, xPts, PPDA); oyuncu: oyuncu xG, xA, şut, kilit pas; xpts: maç xG'lerinden Poisson ile beklenen puan tablosu ve gerçek puanla farkı. TFF liglerinde 422. Boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`lig`zorunlu	sorgu	`string`
`sezon`	sorgu	`string`	"2026-2027" ya da "2026"; yoksa tablodaki en yeni sezon
`kapsam`	sorgu	`"takim" \| "oyuncu" \| "xpts"`
`limit`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/futbol/xg?lig=super-lig&sezon=2026-2027&kapsam=…&limit=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
422Bu ligde xG yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`lig`	`string`
`ligAdi`	`string`
`sezon`	`string`
`kapsam`	`string`
`takimlar`	`object[]`
`oyuncular`	`object[]`
`yontem`	`string`
`yontemAciklama`	`string`
`kaynak`	`string \| null`
`kaynakUrl`	`string \| null`
`lisans`	`string \| null`	Kaynağın şartı ve kaldırma politikası
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

Araçlar

Sahte ama sağlamalı test verisi, uzak MCP ucu ve anahtarsız deneme.

Test verisi

ilk 100 kayıt ücretsiz

Sahte ama sağlamalı TCKN, VKN, IBAN ve GSM; e-posta example.com; adres sicilden gerçek sokak, kapı ve daire rastgele. Kayıtlar gerçek kişiye ait değildir. 100 kayda kadar ücretsiz, sonra her başlanan 100 kayıt 1 kredi. Aynı tohumla aynı liste yeniden üretilir.

POST/v1/test-verisi/uret

ilk 100 kayıt ücretsiz

Sentetik (sahte) test kaydı üret

Anahtar gerekli

Gerçekçi ama uydurma Türk kişi/şirket kayıtları: ad-soyad, TCKN, VKN (+ticaret unvanı), IBAN, GSM, e-posta (example.com), adres (gerçek sicilden il/ilçe/mahalle/sokak + rastgele kapı/daire), doğum tarihi, plaka. Numaralar kendi sağlamalarından geçer (TCKN/VKN kontrol hanesi, IBAN mod-97, BTK numara planı) ama hiçbiri gerçek bir kişiye, şirkete ya da hesaba ait değildir. tohum verilirse aynı liste tekrar üretilir (yanıt tohumu her zaman döner). Kredi: 100 kayda kadar 0, üstü her başlanan 100 kayıt için 1 (500 kayıt = 5 kredi).

İstek gövdesi
Alan	Tip	Açıklama
`adet`	`integer`	1–1000, varsayılan 10
`alanlar`	`"ad" \| "soyad" \| "tckn" \| "vkn" \| "iban" \| "gsm" \| "eposta" \| "adres" \| "dogumTarihi" \| "plaka"[]`	Verilmezse hepsi
`tohum`	`string`	Tekrarlanabilirlik için. en fazla 64 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/test-verisi/uret" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"adet":5,"alanlar":["ad","soyad","tckn","gsm","adres"],"tohum":"demo-1"}'

Yanıtlar

200Başarılı
400adet, alanlar ya da tohum geçersizHata
401Anahtar yok ya da geçersizHata
413adet 1000'den büyükHata
429Kredi limiti aşıldıHata

Yanıt alanları
`adet`	`integer`
`tohum`	`string`
`alanlar`	`string[]`
`kayitlar`	`SentetikKayit[]`
`not`	`string`	Verinin sentetik olduğu uyarısı; kullanıcıya iletin

MCP

keşif anahtarsız

POST/mcp

keşif anahtarsız

Uzak MCP (Streamable HTTP, stateless)

Anahtar yalnız araç çağrısında

Model Context Protocol JSON-RPC ucu. Anahtar yalnız tools/call için gerekli; initialize, tools/list ve ping anahtarsız ve ücretsiz. Anahtarsız tek tools/call 401 anlamında isError döner; içinde tools/call olan anahtarsız toplu istek 401. Kredi, çağrılan aracın REST ucu kadar düşer. Yanıt JSON, SSE yok. Accept: application/json, text/event-stream gerekli. Giriş açıkken (OAuth) ak_live_… anahtarının yanında OAuth erişim belirteci (ak_oat_…) de kabul edilir; kimliksiz tools/call HTTP 401 ve WWW-Authenticate: Bearer resource_metadata="…" döner, geçersiz ya da süresi dolmuş belirteç 401 error="invalid_token".

Gövde: JSON-RPC 2.0 mesajı.

Örnek istek

curl -X POST "$KILAVUZ/mcp" \
  -H "accept: application/json, text/event-stream" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Yanıtlar

200Başarılı
400Geçersiz JSON (JSON-RPC -32700)
401Anahtarsız toplu istekte tools/call

Demo

anahtarsız

POST/v1/demo/adresAnahtarsız adres çözümleme (tanıtım)
POST/v1/demo/ibanAnahtarsız IBAN doğrulama (tanıtım)
GET/v1/demo/eczaneAnahtarsız nöbetçi eczane (tanıtım, ilk 5)
GET/v1/demo/akaryakitAnahtarsız akaryakıt fiyatı (tanıtım)
GET/v1/demo/depremAnahtarsız son 5 deprem (tanıtım)
GET/v1/demo/futbolAnahtarsız Süper Lig puan durumu, ilk 5 (tanıtım)
GET/v1/demo/tazelikKaynak başına son başarılı çekim (tanıtım şeridi)

POST/v1/demo/adres

anahtarsız

Anahtarsız adres çözümleme (tanıtım)

Anahtarsız

Tanıtım sayfasındaki canlı kutu için. Anahtar istemez, kredi düşmez. Yalnız tek adres, en fazla 200 karakter. IP başına 10 dakikada 20 istek; aşılınca 429 ve Retry-After.

İstek gövdesi
Alan	Tip	Açıklama
`q`zorunlu	`string`	en fazla 200 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/demo/adres" \
  -H "content-type: application/json" \
  -d '{"q":"kadikoy moda cad 14"}'

Yanıtlar

200BaşarılıAdresSonucu
400q eksik ya da çok uzunHata
429Demo sınırı dolduHata

POST/v1/demo/iban

anahtarsız

Anahtarsız IBAN doğrulama (tanıtım)

Anahtarsız

Tek IBAN; hesap numarası yanıtta yok. Anahtar istemez, kredi düşmez; yanıt kırpılmış. Bütün veri demoları IP başına 10 dakikada 20 isteği paylaşır; aşılınca 429 ve Retry-After. Tamamı için ücretsiz anahtarla gerçek uç.

İstek gövdesi
Alan	Tip	Açıklama
`iban`zorunlu	`string`	en fazla 64 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/demo/iban" \
  -H "content-type: application/json" \
  -d '{"iban":"TR33 0006 1005 1978 6457 8413 26"}'

Yanıtlar

200Başarılı
400iban eksik ya da çok uzunHata
429Demo sınırı dolduHata

Yanıt alanları
`gecerli`	`boolean`
`bicimli`	`string \| null`
`banka`	`object \| null`
`hata`	`string \| null`
`aciklama`	`string \| null`
`kaynak`	`string`
`guncelleme`	`string \| null`
`not`	`string`

GET/v1/demo/eczane

anahtarsız

Anahtarsız nöbetçi eczane (tanıtım, ilk 5)

Anahtarsız

İl ve ilçe zorunlu; en çok 5 eczane, koordinat yok (toplam bütün listenin sayısı). Anahtar istemez, kredi düşmez; yanıt kırpılmış. Bütün veri demoları IP başına 10 dakikada 20 isteği paylaşır; aşılınca 429 ve Retry-After. Tamamı için ücretsiz anahtarla gerçek uç.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`
`ilce`zorunlu	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/demo/eczane?il=İzmir&ilce=Bornova"

Yanıtlar

200Başarılı
400il ya da ilce eksikHata
422Kapsam dışı ilHata
429Demo sınırı dolduHata

Yanıt alanları
`il`	`string \| null`
`ilce`	`string \| null`
`nobetTarihi`	`string \| null`
`toplam`	`integer`
`eczaneler`	`object[]`	en fazla 5
`eczaneler[].ad`	`string`
`eczaneler[].mahalle`	`string \| null`
`eczaneler[].adres`	`string`
`eczaneler[].telefon`	`string \| null`
`kaynakUrl`	`string`
`lisans`	`string`
`bayat`	`boolean`
`kaynak`	`string`
`guncelleme`	`string \| null`
`not`	`string`

GET/v1/demo/akaryakit

anahtarsız

Anahtarsız akaryakıt fiyatı (tanıtım)

Anahtarsız

İlin ürün özeti (en düşük/ortalama/en yüksek); urun verilirse en ucuz 5 marka. Anahtar istemez, kredi düşmez; yanıt kırpılmış. Bütün veri demoları IP başına 10 dakikada 20 isteği paylaşır; aşılınca 429 ve Retry-After. Tamamı için ücretsiz anahtarla gerçek uç.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`
`urun`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/demo/akaryakit?il=Ankara&urun=motorin"

Yanıtlar

200Başarılı
400il eksikHata
422İl bulunamadıHata
429Demo sınırı dolduHata

Yanıt alanları
`il`	`string`
`ozet`	`object[]`
`enUcuz`	`object[]`	en fazla 5
`enUcuz[].marka`	`string`
`enUcuz[].urun`	`string`
`enUcuz[].fiyat`	`number`
`enUcuz[].tarih`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`bayat`	`boolean`
`kaynak`	`string`
`guncelleme`	`string \| null`
`not`	`string`

GET/v1/demo/deprem

anahtarsız

Anahtarsız son 5 deprem (tanıtım)

Anahtarsız

AFAD'ın son 5 olayı; parametre yok. Anahtar istemez, kredi düşmez; yanıt kırpılmış. Bütün veri demoları IP başına 10 dakikada 20 isteği paylaşır; aşılınca 429 ve Retry-After. Tamamı için ücretsiz anahtarla gerçek uç.

Örnek istek

curl "$KILAVUZ/v1/demo/deprem"

Yanıtlar

200Başarılı
429Demo sınırı dolduHata
503AFAD yanıt vermiyorHata

Yanıt alanları
`depremler`	`object[]`	en fazla 5
`depremler[].zamanTr`	`string`
`depremler[].buyukluk`	`number`
`depremler[].tur`	`string`
`depremler[].derinlikKm`	`number`
`depremler[].yer`	`string`
`depremler[].il`	`string \| null`
`kaynakUrl`	`string`
`lisans`	`string`
`bayat`	`boolean`
`kaynak`	`string`
`guncelleme`	`string \| null`
`not`	`string`

GET/v1/demo/futbol

anahtarsız

Anahtarsız Süper Lig puan durumu, ilk 5 (tanıtım)

Anahtarsız

Güncel sezonun ilk 5 takımı; parametre yok. Anahtar istemez, kredi düşmez; yanıt kırpılmış. Bütün veri demoları IP başına 10 dakikada 20 isteği paylaşır; aşılınca 429 ve Retry-After. Tamamı için ücretsiz anahtarla gerçek uç.

Örnek istek

curl "$KILAVUZ/v1/demo/futbol"

Yanıtlar

200Başarılı
429Demo sınırı dolduHata

Yanıt alanları
`lig`	`string`
`ligAdi`	`string`
`sezon`	`string`
`takimlar`	`object[]`	en fazla 5
`takimlar[].sira`	`integer`
`takimlar[].takim`	`string`
`takimlar[].o`	`integer`
`takimlar[].av`	`integer`
`takimlar[].p`	`integer`
`kaynakUrl`	`string`
`lisans`	`string`
`bayat`	`boolean`
`kaynak`	`string`
`guncelleme`	`string \| null`
`not`	`string`

GET/v1/demo/tazelik

anahtarsız

Kaynak başına son başarılı çekim (tanıtım şeridi)

Anahtarsız

Toplayıcının çektiği her kaynağın son başarılı çekimi ve alan özeti (eczane, akaryakıt, hal, Resmî Gazete, futbol). İstek anında çağrılan kaynaklar (AFAD, TCMB, İBB…) listede yok. Yanıt örnek başına 60 sn önbellekte; IP başına 10 dakikada 30 istek.

Örnek istek

curl "$KILAVUZ/v1/demo/tazelik"

Yanıtlar

200Başarılı
429Demo sınırı dolduHata

Yanıt alanları
`alanlar`	`object[]`
`alanlar[].alan`	`string`
`alanlar[].ad`	`string`
`alanlar[].kaynakSayisi`	`integer`
`alanlar[].tazeKaynakSayisi`	`integer`
`alanlar[].sonCekim`	`string \| null`
`kaynaklar`	`object[]`
`kaynaklar[].ad`	`string`
`kaynaklar[].alan`	`string \| null`
`kaynaklar[].sonCekim`	`string \| null`
`kaynaklar[].bayat`	`boolean`
`kaynak`	`string`
`guncelleme`	`string`

Hesap

Kayıt, anahtar, kullanım, e-posta ve ödeme.

Hesap ve anahtar

ücretsiz

POST/v1/kayitHesap aç, ilk anahtarı al
POST/v1/anahtarYeni anahtar üret
GET/v1/anahtarAnahtarları listele (yalnız önekler)
DELETE/v1/anahtar/{id}Anahtarı iptal et
GET/v1/kullanimKalan kredi
GET/v1/bildirim/kredi-esikKredi eşik uyarısı ayarı
POST/v1/bildirim/kredi-esikKredi eşik uyarısını kur ya da değiştir
DELETE/v1/bildirim/kredi-esikKredi eşik uyarısını kapat
POST/v1/bildirim/kredi-esik/deneDeneme uyarısı gönder

POST/v1/kayit

anahtarsız

Hesap aç, ilk anahtarı al

Anahtarsız

IP başına saatte 5 kayıt. Anahtar yanıtta bir kez döner, bir daha gösterilmez.

İstek gövdesi
Alan	Tip	Açıklama
`email`zorunlu	`string (email)`
`ad`	`string`
`kaynak`	`string`	Nereden geldiniz (ör. "hn"); isteğe bağlı

Örnek istek

curl -X POST "$KILAVUZ/v1/kayit" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

201Hesap açıldı
400Geçersiz e-posta ya da kaynakHata
409E-posta zaten kayıtlıHata
429Kayıt hız sınırıHata

Yanıt alanları
`hesapId`	`string`
`email`	`string`
`plan`	`string`
`anahtar`	`string`
`uyari`	`string`
`dogrulama`	`"gonderildi" \| "dogrulanmis" \| "hiz_siniri" \| "gonderilemedi"`	Doğrulama e-postasının durumu (e-posta doğrulaması açıksa)
`baslangic`	`object`
`baslangic.ornek`	`string`

POST/v1/anahtar

ücretsiz (anahtarla)

Yeni anahtar üret

Anahtar gerekli

En fazla 10 aktif anahtar. Eski anahtar iptal edilmez. Panel oturumuyla da çağrılabilir.

İstek gövdesi
Alan	Tip	Açıklama
`ad`	`string`

Örnek istek

curl -X POST "$KILAVUZ/v1/anahtar" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

201Üretildi
401Anahtar yok ya da geçersizHata
409Anahtar sınırıHata
429Kredi limiti aşıldıHata

Yanıt alanları
`anahtar`	`string`
`onek`	`string`
`uyari`	`string`

GET/v1/anahtar

ücretsiz (anahtarla)

Anahtarları listele (yalnız önekler)

Anahtar gerekli

Örnek istek

curl "$KILAVUZ/v1/anahtar" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`anahtarlar`	`object[]`
`anahtarlar[].id`	`string`
`anahtarlar[].onek`	`string`
`anahtarlar[].ad`	`string \| null`
`anahtarlar[].aktif`	`boolean`
`anahtarlar[].son_kullanim`	`string \| null`
`anahtarlar[].olusturma`	`string`

DELETE/v1/anahtar/{id}

ücretsiz (anahtarla)

Anahtarı iptal et

Anahtar gerekli

Parametreler
Ad	Yer	Tip	Açıklama
`id`zorunlu	yol	`string (uuid)`

Örnek istek

curl -X DELETE "$KILAVUZ/v1/anahtar/<id>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400Geçersiz idHata
401Anahtar yok ya da geçersizHata
404Anahtar bulunamadıHata
409Son aktif anahtar iptal edilemez (API anahtarıyla çağrıldığında; panel oturumunda sınır yok)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`iptal`	`boolean`
`id`	`string`

GET/v1/kullanim

ücretsiz (anahtarla)

Kalan kredi

Anahtar gerekli

API anahtarıyla ya da panel oturumuyla. Panel oturumu kullanım kaydına yazılmaz. Aylık plan açıkken (plan, paket, sinirlar, askida alanları) aylik plan kotası + ücretsiz kotadır (kaynak: "plan+ucretsiz"; parçalar plan ve aylik.ucretsiz), plan yoksa yalnız ücretsiz takvim ayı kotası. Harcama sırası: plan kotası → ücretsiz kota → paket kredisi (ekKredi, süresi dolmamış).

Örnek istek

curl "$KILAVUZ/v1/kullanim" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar geçersizHata
403Hesap askıya alınmışHata
404Hesap bulunamadıHata

Yanıt alanları
`aylik`	`object`
`aylik.kaynak`	`"plan+ucretsiz" \| "ucretsiz"`
`aylik.limit`	`integer`
`aylik.harcanan`	`integer`
`aylik.kalan`	`integer`
`aylik.not`	`string`
`aylik.ucretsiz`	`object`
`plan`	`object \| null`
`plan.kod`	`string`
`plan.ad`	`string`
`plan.limit`	`integer`
`plan.harcanan`	`integer`
`plan.kalan`	`integer`
`plan.donemBitis`	`string (date-time)`
`plan.iptalIstendi`	`string \| null (date-time)`
`ekKredi`	`integer`
`paket`	`object`
`paket.kalan`	`integer`
`paket.sonrakiBitis`	`string \| null (date-time)`
`paket.sonrakiBitisteKalan`	`integer \| null`
`toplamKalan`	`integer`
`sinirlar`	`object`
`sinirlar.dakika`	`integer`
`sinirlar.gunlukTavan`	`integer \| null`
`sinirlar.not`	`string`
`askida`	`boolean`

GET/v1/bildirim/kredi-esik

ücretsiz (anahtarla)

Kredi eşik uyarısı ayarı

Anahtar gerekli

Örnek istek

curl "$KILAVUZ/v1/bildirim/kredi-esik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ayar`	`object \| null`
`ayar.esik`	`integer`
`ayar.url`	`string`	Maskeli (Slack adresi sırdır)
`ayar.eposta`	`boolean`
`ayar.sonGonderim`	`string \| null (date-time)`
`ayar.sonKalan`	`integer \| null`
`ayar.sonHata`	`string \| null`

POST/v1/bildirim/kredi-esik

ücretsiz (anahtarla)

Kredi eşik uyarısını kur ya da değiştir

Anahtar gerekli

Kalan kredi esikin altına inince en çok 24 saatte bir haber verir. url: HTTPS webhook (Slack hooks.slack.com ve Discord gelen webhook'u metin olarak, diğerleri imzalı JSON: {"olay":"kredi.esik","kalan":812,"esik":1000,"zaman":"…"}, başlık x-adreskit-imza: t=<unix>,v1=<hex HMAC-SHA256(imzaSirri, "<t>.<gövde>")>). Adres herkese açık bir IP'ye çözülmeli, yönlendirme izlenmez, 3 sn zaman aşımı. eposta: true: hesabın doğrulanmış e-postasına. İmza sırrı yalnız ilk kurulumda ve sirYenile: true ile döner. Ayar değişince 24 saat sayacı sıfırlanır.

İstek gövdesi
Alan	Tip	Açıklama
`esik`zorunlu	`integer`
`url`	`string \| null (uri)`
`eposta`	`boolean`
`sirYenile`	`boolean`

Örnek istek

curl -X POST "$KILAVUZ/v1/bildirim/kredi-esik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"esik":1000,"url":"https://hooks.slack.com/services/T000/B000/XXXX","eposta":true}'

Yanıtlar

200Güncellendi
201Kuruldu
400Geçersiz eşik ya da adresHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`ayar`	`object`
`ayar.esik`	`integer`
`ayar.url`	`string`	Maskeli (Slack adresi sırdır)
`ayar.eposta`	`boolean`
`ayar.sonGonderim`	`string \| null (date-time)`
`ayar.sonKalan`	`integer \| null`
`ayar.sonHata`	`string \| null`
`imzaSirri`	`string`
`imzaNotu`	`string`
`uyarilar`	`string[]`

Yanıt alanları
`ayar`	`object`
`ayar.esik`	`integer`
`ayar.url`	`string`	Maskeli (Slack adresi sırdır)
`ayar.eposta`	`boolean`
`ayar.sonGonderim`	`string \| null (date-time)`
`ayar.sonKalan`	`integer \| null`
`ayar.sonHata`	`string \| null`
`imzaSirri`	`string`
`imzaNotu`	`string`
`uyarilar`	`string[]`

DELETE/v1/bildirim/kredi-esik

ücretsiz (anahtarla)

Kredi eşik uyarısını kapat

Anahtar gerekli

Örnek istek

curl -X DELETE "$KILAVUZ/v1/bildirim/kredi-esik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
404Kurulu uyarı yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`kapatildi`	`boolean`

POST/v1/bildirim/kredi-esik/dene

ücretsiz (anahtarla)

Deneme uyarısı gönder

Anahtar gerekli

Olay kredi.esik.deneme; hesap başına dakikada bir.

Örnek istek

curl -X POST "$KILAVUZ/v1/bildirim/kredi-esik/dene" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
404Kurulu uyarı yokHata
429Dakikada bir denemeHata

Yanıt alanları
`webhook`	`string \| null`	`gonderildi` ya da `hata: …`
`eposta`	`"gonderildi" \| "kapali" \| "dogrulanmamis" \| "hata" \| null`

E-posta doğrulama ve kurtarma

ücretsiz

GET/v1/eposta/dogrulaE-posta adresini doğrula (e-postadaki bağlantı)
POST/v1/eposta/dogrulama-gonderDoğrulama e-postasını yeniden gönder
POST/v1/kurtarAnahtar kurtarma kodu iste
POST/v1/kurtar/onayKurtarma koduyla yeni anahtar al

GET/v1/eposta/dogrula

anahtarsız

E-posta adresini doğrula (e-postadaki bağlantı)

Anahtarsız

Parametreler
Ad	Yer	Tip	Açıklama
`kod`zorunlu	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/eposta/dogrula?kod=…"

Yanıtlar

200Başarılı
400Kod geçersiz ya da süresi dolmuşHata

Yanıt alanları
`dogrulandi`	`boolean`

POST/v1/eposta/dogrulama-gonder

ücretsiz (anahtarla)

Doğrulama e-postasını yeniden gönder

Anahtar gerekli

Saatte en fazla 3. Bağlantı 24 saat geçerli; yeni bağlantı eskisini geçersiz kılar.

Örnek istek

curl -X POST "$KILAVUZ/v1/eposta/dogrulama-gonder" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata
503E-posta gönderilemiyorHata

Yanıt alanları
`dogrulama`	`"gonderildi" \| "dogrulanmis"`

POST/v1/kurtar

anahtarsız

Anahtar kurtarma kodu iste

Anahtarsız

Hesap olsun olmasın aynı yanıt döner. Kod e-postayla gelir, 30 dakika geçerli. IP başına saatte 5, hesap başına saatte 3 istek.

İstek gövdesi
Alan	Tip	Açıklama
`email`zorunlu	`string (email)`

Örnek istek

curl -X POST "$KILAVUZ/v1/kurtar" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

202İstek alındı
400Geçersiz e-postaHata
429Hız sınırıHata
503E-posta gönderilemiyorHata

Yanıt alanları
`mesaj`	`string`

POST/v1/kurtar/onay

anahtarsız

Kurtarma koduyla yeni anahtar al

Anahtarsız

eskileriIptal: true önceki bütün anahtarları kapatır. Kod tek kullanımlık; anahtar yanıtta bir kez döner.

İstek gövdesi
Alan	Tip	Açıklama
`kod`zorunlu	`string`
`eskileriIptal`	`boolean`	varsayılan false

Örnek istek

curl -X POST "$KILAVUZ/v1/kurtar/onay" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

201Anahtar üretildi
400Kod geçersiz ya da süresi dolmuşHata
409Anahtar sınırı (kod harcanmadı)Hata

Yanıt alanları
`anahtar`	`string`
`onek`	`string`
`iptalEdilen`	`integer`
`uyari`	`string`

Giriş

anahtarsız

Parolasız giriş: Google, Apple ya da e-postaya gelen 6 haneli kod. Hesap ilk girişte açılır.

GET/v1/giris/yontemlerAçık giriş yöntemleri
POST/v1/giris/epostaE-postaya giriş kodu gönder
POST/v1/giris/eposta/dogrulaKodla ya da bağlantıyla giriş, panel oturumu al
GET/v1/giris/googleGoogle ile giriş (tarayıcı yönlendirmesi)
GET/v1/giris/appleApple ile giriş (tarayıcı yönlendirmesi)

GET/v1/giris/yontemler

anahtarsız

Açık giriş yöntemleri

Anahtarsız

Örnek istek

curl "$KILAVUZ/v1/giris/yontemler"

Yanıtlar

200Başarılı

Yanıt alanları
`google`	`boolean`
`apple`	`boolean`
`eposta`	`boolean`

POST/v1/giris/eposta

anahtarsız

E-postaya giriş kodu gönder

Anahtarsız

6 haneli kod ve tek tıklık bağlantı, 15 dakika, tek kullanımlık. Hesap yoksa ilk girişte açılır. IP başına saatte 10, e-posta başına saatte 3. Gönderici yoksa 503.

İstek gövdesi
Alan	Tip	Açıklama
`email`zorunlu	`string (email)`

Örnek istek

curl -X POST "$KILAVUZ/v1/giris/eposta" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

202Kod gönderildi
400Geçersiz e-postaHata
429Hız sınırıHata
503E-posta gönderilemiyorHata

Yanıt alanları
`istek`	`string`	`gi_…`; kodla birlikte gönderilir
`gecerlilikDakika`	`integer`
`mesaj`	`string`

POST/v1/giris/eposta/dogrula

anahtarsız

Kodla ya da bağlantıyla giriş, panel oturumu al

Anahtarsız

{istek, kod} ya da {baglanti}. 5 yanlış denemede kod yanar. Yanıtta panel belirteci; ayrıca API alanında httpOnly çerez.

İstek gövdesi
Alan	Tip	Açıklama
`istek`	`string`
`kod`	`string`
`baglanti`	`string`	`gk_…`

Örnek istek

curl -X POST "$KILAVUZ/v1/giris/eposta/dogrula" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

200Başarılı
400Kod geçersiz, yanlış ya da süresi dolmuşHata
429Hız sınırıHata

Yanıt alanları
`oturum`	`string`	`ak_ses_…` panel belirteci; `Authorization: Bearer` ile gönderilir
`tur`	`object`
`son`	`string (date-time)`
`yeniHesap`	`boolean`	Bu girişte hesap açıldı mı

GET/v1/giris/google

anahtarsız

Google ile giriş (tarayıcı yönlendirmesi)

Anahtarsız

OIDC yetki kodu + PKCE. sonra=panel (varsayılan) girişten sonra PANEL_URL/giris/tamam#devir=… adresine döner.

Parametreler
Ad	Yer	Tip	Açıklama
`sonra`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/giris/google?sonra=…"

Yanıtlar

302Google'a yönlendirme
429Hız sınırıHata
503Google girişi kapalıHata

GET/v1/giris/apple

anahtarsız

Apple ile giriş (tarayıcı yönlendirmesi)

Anahtarsız

Parametreler
Ad	Yer	Tip	Açıklama
`sonra`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/v1/giris/apple?sonra=…"

Yanıtlar

302Apple'a yönlendirme
429Hız sınırıHata
503Apple girişi kapalıHata

Panel oturumu

anahtarsız

Panel `authorization: Bearer ak_ses_…` belirteciyle çalışır; belirteç 12 saat geçerlidir. Anahtar, kullanım ve ödeme uçları bu belirteci de kabul eder.

POST/v1/oturum/devirDevir kodunu panel oturumuna çevir
POST/v1/oturum/cikisÇıkış
GET/v1/benHesap bilgisi
GET/v1/baglantilarOAuth bağlantıları (Claude vb.)
DELETE/v1/baglantilar/{id}OAuth bağlantısını kapat
DELETE/v1/hesapHesabı sil (KVKK)

POST/v1/oturum/devir

anahtarsız

Devir kodunu panel oturumuna çevir

Anahtarsız

Tarayıcı girişinden sonra panel #devir=ak_dvr_… alır (2 dakika, tek kullanımlık) ve bununla belirteç ister.

İstek gövdesi
Alan	Tip	Açıklama
`devir`zorunlu	`string`

Örnek istek

curl -X POST "$KILAVUZ/v1/oturum/devir" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

200Başarılı
400Devir kodu geçersiz, kullanılmış ya da süresi dolmuşHata

Yanıt alanları
`oturum`	`string`	`ak_ses_…` panel belirteci; `Authorization: Bearer` ile gönderilir
`tur`	`object`
`son`	`string (date-time)`
`yeniHesap`	`boolean`	Bu girişte hesap açıldı mı

POST/v1/oturum/cikis

anahtarsız

Çıkış

Anahtarsız

Panel belirtecini, bağlı çerez oturumunu ve o çerezden doğan bütün belirteçleri kapatır.

Örnek istek

curl -X POST "$KILAVUZ/v1/oturum/cikis"

Yanıtlar

200Başarılı
401Oturum yok ya da süresi dolmuşHata

Yanıt alanları
`cikis`	`boolean`

GET/v1/ben

anahtarsız

Hesap bilgisi

Anahtarsız

Örnek istek

curl "$KILAVUZ/v1/ben"

Yanıtlar

200Başarılı
401Oturum yok ya da süresi dolmuşHata

Yanıt alanları
`hesapId`	`string`
`email`	`string`
`dogrulandi`	`boolean`
`plan`	`string`
`olusturma`	`string`
`aylikKredi`	`integer`
`ekKredi`	`integer`
`girisYontemleri`	`"eposta" \| "google" \| "apple"[]`
`askida`	`boolean`	Aylık plan açıkken
`aylikPlan`	`object \| null`	Aylık plan açıkken; etkin plan
`aylikPlan.kod`	`string`
`aylikPlan.saglayici`	`string`
`aylikPlan.donemBitis`	`string`
`aylikPlan.iptalIstendi`	`string \| null`

GET/v1/baglantilar

anahtarsız

OAuth bağlantıları (Claude vb.)

Anahtarsız

Örnek istek

curl "$KILAVUZ/v1/baglantilar"

Yanıtlar

200Başarılı
401Oturum yok ya da süresi dolmuşHata

Yanıt alanları
`baglantilar`	`object[]`
`baglantilar[].id`	`string`
`baglantilar[].ad`	`string \| null`
`baglantilar[].istemciId`	`string`
`baglantilar[].olusturma`	`string`
`baglantilar[].sonKullanim`	`string \| null`

DELETE/v1/baglantilar/{id}

anahtarsız

OAuth bağlantısını kapat

Anahtarsız

Parametreler
Ad	Yer	Tip	Açıklama
`id`zorunlu	yol	`string (uuid)`

Örnek istek

curl -X DELETE "$KILAVUZ/v1/baglantilar/<id>"

Yanıtlar

200Başarılı
400Geçersiz idHata
401Oturum yok ya da süresi dolmuşHata
404Bağlantı bulunamadıHata

Yanıt alanları
`iptal`	`boolean`
`id`	`string`

DELETE/v1/hesap

anahtarsız

Hesabı sil (KVKK)

Anahtarsız

Gövdede onay hesabın e-postası olmalı. Ödemesi olmayan hesap silinir, ödemesi olan anonimleşir (e-posta, anahtarlar, oturumlar, bağlantılar silinir; ödeme kaydı kimliksiz kalır).

İstek gövdesi
Alan	Tip	Açıklama
`onay`zorunlu	`string (email)`

Örnek istek

curl -X DELETE "$KILAVUZ/v1/hesap" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

200Başarılı
400Onay e-postası eşleşmediHata
401Oturum yok ya da süresi dolmuşHata
409Yenilenen aylık plan var; önce DELETE /v1/abonelikHata
501Hesap silme bu sunucuda kapalıHata

Yanıt alanları
`sonuc`	`"silindi" \| "anonimlestirildi"`

OAuth (MCP bağlayıcıları)

anahtarsız

Claude gibi MCP istemcilerinin anahtarsız bağlanması için. Bağlantılar panelden kesilir.

GET/.well-known/oauth-protected-resourceKorunan kaynak meta verisi (RFC 9728)
GET/.well-known/oauth-protected-resource/mcp`/mcp` için korunan kaynak meta verisi (RFC 9728)
GET/.well-known/oauth-authorization-serverYetkilendirme sunucusu meta verisi (RFC 8414)
POST/oauth/registerDinamik istemci kaydı (RFC 7591)
GET/oauth/authorizeYetkilendirme (tarayıcı)
POST/oauth/tokenBelirteç (authorization_code + PKCE, refresh_token)
POST/oauth/revokeBelirteç iptali (RFC 7009)

GET/.well-known/oauth-protected-resource

anahtarsız

Korunan kaynak meta verisi (RFC 9728)

Anahtarsız

Örnek istek

curl "$KILAVUZ/.well-known/oauth-protected-resource"

Yanıtlar

200Başarılı

Yanıt alanları
`resource`	`string`
`authorization_servers`	`string[]`
`scopes_supported`	`string[]`

GET/.well-known/oauth-protected-resource/mcp

anahtarsız

`/mcp` için korunan kaynak meta verisi (RFC 9728)

Anahtarsız

Örnek istek

curl "$KILAVUZ/.well-known/oauth-protected-resource/mcp"

Yanıtlar

200Başarılı

Yanıt alanları
`resource`	`string`
`authorization_servers`	`string[]`

GET/.well-known/oauth-authorization-server

anahtarsız

Yetkilendirme sunucusu meta verisi (RFC 8414)

Anahtarsız

Örnek istek

curl "$KILAVUZ/.well-known/oauth-authorization-server"

Yanıtlar

200Başarılı

POST/oauth/register

anahtarsız

Dinamik istemci kaydı (RFC 7591)

Anahtarsız

Yalnız açık istemci (token_endpoint_auth_method: none). Geri dönüş adresleri: Claude (https://claude.ai/api/mcp/auth_callback, https://claude.com/api/mcp/auth_callback), http://localhost ve 127.0.0.1 (port serbest) ve sunucuda tanımlı ekler. IP başına saatte 20.

İstek gövdesi
Alan	Tip	Açıklama
`redirect_uris`zorunlu	`string[]`
`client_name`	`string`
`grant_types`	`string[]`
`response_types`	`string[]`

Örnek istek

curl -X POST "$KILAVUZ/oauth/register" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

201Kaydedildi
400invalid_redirect_uri ya da invalid_client_metadata
429Hız sınırı

Yanıt alanları
`client_id`	`string`
`client_id_issued_at`	`integer`
`redirect_uris`	`string[]`

GET/oauth/authorize

anahtarsız

Yetkilendirme (tarayıcı)

Anahtarsız

response_type=code, code_challenge_method=S256 ve state zorunlu. Giriş yoksa giriş sayfasına, sonra onay ekranına gider.

Parametreler
Ad	Yer	Tip
`response_type`	sorgu	`string`
`client_id`	sorgu	`string`
`redirect_uri`	sorgu	`string`
`state`	sorgu	`string`
`code_challenge`	sorgu	`string`
`code_challenge_method`	sorgu	`string`
`scope`	sorgu	`string`
`resource`	sorgu	`string`

Örnek istek

curl "$KILAVUZ/oauth/authorize?response_type=…&client_id=…&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=…&scope=…&resource=…"

Yanıtlar

302Onay ekranına ya da hatayla istemciye yönlendirme
400Bilinmeyen istemci ya da geri dönüş adresi (HTML, yönlendirme yok)

POST/oauth/token

anahtarsız

Belirteç (authorization_code + PKCE, refresh_token)

Anahtarsız

Erişim belirteci 1 saat, yenileme belirteci 30 gün ve her kullanımda döner; eski yenileme belirteci yeniden kullanılırsa bağlantı kapatılır.

İstek gövdesi
Alan	Tip	Açıklama
`grant_type`zorunlu	`"authorization_code" \| "refresh_token"`
`client_id`zorunlu	`string`
`code`	`string`
`redirect_uri`	`string`
`code_verifier`	`string`
`refresh_token`	`string`
`resource`	`string`

Örnek istek

curl -X POST "$KILAVUZ/oauth/token" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

200Başarılı
400invalid_grant, invalid_target, unsupported_grant_type
401invalid_client
429Hız sınırı

Yanıt alanları
`access_token`	`string`
`token_type`	`object`
`expires_in`	`integer`
`refresh_token`	`string`
`scope`	`string`

POST/oauth/revoke

anahtarsız

Belirteç iptali (RFC 7009)

Anahtarsız

İstek gövdesi
Alan	Tip	Açıklama
`token`zorunlu	`string`
`token_type_hint`	`string`

Örnek istek

curl -X POST "$KILAVUZ/oauth/revoke" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

200İptal edildi (tanınmayan belirteçte de 200)
429Hız sınırı

Ödeme

ücretsiz

Kredi paketleri yakında. Ödeme sağlayıcıları açılana kadar ödeme başlatma ucu 503 döner.

GET/v1/paketlerKredi paketleri ve fiyatlar
GET/v1/planlarAylık planlar ve fiyatlar
POST/v1/odemeÖdeme başlat
GET/v1/odemeÖdeme geçmişi
GET/v1/abonelikEtkin plan ve plan geçmişi
POST/v1/abonelikAylık plan başlat
DELETE/v1/abonelikPlanı dönem sonunda bitir

GET/v1/paketler

anahtarsız

Kredi paketleri ve fiyatlar

Anahtarsız

Örnek istek

curl "$KILAVUZ/v1/paketler"

Yanıtlar

200Başarılı

Yanıt alanları
`paketler`	`object[]`
`paketler[].kod`	`string`
`paketler[].ad`	`string`
`paketler[].kredi`	`integer`
`paketler[].fiyat`	`object`
`gecerlilikAy`	`integer`	Paket kredisi satın alındığı günden bu kadar ay geçerli
`sinirlar`	`object`	Plansız, paket bakiyeli hesabın hesap başına sınırları
`sinirlar.dakika`	`integer`
`sinirlar.gunlukTavan`	`integer`
`not`	`string`

GET/v1/planlar

anahtarsız

Aylık planlar ve fiyatlar

Anahtarsız

Plan kotası dönem başında yenilenir, devretmez; ücretsiz aylık kota plana eklenir. Fiyatlar KDV dahil. Satın alma POST /v1/abonelik (açıldığında).

Örnek istek

curl "$KILAVUZ/v1/planlar"

Yanıtlar

200Başarılı

Yanıt alanları
`planlar`	`object[]`
`planlar[].kod`	`string`
`planlar[].ad`	`string`
`planlar[].aylikKredi`	`integer`
`planlar[].fiyat`	`object`
`planlar[].sinirlar`	`object`
`not`	`string`

POST/v1/odeme

ücretsiz (anahtarla)

Ödeme başlat

Anahtar gerekli

TRY → PayTR, USD → Polar. Sağlayıcı yapılandırılmamışsa 503. Paket kredisi 12 ay geçerli. faturaUlke (ISO 3166-1 alfa-2) ilk ödemede hesaba yazılır; Türkiye'ye faturalı hesap yalnız TRY öder (400 TR_YALNIZ_TRY).

İstek gövdesi
Alan	Tip	Açıklama
`paket`zorunlu	`string`
`paraBirimi`	`"TRY" \| "USD"`
`faturaUlke`	`string`

Örnek istek

curl -X POST "$KILAVUZ/v1/odeme" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"paket":"kucuk","paraBirimi":"TRY","faturaUlke":"TR"}'

Yanıtlar

201Ödeme sayfası hazır
400Geçersiz paket, para birimi ya da ülkeHata
401Anahtar yok ya da geçersizHata
403Hesap askıya alınmışHata
404Hesap bulunamadıHata
429Kredi limiti aşıldıHata
502Sağlayıcı hatasıHata
503Bu para birimiyle ödeme kapalıHata

Yanıt alanları
`odemeId`	`string`
`paket`	`string`
`kredi`	`integer`
`odemeUrl`	`string`

GET/v1/odeme

ücretsiz (anahtarla)

Ödeme geçmişi

Anahtar gerekli

Örnek istek

curl "$KILAVUZ/v1/odeme" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`odemeler`	`object[]`

GET/v1/abonelik

ücretsiz (anahtarla)

Etkin plan ve plan geçmişi

Anahtar gerekli

Örnek istek

curl "$KILAVUZ/v1/abonelik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`etkin`	`object \| null`
`etkin.id`	`string`
`etkin.plan`	`string`
`etkin.saglayici`	`"paytr" \| "polar"`
`etkin.durum`	`string`
`etkin.fiyat`	`object`
`etkin.donemBaslangic`	`string (date-time)`
`etkin.donemBitis`	`string (date-time)`
`etkin.iptalIstendi`	`string \| null (date-time)`
`etkin.aylikKredi`	`integer`
`etkin.harcanan`	`integer`
`etkin.kalan`	`integer`
`etkin.yenilenir`	`boolean`
`gecmis`	`object[]`

POST/v1/abonelik

ücretsiz (anahtarla)

Aylık plan başlat

Anahtar gerekli

USD → Polar abonelik (her ay otomatik çekim). TRY → PayTR tek ödeme, bir aylık dönem; otomatik çekim yok, bitişe 3 gün kala aynı plan yeniden alınabilir. Etkin plan varken 409. Türkiye'ye faturalı hesap yalnız TRY. Sağlayıcı yapılandırılmamışsa 503.

İstek gövdesi
Alan	Tip	Açıklama
`plan`zorunlu	`string`
`paraBirimi`	`"TRY" \| "USD"`
`faturaUlke`	`string`

Örnek istek

curl -X POST "$KILAVUZ/v1/abonelik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"plan":"gelistirici","paraBirimi":"TRY","faturaUlke":"TR"}'

Yanıtlar

201Ödeme sayfası hazır
400Geçersiz plan, para birimi ya da ülkeHata
401Anahtar yok ya da geçersizHata
403Hesap askıya alınmışHata
404Hesap bulunamadıHata
409Etkin plan varHata
429Kredi limiti aşıldıHata
502Sağlayıcı hatasıHata
503Bu para birimiyle plan kapalıHata

Yanıt alanları
`abonelikId`	`string`
`plan`	`string`
`aylikKredi`	`integer`
`paraBirimi`	`string`
`odemeUrl`	`string`

DELETE/v1/abonelik

ücretsiz (anahtarla)

Planı dönem sonunda bitir

Anahtar gerekli

Yenileme durur; dönem sonuna kadar kota kullanılır, iade yok.

Örnek istek

curl -X DELETE "$KILAVUZ/v1/abonelik" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
404İptal edilecek etkin plan yokHata
409Abonelik sağlayıcıda henüz eşleşmediHata
429Kredi limiti aşıldıHata
502Sağlayıcı hatasıHata
503USD ile plan kapalıHata

Yanıt alanları
`iptal`	`boolean`
`abonelikId`	`string`
`donemBitis`	`string (date-time)`

Sistem

ücretsiz

GET/healthCanlılık
GET/openapi.jsonBu şema
POST/v1/topluGenel toplu istek (en çok 50 alt istek)

GET/health

anahtarsız

Canlılık

Anahtarsız

Örnek istek

curl "$KILAVUZ/health"

Yanıtlar

200Başarılı

Yanıt alanları
`ok`	`boolean`

GET/openapi.json

anahtarsız

Bu şema

Anahtarsız

Örnek istek

curl "$KILAVUZ/openapi.json"

Yanıtlar

200Başarılı

POST/v1/toplu

ücretsiz (anahtarla)

Genel toplu istek (en çok 50 alt istek)

Anahtar gerekli

Birden çok /v1/* çağrısını tek HTTP isteğinde yapar (5 eş zamanlı). Her alt istek aynı anahtarla, kendi fiyatıyla kredi düşer ve dakika sınırına ayrı sayılır; toplu ucun kendisi 0 kredi. Alt isteğin hatası yalnız kendi durumunda görünür, bütün yanıt 200 döner. Hesap, anahtar, ödeme, giriş, bildirim ve demo uçları alt istek olamaz. X-Kalan-Kredi alt isteklerden sonraki değerdir. Adres, IBAN, TCKN/VKN/telefon uçlarının kendi dizi girdisi (1.000'e kadar) bu uçtan daha verimlidir.

İstek gövdesi
Alan	Tip	Açıklama
`istekler`zorunlu	`object[]`	en fazla 50
`istekler[].yol`zorunlu	`string`	`/v1/` ile başlar; sorgu dizgesi içerebilir
`istekler[].yontem`	`"GET" \| "POST"`	Yoksa: govde varsa POST, yoksa GET
`istekler[].govde`	`object`	POST gövdesi (JSON)
`istekler[].sorgu`	`object`
`istekler[].kimlik`	`string`	Sonuçta aynen döner. en fazla 100 karakter

Örnek istek

curl -X POST "$KILAVUZ/v1/toplu" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{"istekler":[{"yol":"/v1/il/34"},{"yol":"/v1/iban/dogrula","govde":{"iban":"TR330006100519786457841326"},"kimlik":"musteri-7"}]}'

Yanıtlar

200Başarılı
400Geçersiz alt istek (sıra numarasıyla)Hata
401Anahtar yok ya da geçersizHata
41350'den fazla alt istekHata
429Kredi limiti aşıldıHata

Yanıt alanları
`sonuclar`	`object[]`	Girdi sırasıyla
`sonuclar[].kimlik`	`string`
`sonuclar[].durum`	`integer`
`sonuclar[].govde`	`object`	Alt uç yanıtı (JSON ya da metin)
`ozet`	`object`
`ozet.toplam`	`integer`
`ozet.basarili`	`integer`
`ozet.hatali`	`integer`
`ozet.kalanKredi`	`integer`

Diğer

Henüz bir gruba yerleştirilmemiş uçlar.

borsa

1 kredi

GET/v1/borsa/fiyatTicaret borsası fiyatları (TOBB)
GET/v1/borsa/tmoTMO piyasa bülteni: yurt içi hububat ve bakliyat fiyatları

GET/v1/borsa/fiyat

1 kredi

Ticaret borsası fiyatları (TOBB)

Anahtar gerekli

Ticaret borsalarında tescil edilen işlemlerin fiyatları: hububat, bakliyat, yağlı tohum, kuru meyve, pamuk, canlı hayvan… En az, en çok ve ortalama fiyat (TL / birim), miktar, işlem adedi ve tutarı. Kaynak TOBB Borsa Fiyat portalı; günde iki kez çekilir, istek anında kaynağa gidilmez. Her (borsa, ürün) için aralıktaki **son işlem günü** döner; tarih verilirse yalnız o gün işlem görenler. Kapsam: portalda o ay fiyat giren borsalar. Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`urun`	sorgu	`string`	Ürün adında geçen metin (Türkçe karaktersiz de olur)
`borsa`	sorgu	`string`	Borsa adında geçen metin ya da TOBB borsa kodu
`grup`	sorgu	`string`	Ana ürün grubu (HUBUBAT, BAKLİYAT VE MAMÜLLERİ, KURU MEYVELER, TEKSTİL HAMMADDELERİ…)
`tarih`	sorgu	`string (date)`	Tek işlem günü (YYYY-AA-GG); gun ile birlikte verilmez
`gun`	sorgu	`integer`	Bugünden geriye kaç gün

Örnek istek

curl "$KILAVUZ/v1/borsa/fiyat?urun=buğday&borsa=Konya&grup=hububat&tarih=2026-09-18&gun=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih ya da gun geçersizHata
401Anahtar yok ya da geçersizHata
422bilinmeyen ürün grubuHata
429Kredi limiti aşıldıHata

Yanıt alanları
`aralik`	`object`
`aralik.baslangic`	`string`
`aralik.bitis`	`string`
`fiyatlar`	`object[]`
`fiyatlar[].borsa`	`string`
`fiyatlar[].borsaKod`	`string`
`fiyatlar[].urun`	`string`
`fiyatlar[].urunKod`	`string`	TOBB ürün kodu, ana-alt
`fiyatlar[].grup`	`string`
`fiyatlar[].birim`	`string`	KG, TON, ADET…
`fiyatlar[].islemTarihi`	`string (date)`
`fiyatlar[].islemZamani`	`string`	Son işlem, Türkiye saati (ISO 8601)
`fiyatlar[].enAz`	`number`
`fiyatlar[].enCok`	`number`
`fiyatlar[].ortalama`	`number`	Ağırlıklı ortalama, TL / birim
`fiyatlar[].miktar`	`number`
`fiyatlar[].adet`	`integer`
`fiyatlar[].tutar`	`number`	TL
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

GET/v1/borsa/tmo

1 kredi

TMO piyasa bülteni: yurt içi hububat ve bakliyat fiyatları

Anahtar gerekli

TMO Günlük Piyasa ve Borsa Fiyatları Bülteni'nin yurt içi bölümü: buğday çeşitleri, arpa, mısır, yulaf, soya, ayçiçeği, kepekler, mercimek, nohut, fasulye, pirinç. Her ürün için TMO'nun piyasa fiyatı (tur=piyasa), seçili ticaret borsalarının fiyatı ve miktarı (borsa, yer = borsa) ve sektör fiyatları (sektor, cesit). TL/ton ve $/ton; geçen yılın aynı günü ve yıllık değişim yalnız bültenin güncel gününde. Bülten PDF'i iş günleri yayımlanır; TMO sitesi yurt dışı IP'ye kapalı olduğundan Türkiye'deki bir makineden gündüz (08:30–20:30) iki saatte bir çekilir, o makine kapalıysa bayat (guncelleme son başarılı çekim). Bakliyat ve pirinç haftalık. Her kalem için aralıktaki **son gün** döner. TMO'nun kendi alım/satış fiyatları ve uluslararası fiyatlar bu uçta yok. Liste boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`urun`	sorgu	`string`	Ürün ya da çeşit adında geçen metin (Türkçe karaktersiz de olur)
`yer`	sorgu	`string`	Borsa adında geçen metin
`tur`	sorgu	`"piyasa" \| "borsa" \| "sektor"`
`tarih`	sorgu	`string (date)`	Tek gün (YYYY-AA-GG); gun ile birlikte verilmez
`gun`	sorgu	`integer`	Bugünden geriye kaç gün

Örnek istek

curl "$KILAVUZ/v1/borsa/tmo?urun=buğday&yer=Konya&tur=…&tarih=2026-09-18&gun=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400tarih, gun ya da tur geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`aralik`	`object`
`aralik.baslangic`	`string`
`aralik.bitis`	`string`
`fiyatlar`	`object[]`
`fiyatlar[].urun`	`string`	Bültendeki grup başlığı, örn. MAKARNALIK BUĞDAY
`fiyatlar[].cesit`	`string \| null`	Sektör ve kepek satırlarında alt kalem
`fiyatlar[].yer`	`string \| null`	Borsa satırında borsa
`fiyatlar[].tur`	`"piyasa" \| "borsa" \| "sektor"`
`fiyatlar[].tarih`	`string (date)`
`fiyatlar[].miktarTon`	`number \| null`
`fiyatlar[].tlTon`	`number`
`fiyatlar[].usdTon`	`number \| null`
`fiyatlar[].gecenYilTlTon`	`number \| null`	Geçen yılın aynı günü
`fiyatlar[].yillikDegisim`	`number \| null`	Yüzde
`fiyatlar[].bultenTarihi`	`string (date)`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

kesinti

1 kredi

GET/v1/kesinti

1 kredi

Planlı ve anlık elektrik/su kesintileri

Anahtar gerekli

İlin (isteğe bağlı ilçenin) süren ve gelecek kesintileri: dağıtım şirketlerinin ve su idarelerinin duyuruları. Veri günde iki kez çekilir, istek anında kaynağa gidilmez; kaynaklardan birinin son başarılı çekimi tazelik süresinden eskiyse bayat: true. Yalnız il, ilçe ve mahalle (sokak yok); açıklamalardan telefon, e-posta ve kişi adı izleri atılır. Elektrik: Samsun, Ordu, Çorum, Amasya, Sinop (YEDAŞ), Kayseri ve Sivas-Gemerek (KCETAŞ), Bursa, Balıkesir, Çanakkale, Yalova (UEDAŞ), İstanbul Avrupa yakası (BEDAŞ), Antalya, Burdur, Isparta (AEDAŞ). Su: İzmir, Ankara, Bursa. YEDAŞ ve BUSKİ yurt dışı IP'ye kapalı olduğu için Türkiye'deki bir makineden gündüz iki saatte bir çekilir; o makine kapalıysa veri eskir, bayat ve kaynağın guncellemesi bunu gösterir. Liste boşsa kredi düşmez. Kapsam dışı il 422, kapsam ve gerekçeli kapsamDisi listesi.

Parametreler
Ad	Yer	Tip	Açıklama
`il`zorunlu	sorgu	`string`	İl adı ya da plaka
`ilce`	sorgu	`string`
`tur`	sorgu	`"elektrik" \| "su"`	Yoksa ikisi

Örnek istek

curl "$KILAVUZ/v1/kesinti?il=Bursa&ilce=Nilüfer&tur=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il eksik / tur geçersizHata
401Anahtar yok ya da geçersizHata
422Bu il için kaynak yok
429Kredi limiti aşıldıHata

Yanıt alanları
`il`	`string`
`ilce`	`string \| null`
`tur`	`string \| null`
`kesintiler`	`object[]`
`kesintiler[].tur`	`"elektrik" \| "su"`
`kesintiler[].ilce`	`string \| null`
`kesintiler[].mahalleler`	`string[]`
`kesintiler[].baslangic`	`string \| null`	ISO 8601 (+03:00)
`kesintiler[].bitis`	`string \| null`
`kesintiler[].planli`	`boolean`	Bildirimli/planlı (true) ya da arıza (false)
`kesintiler[].neden`	`string \| null`
`kesintiler[].aciklama`	`string \| null`
`kesintiler[].kaynak`	`string`
`kapsamNotu`	`string \| null`	Kısmi kapsam notu (ör. İstanbul yalnız Avrupa yakası)
`kaynaklar`	`object[]`
`kaynaklar[].ad`	`string`
`kaynaklar[].aciklama`	`string`
`kaynaklar[].tur`	`string`
`kaynaklar[].url`	`string`
`kaynaklar[].lisans`	`string`
`kaynaklar[].anlik`	`boolean`
`kaynaklar[].guncelleme`	`string \| null`
`kaynaklar[].bayat`	`boolean`
`kaynak`	`string`
`guncelleme`	`string \| null`	İlgili kaynakların en eski son başarılı çekimi (ISO 8601); biri hiç çekilmediyse null
`bayat`	`boolean`
`not`	`string`

ilan

1 kredi

GET/v1/ilan/ara

1 kredi

ilan.gov.tr resmî ilanlarında arama

Anahtar gerekli

İhale, icra/mahkeme satışı (taşınmaz ve taşınır), kamu personel ve diğer resmî ilanların künyesi: başlık, kurum, il/ilçe, yayın ve satış/ihale tarihi, muhammen bedel, ilanın bağlantısı. Tebligat ve iflas ilanları alınmaz; icra ilanlarının metni ve dosya numarası saklanmaz. Veri günde iki kez çekilir, 180 gün tutulur. Yeniden eskiye; sonuç boşsa kredi düşmez.

Parametreler
Ad	Yer	Tip	Açıklama
`q`	sorgu	`string`	Başlıkta geçen metin
`il`	sorgu	`string`	İl adı ya da plaka
`ilce`	sorgu	`string`
`kategori`	sorgu	`"ihale" \| "emlak" \| "vasita" \| "personel" \| "endustriyel" \| "elektronik" \| "muhtelif" \| "hayvan"`	`emlak` icra/mahkeme taşınmaz satışları; `icra`, `tasinmaz` da kabul
`baslangic`	sorgu	`string (date)`	En eski yayın günü
`bitis`	sorgu	`string (date)`	En yeni yayın günü
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/ilan/ara?q=arsa&il=Çanakkale&ilce=…&kategori=…&baslangic=2026-09-18&bitis=2026-09-18&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400q en az 3 karakter / il, kategori, tarih, limit ya da sayfa geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`q`	`string \| null`
`il`	`string \| null`
`kategori`	`string \| null`
`sayfa`	`integer`
`sonuclar`	`object[]`
`sonuclar[].ilanNo`	`string`
`sonuclar[].kategori`	`string`
`sonuclar[].ilanTuru`	`string \| null`
`sonuclar[].baslik`	`string`
`sonuclar[].kurum`	`string \| null`
`sonuclar[].il`	`string \| null`
`sonuclar[].ilce`	`string \| null`
`sonuclar[].yayinTarihi`	`string (date)`
`sonuclar[].islemTarihi`	`string \| null`	Birinci satış günü ya da ihale tarihi
`sonuclar[].muhammenBedel`	`number \| null`
`sonuclar[].ozellikler`	`object`
`sonuclar[].url`	`string`
`sonuclar[].kisisel`	`boolean`	Başlıkta kişi adı izi vardı; başlık kategori adına indirgendi
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string \| null`	Son başarılı çekim (ISO 8601); hiç yoksa null
`bayat`	`boolean`
`not`	`string`

gtip

ücretsiz (anahtarla)

GET/v1/gtip/fasillarGTİP bölüm ve fasılları (ücretsiz)
GET/v1/gtip/araGTİP metin ya da kod başıyla ara (ücretsiz)
GET/v1/gtip/{kod}GTİP kodla getir: fasıl, pozisyon, alt pozisyon, tarife satırı (ücretsiz)

GET/v1/gtip/fasillar

ücretsiz (anahtarla)

GTİP bölüm ve fasılları (ücretsiz)

Anahtar gerekli

İstatistik Pozisyonlarına Bölünmüş Türk Gümrük Tarife Cetveli 2026 (Karar 10781): 21 bölüm, 98 fasıl; fasıl başına pozisyon ve 12 haneli tarife satırı sayısı.

Örnek istek

curl "$KILAVUZ/v1/gtip/fasillar" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`bolumler`	`object[]`
`bolumler[].kod`	`string`
`bolumler[].tanim`	`string`
`bolumler[].fasillar`	`object[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`karar`	`string`
`resmiGazete`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

GET/v1/gtip/ara

ücretsiz (anahtarla)

GTİP metin ya da kod başıyla ara (ücretsiz)

Anahtar gerekli

Tarife satırlarında (12 hane) Türkçe sözcük araması: çekim ekleri ve bitişik yazım ("zeytin yağı") tolere edilir, cetvelde geçmeyen yaygın adlar ("cep telefonu", "laptop") cetvel diline çevrilir (yorum). Önce bütün sözcükleri tutan satırlar; sıra pozisyon başlığının ve satırın kendi tanımının puanıyla. pozisyonlar eşleşmelerin toplandığı 4 haneli başlıklardır. Rakamla aranırsa (q=6109) o kod başındaki satırlar döner. Sözcük eşleşmesidir, sınıflandırma kuralı uygulamaz.

Parametreler
Ad	Yer	Tip	Açıklama
`q`zorunlu	sorgu	`string`
`fasil`	sorgu	`string`	Yalnız bu fasıl
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/gtip/ara?q=pamuklu tişört&fasil=61&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400q yok ya da parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`sorgu`	`string`
`yorum`	`string \| null`
`sayfa`	`integer`
`limit`	`integer`
`toplam`	`integer`
`tam`	`boolean`	Bütün sorgu sözcüklerini tutan satır var mı; yoksa kısmi eşleşmeler döner
`satirlar`	`object[]`
`satirlar[].kod`	`string`
`satirlar[].kodNoktali`	`string`
`satirlar[].tanim`	`string`
`satirlar[].tamTanim`	`string`	Pozisyondan satıra tanımlar, " › " ile
`satirlar[].fasil`	`string`
`satirlar[].pozisyon`	`string`
`satirlar[].olcuBirimi`	`string \| null`
`satirlar[].kanuniVergiHaddi`	`number \| null`	474 sayılı Kanun'daki had (%); uygulanan vergi değil
`satirlar[].puan`	`number`
`pozisyonlar`	`object[]`
`pozisyonlar[].kod`	`string`
`pozisyonlar[].kodNoktali`	`string`
`pozisyonlar[].tanim`	`string`
`pozisyonlar[].eslesen`	`integer`
`pozisyonlar[].puan`	`number`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`karar`	`string`
`resmiGazete`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

GET/v1/gtip/{kod}

ücretsiz (anahtarla)

GTİP kodla getir: fasıl, pozisyon, alt pozisyon, tarife satırı (ücretsiz)

Anahtar gerekli

2 hane: fasıl ve pozisyonları (tur: fasil). Cetvelde satırı olan kod (4, 6, 8, 10, 12 hane): tanımı, pozisyondan kendisine yol, altındaki agac ve 12 hanede ölçü birimi ile 474 sayılı Kanun'daki vergi haddi (tur: dugum). Satırı olmayan ara kod: altındaki tarife satırları (tur: onek). Nokta ve boşluk olabilir: 0901.21, 8517.13.00.00.19.

Parametreler
Ad	Yer	Tip	Açıklama
`kod`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/gtip/<kod>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400kod biçimi geçersizHata
401Anahtar yok ya da geçersizHata
404kod 2026 cetvelinde yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`tur`	`"fasil" \| "dugum" \| "onek"`
`kod`	`string`
`kodNoktali`	`string`
`tanim`	`string`
`duzey`	`"pozisyon" \| "alt_pozisyon" \| "kombine_nomanklatur" \| "milli_alt_acilim" \| "gtip"`
`bolum`	`object`
`bolum.kod`	`string`
`bolum.tanim`	`string`
`fasil`	`object`
`fasil.kod`	`string`
`fasil.tanim`	`string`
`yol`	`object[]`
`yol[].kod`	`string \| null`
`yol[].kodNoktali`	`string \| null`
`yol[].duzey`	`string \| null`
`yol[].tanim`	`string`
`olcuBirimi`	`string \| null`
`kanuniVergiHaddi`	`number \| null`
`tarifeSatiriSayisi`	`integer`
`agac`	`object[]`
`pozisyonlar`	`object[]`
`pozisyonlar[].kod`	`string`
`pozisyonlar[].kodNoktali`	`string`
`pozisyonlar[].tanim`	`string`
`pozisyonlar[].tarifeSatiriSayisi`	`integer`
`satirlar`	`object[]`
`satirlar[].kod`	`string`
`satirlar[].kodNoktali`	`string`
`satirlar[].tanim`	`string`
`satirlar[].tamTanim`	`string`	Pozisyondan satıra tanımlar, " › " ile
`satirlar[].fasil`	`string`
`satirlar[].pozisyon`	`string`
`satirlar[].olcuBirimi`	`string \| null`
`satirlar[].kanuniVergiHaddi`	`number \| null`	474 sayılı Kanun'daki had (%); uygulanan vergi değil
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`karar`	`string`
`resmiGazete`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

nace

ücretsiz (anahtarla)

GET/v1/nace/kisimlarNACE kısımları ve bölümleri (ücretsiz)
GET/v1/nace/araNACE faaliyet kodu ara (ücretsiz)
GET/v1/nace/{kod}NACE kodla getir: kısım, bölüm, grup, sınıf, faaliyet (ücretsiz)

GET/v1/nace/kisimlar

ücretsiz (anahtarla)

NACE kısımları ve bölümleri (ücretsiz)

Anahtar gerekli

GİB faaliyet kodu listesi (2026, NACE Rev. 2.1 düzeni): 22 kısım (A–V) ve Türkiye'ye özgü Y; her kısmın bölümleri ve faaliyet sayısı.

Örnek istek

curl "$KILAVUZ/v1/nace/kisimlar" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`kisimlar`	`object[]`
`kisimlar[].kod`	`string`
`kisimlar[].tanim`	`string`
`kisimlar[].bolumler`	`object[]`
`kisimlar[].faaliyetSayisi`	`integer`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

GET/v1/nace/ara

ücretsiz (anahtarla)

NACE faaliyet kodu ara (ücretsiz)

Anahtar gerekli

Altı haneli faaliyet tanımlarında Türkçe sözcük araması (çekim ekleri tolere edilir; "yazılım", "kafe", "emlakçı" gibi listede geçmeyen adlar liste diline çevrilir, yorum). Rakamla aranırsa (q=6210) o kod başındaki faaliyetler. siniflar eşleşmelerin toplandığı 4 haneli NACE sınıflarıdır.

Parametreler
Ad	Yer	Tip	Açıklama
`q`zorunlu	sorgu	`string`
`kisim`	sorgu	`string`	Yalnız bu kısım (A–V, Y)
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/nace/ara?q=yazılım&kisim=K&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400q yok ya da parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`sorgu`	`string`
`yorum`	`string \| null`
`sayfa`	`integer`
`limit`	`integer`
`toplam`	`integer`
`tam`	`boolean`
`faaliyetler`	`object[]`
`faaliyetler[].kod`	`string`
`faaliyetler[].kodNoktali`	`string`
`faaliyetler[].tanim`	`string`
`faaliyetler[].kisim`	`string \| null`
`faaliyetler[].sinif`	`string \| null`
`faaliyetler[].yol`	`object[]`
`faaliyetler[].puan`	`number`
`faaliyetler[].tehlikeSinifi`	`object \| null`	İSG tehlike sınıfı (İşyeri Tehlike Sınıfları Tebliği Ek-1); kod tebliğde yoksa null. Ayrıntı /v1/isg/tehlike-sinifi/{kod}
`siniflar`	`object[]`
`siniflar[].kod`	`string`
`siniflar[].kodNoktali`	`string`
`siniflar[].duzey`	`"kisim" \| "bolum" \| "grup" \| "sinif" \| "faaliyet"`
`siniflar[].tanim`	`string`
`siniflar[].eslesen`	`integer`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

GET/v1/nace/{kod}

ücretsiz (anahtarla)

NACE kodla getir: kısım, bölüm, grup, sınıf, faaliyet (ücretsiz)

Anahtar gerekli

Kısım harfi (J), bölüm (62), grup (62.1), sınıf (62.10) ya da faaliyet (62.10.00); "0111xx" yazımı da olur. Üst düzeyler yolda, bir alt düzey altta.

Parametreler
Ad	Yer	Tip	Açıklama
`kod`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/nace/<kod>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400kod biçimi geçersizHata
401Anahtar yok ya da geçersizHata
404kod GİB listesinde yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`kod`	`string`
`kodNoktali`	`string`
`duzey`	`"kisim" \| "bolum" \| "grup" \| "sinif" \| "faaliyet"`
`tanim`	`string`
`yol`	`object[]`
`yol[].kod`	`string`
`yol[].kodNoktali`	`string`
`yol[].duzey`	`"kisim" \| "bolum" \| "grup" \| "sinif" \| "faaliyet"`
`yol[].tanim`	`string`
`alt`	`object[]`
`alt[].kod`	`string`
`alt[].kodNoktali`	`string`
`alt[].duzey`	`"kisim" \| "bolum" \| "grup" \| "sinif" \| "faaliyet"`
`alt[].tanim`	`string`
`faaliyetSayisi`	`integer`
`tehlikeSinifi`	`object \| null`	Yalnız altı haneli faaliyette. İSG tehlike sınıfı (İşyeri Tehlike Sınıfları Tebliği Ek-1); kod tebliğde yoksa null. Ayrıntı /v1/isg/tehlike-sinifi/{kod}
`tehlikeSinifi.sinif`	`"az_tehlikeli" \| "tehlikeli" \| "cok_tehlikeli"`
`tehlikeSinifi.ad`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

isg

ücretsiz (anahtarla)

GET/v1/isg/tehlike-sinifiİSG tehlike sınıfı listesi ve arama (ücretsiz)
GET/v1/isg/tehlike-sinifi/{naceKodu}NACE koduna göre İSG tehlike sınıfı ve yükümlülükler (ücretsiz)

GET/v1/isg/tehlike-sinifi

ücretsiz (anahtarla)

İSG tehlike sınıfı listesi ve arama (ücretsiz)

Anahtar gerekli

İş Sağlığı ve Güvenliğine İlişkin İşyeri Tehlike Sınıfları Tebliği (RG 26.12.2012/28509) Ek-1, değişiklikleri işlenmiş (son: RG 1.4.2026/33211; Ek-1 13.3.2025'ten beri NACE Rev.2.1 kodlarıyla). ara faaliyet adı (Türkçe sözcük araması, "yazılım", "kafe" gibi gündelik adlar çevrilir) ya da kod başı ("62", "43.12"); boşsa bütün liste. sinif verilirse o sınıfa bağlı yükümlülükler de döner. dagilim süzgeçten sonraki bütün eşleşmelerin sınıf sayıları, kapsam GİB NACE listesiyle eşleşme.

Parametreler
Ad	Yer	Tip	Açıklama
`ara`	sorgu	`string`
`sinif`	sorgu	`"az_tehlikeli" \| "tehlikeli" \| "cok_tehlikeli"`	`az`, `cok` kısaltmaları da olur
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/isg/tehlike-sinifi?ara=kuaför&sinif=…&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`sorgu`	`string \| null`
`yorum`	`string \| null`
`sinif`	`"az_tehlikeli" \| "tehlikeli" \| "cok_tehlikeli"`
`sayfa`	`integer`
`limit`	`integer`
`toplam`	`integer`
`tam`	`boolean`
`dagilim`	`object`
`dagilim.az_tehlikeli`	`integer`
`dagilim.tehlikeli`	`integer`
`dagilim.cok_tehlikeli`	`integer`
`faaliyetler`	`object[]`
`faaliyetler[].kod`	`string`
`faaliyetler[].kodNoktali`	`string`
`faaliyetler[].tanim`	`string`
`faaliyetler[].tehlikeSinifi`	`"az_tehlikeli" \| "tehlikeli" \| "cok_tehlikeli"`
`faaliyetler[].tehlikeSinifiAdi`	`string`
`faaliyetler[].dipnot`	`string`	Sınıfın yanındaki "*" dipnotu (asbest yasağı)
`faaliyetler[].degisiklik`	`object`	13.3.2025'teki yeni Ek-1'den sonra satırı değiştiren tebliğ
`faaliyetler[].eslesme`	`"tam" \| "yalniz_kod" \| "yok"`	GİB NACE listesiyle (/v1/nace): tam = kod ve tanım aynı, yalniz_kod = kod aynı, tanım yazımı farklı, yok = kod GİB listesinde yok
`yukumlulukler`	`object[]`	Yalnız `sinif` verilince
`yukumlulukler[].kod`	`string`
`yukumlulukler[].baslik`	`string`
`yukumlulukler[].deger`	`number \| string`
`yukumlulukler[].birim`	`string`
`yukumlulukler[].aciklama`	`string`
`yukumlulukler[].mevzuat`	`object`
`yukumlulukler[].ayrinti`	`object`
`kapsam`	`object`
`kapsam.tebligFaaliyet`	`integer`
`kapsam.gibFaaliyet`	`integer`
`kapsam.ortakKod`	`integer`
`kapsam.ayniTanim`	`integer`
`kapsam.yalnizTeblig`	`string[]`
`kapsam.yalnizGib`	`string[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`	Hukuki tavsiye değildir; kesin sınıf SGK tescilindeki asıl işe bağlıdır (Tebliğ m.2)
`teblig`	`object`
`teblig.ad`	`string`
`teblig.resmiGazete`	`object`
`teblig.ek`	`string`
`teblig.naceSurumu`	`string`
`teblig.sonDegisiklik`	`object`
`teblig.degisiklikSayisi`	`integer`

GET/v1/isg/tehlike-sinifi/{naceKodu}

ücretsiz (anahtarla)

NACE koduna göre İSG tehlike sınıfı ve yükümlülükler (ücretsiz)

Anahtar gerekli

Altı haneli NACE faaliyet kodu (62.10.00, 621000) → az tehlikeli / tehlikeli / çok tehlikeli ve sınıfa bağlı yükümlülükler: iş güvenliği uzmanı belge sınıfı ve çalışma süresi, işyeri hekimi çalışma süresi, periyodik muayene, risk değerlendirmesi ve acil durum planı yenileme, acil durum destek elemanı; her biri yönetmelik maddesi ve RG künyesiyle. Kod ekten kaldırılmışsa 404 + mulga; GİB listesinde olup tebliğde olmayan kod 404 + gibTanim.

Parametreler
Ad	Yer	Tip	Açıklama
`naceKodu`zorunlu	yol	`string`

Örnek istek

curl "$KILAVUZ/v1/isg/tehlike-sinifi/<naceKodu>" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400altı haneli kod değilHata
401Anahtar yok ya da geçersizHata
404kod tebliğ ekinde yok (mülga, yalnız GİB listesinde ya da hiç yok)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`kod`	`string`
`kodNoktali`	`string`
`tanim`	`string`
`tehlikeSinifi`	`"az_tehlikeli" \| "tehlikeli" \| "cok_tehlikeli"`
`tehlikeSinifiAdi`	`string`
`dipnot`	`string`	Sınıfın yanındaki "*" dipnotu (asbest yasağı)
`degisiklik`	`object`	13.3.2025'teki yeni Ek-1'den sonra satırı değiştiren tebliğ
`degisiklik.tur`	`"degisik_satir" \| "degisik_ibare" \| "ek_satir"`
`degisiklik.aciklama`	`string`
`degisiklik.resmiGazete`	`object`
`eslesme`	`"tam" \| "yalniz_kod" \| "yok"`	GİB NACE listesiyle (/v1/nace): tam = kod ve tanım aynı, yalniz_kod = kod aynı, tanım yazımı farklı, yok = kod GİB listesinde yok
`yukumlulukler`	`object[]`
`yukumlulukler[].kod`	`string`
`yukumlulukler[].baslik`	`string`
`yukumlulukler[].deger`	`number \| string`
`yukumlulukler[].birim`	`string`
`yukumlulukler[].aciklama`	`string`
`yukumlulukler[].mevzuat`	`object`
`yukumlulukler[].ayrinti`	`object`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`	Hukuki tavsiye değildir; kesin sınıf SGK tescilindeki asıl işe bağlıdır (Tebliğ m.2)
`teblig`	`object`
`teblig.ad`	`string`
`teblig.resmiGazete`	`object`
`teblig.ek`	`string`
`teblig.naceSurumu`	`string`
`teblig.sonDegisiklik`	`object`
`teblig.degisiklikSayisi`	`integer`

arac

0–1 kredi

GET/v1/arac/kasko-degerTSB kasko değer listesi: marka/model/yıl
GET/v1/arac/kasko-deger/markalarKasko listesindeki markalar (ücretsiz)
GET/v1/arac/trafik-azami-primZorunlu trafik sigortası azami primi
GET/v1/arac/otvBinek otomobil ÖTV hesabı (ücretsiz)

GET/v1/arac/kasko-deger

1 kredi

TSB kasko değer listesi: marka/model/yıl

Anahtar gerekli

Türkiye Sigorta Birliği'nin aylık kasko değer listesi (~28.000 tip, son 15 model yılı), koda gömülü. marka, ara ya da markaKodu zorunlu; tip ve ara sözcük sözcük eşleşir (ör. marka=alfa romeo&tip=giulietta 1.4). yil verilirse yalnız o model yılı için değeri olan tipler, degerler o yıla daralır. Değer TL; ilan/piyasa fiyatı değil, kasko priminde ve hasarda esas alınan referans. Sonuç yoksa 0 kredi. Vergi için /v1/arac/otv ve /v1/vergi/mtv.

Parametreler
Ad	Yer	Tip	Açıklama
`marka`	sorgu	`string`	Marka adı (tam eşleşme önce, yoksa içeren)
`tip`	sorgu	`string`	Tip adındaki sözcükler
`ara`	sorgu	`string`	Marka + tip adında serbest arama
`markaKodu`	sorgu	`string`	TSB marka kodu
`tipKodu`	sorgu	`string`	TSB tip kodu (markaKodu ile)
`yil`	sorgu	`integer`	Model yılı
`limit`	sorgu	`integer`
`sayfa`	sorgu	`integer`

Örnek istek

curl "$KILAVUZ/v1/arac/kasko-deger?marka=alfa romeo&tip=giulietta 1.4&ara=…&markaKodu=…&tipKodu=…&yil=2016&limit=…&sayfa=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400marka/ara/markaKodu yok ya da parametre geçersizHata
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`sayfa`	`integer`
`limit`	`integer`
`araclar`	`object[]`
`araclar[].markaKodu`	`string`
`araclar[].marka`	`string`
`araclar[].tipKodu`	`string`
`araclar[].tip`	`string`
`araclar[].degerler`	`object[]`
`ay`	`string`	Liste ayı, YYYY-AA
`listeAdi`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`sayfaUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`bayat`	`boolean`	Gömülü liste bu aydan eski
`uyari`	`string`

GET/v1/arac/kasko-deger/markalar

ücretsiz (anahtarla)

Kasko listesindeki markalar (ücretsiz)

Anahtar gerekli

Örnek istek

curl "$KILAVUZ/v1/arac/kasko-deger/markalar" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
401Anahtar yok ya da geçersizHata
429Kredi limiti aşıldıHata

Yanıt alanları
`toplam`	`integer`
`markalar`	`object[]`
`markalar[].kod`	`string`
`markalar[].ad`	`string`
`markalar[].tipSayisi`	`integer`
`ay`	`string`
`yillar`	`integer[]`
`kaynak`	`string`
`kaynakUrl`	`string`
`sayfa`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`

GET/v1/arac/trafik-azami-prim

1 kredi

Zorunlu trafik sigortası azami primi

Anahtar gerekli

SBM'nin yayımladığı azami (tavan) brüt prim tablosu, son üç ay: il × araç grubu × basamak (0 en pahalı … 8 en ucuz, ilk poliçe 4) × özel/tüzel × yakıt (elektrik/diğer) × engelli indirimi. il ya da (grup + basamak) zorunlu; bütün filtreler verilip tek satır kalırsa azamiPrim üst düzeyde döner. Sigortacı bu tutarı aşamaz, altında fiyat verebilir. Sonuç yoksa 0 kredi.

Parametreler
Ad	Yer	Tip	Açıklama
`il`	sorgu	`string`	Plaka kodu ya da il adı
`grup`	sorgu	`string`	Araç grubu kodu (01–15) ya da adı; liste yanıtın hata gövdesinde
`basamak`	sorgu	`integer`
`ozelTuzel`	sorgu	`"ozel" \| "tuzel"`
`yakit`	sorgu	`"diger" \| "elektrik"`
`engelli`	sorgu	`boolean`	Engelli indirimli tavan (yalnız basamak 2–8, bazı gruplarda yok)
`ay`	sorgu	`string`	YYYY-AA; tablodaki son üç aydan biri, verilmezse en yenisi

Örnek istek

curl "$KILAVUZ/v1/arac/trafik-azami-prim?il=34&grup=otomobil&basamak=4&ozelTuzel=…&yakit=…&engelli=…&ay=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400il ya da grup+basamak yok, il/grup bulunamadı ya da parametre geçersizHata
401Anahtar yok ya da geçersizHata
422ay tabloda yok (aylar)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`ay`	`string`
`aylar`	`string[]`
`azamiPrim`	`number`	Tek satır kaldığında, TL
`toplam`	`integer`
`satirlar`	`object[]`
`satirlar[].il`	`string \| null`
`satirlar[].plaka`	`integer`
`satirlar[].grupKodu`	`string`
`satirlar[].grup`	`string`
`satirlar[].basamak`	`integer`
`satirlar[].ozelTuzel`	`"ozel" \| "tuzel"`
`satirlar[].yakit`	`"diger" \| "elektrik"`
`satirlar[].engelliIndirimi`	`boolean`
`satirlar[].azamiPrim`	`number`
`birim`	`string`
`kaynak`	`string`
`kaynakUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`bayat`	`boolean`
`uyari`	`string`

GET/v1/arac/otv

ücretsiz (anahtarla)

Binek otomobil ÖTV hesabı (ücretsiz)

Anahtar gerekli

ÖTV (II) sayılı liste 87.03 binek otomobil oranları, Cumhurbaşkanı Kararı 10115 (RG 24.07.2025) ve 31.07.2026'dan itibaren 100.000 TL asgari maktu vergi; ÖTV + %20 KDV. matrah (vergisiz fiyat) verilirse ileri, fiyat (vergiler dahil) verilirse matrah geriye çözülür. Dilimler kademeli değildir: bütün matrah dilimin oranıyla vergilenir. Engelli/taksi istisnaları ve ticari araçlar kapsam dışı. Yıllık vergi için /v1/vergi/mtv.

Parametreler
Ad	Yer	Tip	Açıklama
`motor`	sorgu	`"icten" \| "hibrit" \| "sarjli_hibrit" \| "elektrik"`
`motorHacmi`	sorgu	`number`	cm³ (elektrik dışında zorunlu)
`elektrikGucu`	sorgu	`number`	kW: elektrikte motor gücü, hibritte elektrik motoru gücü
`co2`	sorgu	`number`	Şarjlı hibrit: CO₂ g/km
`menzil`	sorgu	`number`	Şarjlı hibrit: elektrikli menzil km
`matrah`	sorgu	`number`	ÖTV matrahı TL (fiyat ile birlikte verilmez)
`fiyat`	sorgu	`number`	ÖTV ve KDV dahil satış fiyatı TL
`tarih`	sorgu	`string (date)`	Verilmezse bugün (2025-07-24 … 2026-12-31)

Örnek istek

curl "$KILAVUZ/v1/arac/otv?motor=…&motorHacmi=1499&elektrikGucu=…&co2=…&menzil=…&matrah=800000&fiyat=…&tarih=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400motor/motorHacmi/matrah/fiyat eksik ya da geçersizHata
401Anahtar yok ya da geçersizHata
422tarih kapsam dışı ya da fiyata karşılık matrah yokHata
429Kredi limiti aşıldıHata

Yanıt alanları
`satir`	`string`
`tanim`	`string`
`dilim`	`string`
`matrah`	`number`
`otvOrani`	`number`	%
`nispiOtv`	`number`
`otv`	`number`
`asgariMaktuUygulandi`	`boolean`
`kdvMatrahi`	`number`
`kdv`	`number`
`vergiliFiyat`	`number`
`vergiPayi`	`number`	%
`digerCozumler`	`object[]`	Fiyattan çözümde aynı fiyatı veren başka matrahlar
`belirsiz`	`boolean`
`belirsizlik`	`string`
`asgariMaktu`	`object`
`asgariMaktu.tutar`	`number`
`asgariMaktu.baslangic`	`string`
`asgariMaktu.not`	`string`
`tarih`	`string`
`ilgili`	`object`
`kaynak`	`object`
`kaynak.belge`	`string`
`kaynak.rg`	`string`
`kaynak.url`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

sigorta

ücretsiz (anahtarla)

GET/v1/sigorta/dask

ücretsiz (anahtarla)

DASK (zorunlu deprem sigortası) primi (ücretsiz)

Anahtar gerekli

Sigorta bedeli = brüt m² × yapı tarzının o ayki birim maliyeti (azami teminatla sınırlı); prim = bedel × risk grubunun binde oranı. **Risk grubu il/ilçeden çıkmaz** (DASK adres koduna, deprem tehlike haritasına ve zemine göre belirler, eşleme yayımlanmıyor): riskGrubu verin, verilmezse yedi grubun primi döner. Birim maliyetler aylık (poliçe başlangıç ayı). Trafik sigortası için /v1/arac/trafik-azami-prim.

Parametreler
Ad	Yer	Tip	Açıklama
`m2`zorunlu	sorgu	`number`	Brüt yüzölçümü
`yapiTarzi`	sorgu	`"betonarme" \| "diger"`
`riskGrubu`	sorgu	`string`	1–7 ya da I–VII
`tarih`	sorgu	`string (date)`	Poliçe başlangıcı; verilmezse bugün

Örnek istek

curl "$KILAVUZ/v1/sigorta/dask?m2=100&yapiTarzi=…&riskGrubu=3&tarih=2026-09-18" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR"

Yanıtlar

200Başarılı
400m2, yapiTarzi, riskGrubu ya da tarih geçersizHata
401Anahtar yok ya da geçersizHata
422poliçe ayının birim maliyeti gömülü değil (aylar)Hata
429Kredi limiti aşıldıHata

Yanıt alanları
`m2`	`number`
`yapiTarzi`	`string`
`yapiTanimi`	`string`
`tarih`	`string`
`ay`	`string`
`birimMaliyet`	`number`
`hesaplananBedel`	`number`
`azamiTeminat`	`number`
`sigortaBedeli`	`number`
`azamiTeminataTakildi`	`boolean`
`primler`	`object[]`
`primler[].riskGrubu`	`integer`
`primler[].grup`	`string`
`primler[].oranBinde`	`number`
`primler[].prim`	`number`
`prim`	`number`	riskGrubu verildiyse
`oranlarBinde`	`number[]`
`riskGrubuNotu`	`string`
`ilgili`	`object`
`kaynak`	`string`
`kaynakUrl`	`string`
`tarifeUrl`	`string`
`lisans`	`string`
`guncelleme`	`string (date)`
`uyari`	`string`

fatura

1 kredi

POST/v1/fatura/dogrula

1 kredi

e-Fatura / e-Arşiv UBL-TR belge doğrulama: XSD + GİB şematronu

Anahtar gerekli

Gövde ham XML (Content-Type: application/xml) ya da JSON {"xml": "...", "tur": "efatura|earsiv"}, en çok 3 MB. Sırayla: iyi biçimli XML; UBL 2.1 XSD (GİB UBL-TR 1.2.1 paketi; Invoice, CreditNote, DespatchAdvice, ReceiptAdvice, ApplicationResponse); GİB e-Fatura paketindeki UBL-TR şematronunun bütün kuralları (zarf dahil). tur verilmezse ProfileID EARSIVFATURA ise e-Arşiv (GİB type=earchive parametresi) sayılır. İmza (XAdES), mükellef/etiket sorgusu ve tekillik denetlenmez; kapsam yanıtta kapsam alanında. Belge saklanmaz, günlüğe yazılmaz. Biçim, şema ya da şematron hatası olan belge de 200 döner (gecerli: false) ve 1 kredi düşer.

Parametreler
Ad	Yer	Tip	Açıklama
`tur`	sorgu	`"efatura" \| "earsiv"`

İstek gövdesi
Alan	Tip	Açıklama
`xml`zorunlu	`string`
`tur`	`"efatura" \| "earsiv"`

Örnek istek

curl -X POST "$KILAVUZ/v1/fatura/dogrula?tur=…" \
  -H "authorization: Bearer $KILAVUZ_ANAHTAR" \
  -H "content-type: application/json" \
  -d '{}'

Yanıtlar

200Başarılı
400XML gövdesi yok ya da tur geçersizHata
401Anahtar yok ya da geçersizHata
413belge 3 MB'tan büyükHata
422DOCTYPE içeren belgeHata
429Kredi limiti aşıldıHata

Yanıt alanları
`gecerli`	`boolean`
`bicim`	`object`
`bicim.gecerli`	`boolean`
`bicim.hata`	`string`
`belge`	`object`
`belge.kok`	`string`
`belge.zarf`	`boolean`
`belge.profil`	`string \| null`
`belge.faturaTipi`	`string \| null`
`belge.sematronTuru`	`"efatura" \| "earchive"`
`sema`	`object`
`sema.durum`	`"gecerli" \| "gecersiz" \| "uygulanmadi" \| "calismadi"`
`sema.hatalar`	`object[]`
`sema.toplamHata`	`integer`
`sema.neden`	`string`
`sematron`	`object`
`sematron.durum`	`"gecerli" \| "gecersiz" \| "yarida"`
`sematron.hatalar`	`object[]`
`sematron.toplamHata`	`integer`
`sematron.denetlenen`	`integer`
`sematron.yarida`	`boolean`
`sematron.degerlendirilemeyen`	`object[]`
`kapsam`	`string`
`paket`	`object`
`kaynak`	`string`
`guncelleme`	`string \| null`
`not`	`string`

Şemalar

`Hata`

`hata`her zaman	`string`

`Tatil`

`tarih`her zaman	`string (date)`
`ad`her zaman	`string`
`tur`her zaman	`"resmi" \| "dini"`
`yarimGun`her zaman	`boolean`	Arifeler ve 28 Ekim: 13.00'te başlar
`baslangicSaati`	`object`

`PiyasaFiyati`

`kod`her zaman	`string`	doviz.com kodu: gram-altin, ceyrek-altin, ons, USD…
`ad`her zaman	`string`
`alis`her zaman	`number`
`satis`her zaman	`number`
`degisimYuzde`	`number \| null`
`saat`	`string \| null`	Kaynağın son fiyat saati, Türkiye saati SS:DD (tarih yok)
`birim`her zaman	`"TRY" \| "USD"`

`HavaSaati`

`zaman`	`string`	Adımın başlangıcı, UTC
`sicaklikC`	`number \| null`
`nemYuzde`	`number \| null`
`ruzgarHizMs`	`number \| null`
`ruzgarYonDerece`	`number \| null`
`basincHpa`	`number \| null`
`bulutYuzde`	`number \| null`
`yagisMm`	`number \| null`
`yagisSaat`	`1 \| 6 \| null`	yagisMm kaç saatlik
`durum`	`string \| null`	Türkçe gökyüzü durumu
`durumKod`	`string \| null`	MET sembol kodu

`MesafeUcu`

`girdi`	`string`
`tur`	`"il" \| "koordinat"`
`il`	`string \| null`
`plaka`	`integer \| null`
`lat`	`number`
`lon`	`number`

`IlKarti`

`plaka`her zaman	`integer`	1–81
`ad`her zaman	`string`
`bolge`her zaman	`"Marmara" \| "Ege" \| "Akdeniz" \| "İç Anadolu" \| "Karadeniz" \| "Doğu Anadolu" \| "Güneydoğu Anadolu"`	Coğrafi bölge (idari birim değil)
`ibbs`her zaman	`object`	İstatistiki Bölge Birimleri Sınıflaması (NUTS) kodları
`ibbs.duzey1`	`string`
`ibbs.duzey2`	`string`
`ibbs.duzey3`	`string`
`alanKodlari`her zaman	`object[]`
`alanKodlari[].kod`	`string`
`alanKodlari[].bolum`	`string`	Yalnız İstanbul: "Avrupa Yakası"/"Anadolu Yakası"
`buyuksehir`her zaman	`boolean`	6360 sayılı Kanun
`komsular`her zaman	`string[]`	Kara sınırı paylaşan iller
`ilceSayisi`her zaman	`integer`
`postaKoduAraligi`	`object`	İle ayrılan blok; hepsi kullanımda değil
`postaKoduAraligi.bas`	`string`
`postaKoduAraligi.son`	`string`
`nufus`her zaman	`object`
`nufus.yil`	`integer`
`nufus.toplam`	`integer`
`nufus.ilIlceMerkezi`	`integer`
`nufus.beldeKoy`	`integer`	Büyükşehirde 0
`nufus.yillikArtisHizi`	`number \| null`	Binde
`nufus.yogunluk`	`number`	Kişi/km²
`yuzolcumu`	`number`	km², göl ve baraj yüzeyleri hariç (TÜİK yoğunluğundan türetildi)
`rakim`	`integer \| null`	İl merkezi rakımı, metre (Copernicus DEM GLO-90, yaklaşık; MGM istasyon rakımı değil)
`merkez`	`object \| null`	Şehir merkezi POI'lerinin medyanı (Overture), yaklaşık
`merkez.lat`	`number`
`merkez.lon`	`number`

`IlceNufusu`

`ad`her zaman	`string`
`nufus`her zaman	`integer`
`yillikArtisHizi`	`number \| null`	Binde
`merkez`	`object \| null`
`merkez.lat`	`number`
`merkez.lon`	`number`

`NufusYili`

`yil`her zaman	`integer`
`nufus`her zaman	`integer`

`IbbsBirimi`

`kod`her zaman	`string`
`ad`her zaman	`string`
`ust`	`string`	Bir üst düzeyin kodu; Düzey 1'de yok
`plaka`	`integer`	Yalnız Düzey 3

`VergiDairesi`

`kod`	`string \| null`	5 haneli muhasebe birim kodu; şubede null
`ad`	`string`
`tur`	`"mudurluk" \| "sube" \| "defterdarlik"`
`ilKodu`	`string`	Plaka kodu, "01"
`il`	`string`
`ilce`	`string`	İl merkezindekiler "Merkez"

`TrafikCezasi`

`madde`	`string`	KTK madde/fıkra/bent
`baslik`	`string`
`tutar`	`number \| null`	TL; aralıklı cezada null
`alt`	`number`
`ust`	`number`
`ehliyetGun`	`integer`	Sürücü belgesi geri alma, gün
`belgeIptal`	`boolean`
`aracMenGun`	`integer`
`cezaPuani`	`5 \| 10 \| 15 \| 20`	EGM 2026 rehberi (KTY Ek-35)
`yururluk`	`string (date)`
`dayanak`	`string`
`kaynak`	`"resmi" \| "rehber" \| "hesap" \| "ikincil"`	resmi: 7574 RG metni; rehber: EGM 2026 ceza rehberi
`not`	`string`
`belirsiz`	`boolean`
`etiketler`	`string[]`

`HarcKalemi`

`ad`	`string`
`tutar`	`number \| null`	Maktu tutar, TL; oransal kalemde null
`binde`	`number`
`altSinir`	`number`
`ustSinir`	`number`
`cins`	`"harc" \| "degerli-kagit" \| "ucret" \| "pay"`
`sure`	`"6ay" \| "1yil" \| "2yil" \| "3yil" \| "10yil" \| "suresiz"`
`dayanak`	`string`	Tarifedeki yeri
`not`	`string`
`belirsiz`	`boolean`

`Gecerlilik`

`baslangic`her zaman	`string (date)`
`bitis`her zaman	`string \| null (date)`	null: yenisi çıkana kadar

`ResmiKaynak`

`belge`her zaman	`string`
`rg`her zaman	`string \| null`	Resmî Gazete tarihi / sayısı
`url`her zaman	`string`

`OranDonemi`

`baslangic`her zaman	`string (date)`
`bitis`her zaman	`string \| null (date)`	null: güncel dönem
`oran`her zaman	`number`	Yüzde (gecikme zammında aylık, tecil faizinde yıllık)
`dayanak`her zaman	`string`

`OranParcasi`

`baslangic`	`string (date)`
`bitis`	`string (date)`
`oran`	`number`
`dayanak`	`string`
`ay`	`integer`	Yalnız gecikme zammında: tam ay
`gun`	`integer`
`tutar`	`number`

`Dilim`

`ust`	`number \| null`	Dilim üst sınırı (TL); son dilimde null
`oran`	`number`	Yüzde

`Ayrisma`

`mahalle`	`string`
`koy`	`string`
`yolAdi`	`string`
`yolTipi`	`string`
`binaNo`	`string`
`daire`	`string`
`kat`	`string`
`blok`	`string`
`bina`	`string`
`site`	`string`
`postaKodu`	`string`
`serbest`	`string[]`	Çapaya bağlanamayan kelimeler
`duzeltmeler`	`string[]`

`AdresSonucu`

`il`	`string`
`ilce`	`string`
`mahalle`	`string`
`yol`	`string`
`binaNo`	`string`
`daire`	`string`
`kat`	`string`
`lat`	`number`
`lon`	`number`
`hassasiyet`her zaman	`"sokak" \| "mahalle" \| "ilce" \| "il" \| "yok"`	Koordinatın ayrıntı düzeyi (bileşenin bulunup bulunmadığı değil). `mahalle` şimdilik üretilmiyor
`dogrulanan`her zaman	`object`	Hangi bileşenin resmî sicilde bulunduğu; koordinattan bağımsız
`dogrulanan.il`	`boolean`
`dogrulanan.ilce`	`boolean`
`dogrulanan.mahalle`	`boolean`
`dogrulanan.yol`	`boolean`
`guven`her zaman	`number`	0–1
`duzeltmeler`her zaman	`string[]`	Yapılan düzeltmelerin okunur dökümü
`ayrisma`her zaman	`Ayrisma`

`IbanSonucu`

`gecerli`her zaman	`boolean`
`iban`	`string`
`bicimli`	`string`
`ulke`	`string`
`bankaKodu`	`string`
`hesapNo`	`string`
`banka`	`object`
`hata`	`"bos" \| "gecersiz_karakter" \| "bilinmeyen_ulke" \| "uzunluk" \| "kontrol_basamagi" \| "tr_ayrilmis_hane"`
`aciklama`	`string`

`Kur`

`kod`	`string`
`ad`	`string`
`adEn`	`string`
`birim`	`integer`	TCMB kote birimi (JPY 100); kurlar 1 birime indirgenmiş
`alis`	`number \| null`
`satis`	`number \| null`
`efektifAlis`	`number \| null`
`efektifSatis`	`number \| null`

`KimlikSonucu`

`gecerli`her zaman	`boolean`
`tur`	`"vkn" \| "tckn"`	Yalnız VKN ucunda
`vkn`	`string`	Yalnız geçerli 10 haneli VKN
`hata`	`"bos" \| "gecersiz_karakter" \| "uzunluk" \| "ilk_hane_sifir" \| "kontrol_10" \| "kontrol_11" \| "kontrol_basamagi"`
`aciklama`	`string`
`not`her zaman	`string`

`TelefonSonucu`

`gecerli`her zaman	`boolean`
`e164`	`string \| null`	+905321234567; 444 numaralarında null
`ulusal`	`string`	0532 123 45 67
`tur`	`"gsm" \| "m2m" \| "sabit" \| "ucretsiz_800" \| "katma_degerli_900" \| "ulusal_850" \| "kurumsal_444"`
`il`	`string`	Yalnız sabit hatlarda
`hata`	`"bos" \| "gecersiz_karakter" \| "yabanci_ulke" \| "uzunluk" \| "tanimsiz_onek"`
`aciklama`	`string`

`TeslimTahmini`

`gonderimTarihi`her zaman	`string (date)`
`kabulTarihi`her zaman	`string (date)`	Gönderinin işleme alındığı ilk iş günü
`gonderen`her zaman	`object`
`gonderen.il`	`string`
`gonderen.bolge`	`string`
`alici`her zaman	`object`
`alici.il`	`string`
`alici.bolge`	`string`
`tasiyici`	`string`
`isGunu`her zaman	`integer`
`tahminiTeslim`her zaman	`string (date)`
`enGec`her zaman	`string (date)`	Tahminin bir iş günü sonrası
`not`her zaman	`string`	Tahmin, taahhüt değil

`SentetikKayit`

`ad`	`string`
`soyad`	`string`
`unvan`	`string`	Yalnız vkn istendiğinde: ticaret unvanı
`tckn`	`string`	Kontrol haneleri tutar, kayıtlı kişi değildir
`vkn`	`string`
`iban`	`string`	TR, mod-97 geçerli; banka kodu TCMB listesinden
`gsm`	`string`	BTK planındaki gerçek 5xx öneki + rastgele abone
`eposta`	`string`	Her zaman example.com (RFC 2606)
`adres`	`object`	İl/ilçe/mahalle/sokak sicilden gerçek; kapı ve daire rastgele
`adres.il`	`string`
`adres.ilce`	`string`
`adres.mahalle`	`string`
`adres.yol`	`string`
`adres.binaNo`	`string`
`adres.daire`	`string`
`adres.tekSatir`	`string`
`dogumTarihi`	`string (date)`
`plaka`	`string`

`EtiketTarafGirdisi`

`adres`her zaman	`string`	en fazla 1000 karakter
`ad`	`string`	Kişi ya da firma adı; yalnız etikete geçirilir. en fazla 100 karakter

`EtiketTaraf`

`ad`	`string`	Girdiden aynen geçirilir; çözümlenmez, saklanmaz
`il`	`string \| null`
`ilce`	`string \| null`
`mahalle`	`string \| null`
`yol`	`string \| null`
`binaNo`	`string \| null`
`daire`	`string \| null`
`kat`	`string \| null`
`site`	`string \| null`
`blok`	`string \| null`
`satirlar`her zaman	`string[]`	Etikete basılacak satırlar; her biri en çok 35 karakter
`dogrulanan`her zaman	`object`
`dogrulanan.il`	`boolean`
`dogrulanan.ilce`	`boolean`
`dogrulanan.mahalle`	`boolean`
`dogrulanan.yol`	`boolean`
`guven`her zaman	`number`	0–1
`eksikler`her zaman	`string[]`	Etiket için kritik olup çözülemeyenler (il, ilce, yol, binaNo)

`KargoKonum`

`il`	`string \| null`
`ilce`	`string \| null`
`ulke`	`string \| null`

`KargoSonucu`

`tasiyici`her zaman	`string`
`takipNo`her zaman	`string`
`bulundu`her zaman	`boolean`
`mesaj`	`string`	Yalnız bulundu=false
`durum`	`"hazirlaniyor" \| "yolda" \| "dagitimda" \| "teslim_edildi" \| "iade" \| "bilinmiyor"`
`durumMetni`	`string \| null`
`teslimEdildi`	`boolean`
`gonderiTarihi`	`string \| null`
`tahminiTeslim`	`string \| null`
`cikis`	`KargoKonum`
`varis`	`KargoKonum`
`teslimBirimi`	`object \| null`
`teslimBirimi.ad`	`string \| null`
`teslimBirimi.telefon`	`string \| null`
`hareketler`	`object[]`
`hareketler[].tarih`	`string \| null`
`hareketler[].yer`	`string \| null`
`hareketler[].aciklama`	`string \| null`

Şema derleme anında https://api.kilavuzapi.com/openapi.json ucundan alındı.

İlk istek

Anahtarını al

İki değişken tanımla

Bir adres çözümle

Kimlik ve kredi

Claude'a bağlan

Bağlayıcı ekle

Adresi yapıştır

Gir ve izin ver

Hatalar

Toplu CSV

Kredi ve sınırlar

Örnek

Seçenekler

Hatalar

Adres

Adres

Doğrulama

IBAN

Alan kodu

Barkod

TCKN, VKN, telefon

Kamu verisi

Nöbetçi eczane

Akaryakıt

Hal fiyatı

İstanbul (İBB açık veri)

Baraj doluluk

Hava durumu

Deprem

Eğitim

Otoyol ve köprü geçişi

Enerji tarifeleri

Resmî Gazete

İlaç listesi

İl kartı ve bölgeler

Nüfus

Vergi ve finans

TCMB kuru

Altın ve serbest piyasa

Vergi dairesi

TÜFE ve kira

Vergi ve SGK

Bordro ve tazminat

Harçlar

Trafik cezası

Avukatlık ve noter ücretleri

Kargo ve e-ticaret

Kargo