Doküman

İlk istek

1. Anahtarını al

   Kayıt yakında açılıyor. Anahtar bir kez gösterilecek; biz yalnız özetini saklarız. Anahtarın varsa sonraki adıma geç.

2. İki değişken tanımla

   export ADRESKIT="https://xacw6yute6famacx6a7tjafkfq0hqmug.lambda-url.eu-central-1.on.aws"
   export ADRESKIT_ANAHTAR="ak_live_…"

3. Bir adres çözümle

   curl -X POST "$ADRESKIT/v1/address/resolve" \
     -H "authorization: Bearer $ADRESKIT_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. Kalan krediyi GET /v1/kullanim ya da panel söyler.

Aynı araçlar uzak MCP olarak da açık: POST /mcp. İstemci kurulumu ana sayfada.

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 "$ADRESKIT/v1/address/temizle" \
  -H "authorization: Bearer $ADRESKIT_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.

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.