İçeriğe geç
Veri API'si

Doküman

İlk isteğinizden ürününüze: uçlar, fiyatlar, hatalar ve OpenAPI dosyası.

Başlarken

Binderim Veri API'si, HTTPS üzerinden çalışan, yalnızca okuma yapan bir JSON API'sidir. Bütün uçlar tek bir taban adresin altındadır:

https://dev.binderim.com/v1
  1. Binderim hesabınızla giriş yapın (sağ üstte).
  2. API şartlarını kabul edin ve panelinizde bir API anahtarı oluşturun. Anahtar bir kez gösterilir; o anda kopyalayın.
  3. Anahtarı her istekle gönderin ve yanıtın data kısmını okuyun.

curl

curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/games"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/games", {
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY },
});
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/games",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
)
body = res.json()

API hiçbir veriyi değiştirmez: her uç yalnızca okur. Anahtarınızı sunucunuzda tutun; tarayıcıda herkes görebilir.

Kimlik doğrulama

Anahtarınızı X-Api-Key başlığında ya da Authorization: Bearer <anahtar> olarak gönderin. Adres loglara düştüğü için anahtar adresin içinde asla kabul edilmez; anahtarı adrese koyan istek 401 alır.

Hesap başına bir anahtar oluşturabilir, panelinizden değiştirebilirsiniz (eski anahtar hemen çalışmayı bırakır) ya da iptal edebilirsiniz. Yalnızca GET /v1 ve GET /v1/health anahtarsız çalışır.

Paketler

Sınırlar ve özellikler paketinizden gelir. Anahtarınızın paketi her yanıtta meta.plan olarak döner.

PaketGünlük istekSaniyede istekYanıt başına kartGünlük kartFiyat kaynaklarıPara birimi dönüşümüDereceli fiyatlar ve yapay zekâToplu indirme
Free 100 1 10 1.000 Genel Hayır Hayır Hayır
Pro 1.000 3 50 50.000 Genel ve diğer kaynaklar Evet Hayır Hayır
Business 5.000 10 100 500.000 Genel, diğer kaynaklar ve Binderim satışları Evet Evet Haftalık dosyalar

"Günlük kart", başlık kotadır: günlük istek sayısı çarpı bir isteğin döndürebildiği kart sayısı. Ticari kullanım için Business paketi gerekir; şartlara bakın.

İstek sınırları

Her paketin bir günlük kotası (UTC gününe göre sayılır, 00:00 UTC'de sıfırlanır) ve bir saniye sınırı vardır. Bir uca ulaşan istek, card_not_found gibi bir 4xx yanıtla bitse bile bir istek sayılır. Ondan önce reddedilenler (401, 503) sayılmaz. Geçerli anahtarla gelen her isteğin yanıtı, nerede olduğunuzu söyler:

  • X-RateLimit-Limit: günlük kotanız (istek)
  • X-RateLimit-Remaining: bugün kalan istek
  • X-RateLimit-Reset: kotanın ne zaman sıfırlanacağı (Unix zamanı, saniye)

Bir sınırı aşarsanız 429 ile rate_limited (saniye) ya da daily_quota_exceeded ve saniye cinsinden bir Retry-After başlığı alırsınız. Başarılı yanıtlar 60 saniye önbelleğe alınabilir (Cache-Control: private, max-age=60).

Tek istisna GET /v1/bulk ucudur (Toplu indirme): günlük kotadan düşmez ve kota dolsa da çalışır, ama saniye sınırı geçerlidir; yanıtları hiç önbelleğe alınmaz (Cache-Control: no-store).

Hatalar

Hatalar her yerde aynı biçimdedir. Programınızda code alanını kullanın; message insanlar içindir ve değişebilir.

{ "error": { "code": "invalid_api_key", "message": "Missing, invalid or revoked API key. ..." } }
KodHTTPAnlamı
invalid_api_key401API anahtarı yok, yanlış ya da iptal edilmiş; ya da adresin içinde gönderilmiş.
plan_upgrade_required403Paketiniz bu özelliği, fiyat kaynağını ya da para birimi dönüşümünü içermiyor.
invalid_id400Kart kimliği geçerli değil (küçük harf, rakam ve tire).
invalid_parameter400Bir sorgu parametresi geçerli değil; örneğin page=0.
page_size_too_large400page_size, paketinizin yanıt başına izin verdiği sayıdan büyük.
batch_too_large400Toplu istekte, paketinizin istek başına izin verdiğinden fazla farklı kimlik var.
invalid_body400İstek gövdesi beklenen JSON nesnesi değil.
unknown_source400Fiyat kaynağı adı tanınmıyor.
unknown_currency400Para birimi desteklenmiyor. USD, EUR, GBP ya da TRY kullanın.
game_not_found404Bu kimlikte bir oyun yok. GET /v1/games'e bakın.
set_not_found404Bu kimlikte bir set yok.
card_not_found404Bu kimlikte bir kart yok.
not_found404Bilinmeyen uç.
method_not_allowed405Uç var ama bu HTTP yöntemiyle değil. İzin verilenler Allow başlığındadır.
card_deleted410Kart katalogdan kaldırıldı.
payload_too_large413İstek gövdesi 64 KB'tan büyük.
rate_limited429Saniyede paketinizin izin verdiğinden fazla istek gönderdiniz. Retry-After saniye bekleyin.
daily_quota_exceeded429Günlük kotanız doldu. 00:00 UTC'de sıfırlanır.
internal_error500Bizim tarafımızda bir sorun oldu. Daha sonra yeniden deneyin.
warming_up503Servis açılıyor (ya da yapay zekâ verisi hâlâ yükleniyor). Retry-After saniye sonra yeniden deneyin. Kotanızdan düşmez.
bulk_not_ready503Haftalık toplu dosyalar henüz hazır değil (ilk sürüm hâlâ hazırlanıyor) ya da geçici olarak kullanılamıyor. Retry-After saniye sonra yeniden deneyin. Kotanızdan düşmez.
server_busy503Aynı anda çok fazla istek işleniyor. Kısa süre sonra yeniden deneyin. Kotanızdan düşmez.

message metinleri İngilizcedir.

Yanıt biçimi

Başarılı yanıtlar sonucu data içine koyar ve meta ile tanımlar:

{
  "data": [ ... ],
  "meta": {
    "plan": "free",
    "catalog_as_of": "2026-10-22T06:00:00Z",
    "prices_as_of": "2026-10-22T08:00:00Z",
    "attribution": "Powered by Binderim (https://binderim.com)"
  }
}
  • Alan adları snake_case'tir. Zamanlar UTC, ISO 8601 biçimindedir.
  • Değeri olmayan alan hiç yazılmaz; null dönmez.
  • meta.attribution yalnızca Free pakette bulunur (bkz. Atıf).
  • catalog_as_of ve prices_as_of verinin ne kadar taze olduğunu söyler. Katalog 3 saatte bir, fiyatlar saatte bir yenilenir.

Uçlar

Toplu fiyat ucu POST, diğer bütün uçlar GET (ve HEAD) yanıtlar. Oyun kimlikleri pokemon gibi kısa adlardır; set kimlikleri sayıdır; kart kimlikleri Kart kimlikleri ve birleştirmeler bölümünde anlatılır.

GET /v1/health ve GET /v1

Anahtar yok, kota yok. /v1/health servis hazırsa 200, açılırken 503 yanıtlar; erişim denetimleri için kullanın. GET /v1 API adını ve sürümü döndürür.

{ "status": "ok", "ready": true, "ai_ready": true, "catalog_built_utc": "2026-10-22T06:00:00Z", "prices_built_utc": "2026-10-22T08:00:00Z", "bulk_generated_utc": "2026-10-19T02:00:12Z" }

bulk_generated_utc, en son haftalık toplu sürümün üretildiği zamandır; ilk sürüm oluşana kadar yazılmaz ve status değerini değiştirmez.

curl

curl "https://dev.binderim.com/v1/health"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/health");
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/health",
)
body = res.json()

GET /v1/games

Katalogdaki oyunlar; set ve kart sayılarıyla.

{ "data": [ { "id": "pokemon", "name": "Pokémon", "set_count": 932, "card_count": 76304 } ], "meta": { ... } }

curl

curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/games"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/games", {
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY },
});
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/games",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
)
body = res.json()

GET /v1/games/{game}/sets

Bir oyunun bütün setleri: id, code, name, series, release_date, card_count ve varsa logo / symbol görsel adresleri. Sayfalama yoktur. Bilinmeyen oyun: 404 game_not_found.

curl

curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/games/pokemon/sets"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/games/pokemon/sets", {
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY },
});
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/games/pokemon/sets",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
)
body = res.json()

GET /v1/sets/{id}/cards

Bir setin kartları, kart numarası sırasıyla. Sorgu: page (1'den başlar) ve page_size (varsayılan ve üst sınır, paketinizin yanıt başına kart sayısıdır). meta içinde page, page_size ve total bulunur. Hatalar: set_not_found, invalid_parameter, page_size_too_large.

curl

curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/sets/2841/cards?page=1&page_size=10"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/sets/2841/cards?page=1&page_size=10", {
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY },
});
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/sets/2841/cards?page=1&page_size=10",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
)
body = res.json()

GET /v1/cards/{publicId}

Tek kart: kimlik, oyun, set, ad, numara, dil, nadirlik, görseller ve dış kimlikler. Business pakette yanıtta ayrıca grades ve ai olur. İsteğe bağlı sorgu: currency (grades girdilerine dönüştürülmüş tutar ekler; Pro ve Business).

{
  "data": {
    "id": "pkm-sv08-123-en", "game": "pokemon",
    "set": { "id": "2841", "code": "sv08", "name": "Surging Sparks" },
    "name": "Pikachu", "number": "123", "language": "en", "rarity": "Common",
    "images": { "large": "https://img.binderim.com/images/...", "small": "https://img.binderim.com/images/..." },
    "external_ids": { "tcgplayer": "123456", "pricecharting": { "normal": "1111", "reverse-holo": "2222" } }
  },
  "meta": { ... }
}

curl

curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/cards/pkm-sv08-123-en"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/cards/pkm-sv08-123-en", {
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY },
});
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/cards/pkm-sv08-123-en",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
)
body = res.json()

GET /v1/cards/{publicId}/prices

Bir kartın en son fiyatları; kaynak, fiyat türü ve varyant başına bir girdi. İsteğe bağlı sorgu: source (tek bir kaynak adı) ve currency (USD, EUR, GBP ya da TRY; Pro ve Business). Business ayrıca grades alır. Bkz. Fiyatlar ve para birimleri.

{
  "data": {
    "card_id": "pkm-sv08-123-en",
    "prices": [
      { "source": "general", "type": "market", "variant": "normal", "amount": 1.5, "currency": "USD", "as_of": "2026-10-22T03:12:00Z" },
      { "source": "tcgplayer", "type": "market", "variant": "reverse-holo", "amount": 2.1, "currency": "USD", "as_of": "2026-10-22T03:12:00Z",
        "converted": { "amount": 1.57, "currency": "GBP", "rate": 0.748, "rate_date": "2026-10-22" } }
    ]
  },
  "meta": { ... }
}

curl

curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/cards/pkm-sv08-123-en/prices?currency=GBP&source=tcgplayer"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/cards/pkm-sv08-123-en/prices?currency=GBP&source=tcgplayer", {
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY },
});
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/cards/pkm-sv08-123-en/prices?currency=GBP&source=tcgplayer",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
)
body = res.json()

POST /v1/prices/batch

Tek istekte birçok kartın fiyatı. { "ids": [...], "currency": "USD", "source": "general" } gönderin (currency ve source isteğe bağlıdır). Gövde en fazla 64 KB olabilir ve farklı kimlik sayısı en fazla paketinizin yanıt başına kart sayısı kadardır. Tekrarlanan kimlikler bir kez yanıtlanır. Her kimliğin kendi sonucu vardır:

  • ok: id, prices (Business'ta grades da)
  • merged: gönderdiğiniz kimlik emekli edilmiş; merged_into kullanmanız gereken kimliktir, fiyatlar o kartındır
  • deleted, not_found, invalid_id: fiyat yok; isteğin kendisi yine başarılıdır
{ "data": [ { "requested_id": "pkm-sv08-123-en", "status": "ok", "id": "pkm-sv08-123-en", "prices": [ ... ] },
            { "requested_id": "pkm-old-001-en", "status": "merged", "merged_into": "pkm-sv08-001-en", "prices": [ ... ] },
            { "requested_id": "pkm-gone-001-en", "status": "deleted" } ], "meta": { ... } }

curl

curl -X POST -H "X-Api-Key: $BINDERIM_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids": ["pkm-sv08-123-en", "mtg-snc-1-en"], "currency": "USD"}' \
  "https://dev.binderim.com/v1/prices/batch"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/prices/batch", {
  method: "POST",
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({"ids": ["pkm-sv08-123-en", "mtg-snc-1-en"], "currency": "USD"}),
});
const body = await res.json();

Python

import os, requests

res = requests.post(
    "https://dev.binderim.com/v1/prices/batch",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
    json={"ids": ["pkm-sv08-123-en", "mtg-snc-1-en"], "currency": "USD"},
)
body = res.json()

GET /v1/bulk

Yalnızca Business paketi. Haftalık toplu dosyalar için süreli indirme bağlantıları; Toplu indirme bölümüne bakın. İsteğe bağlı sorgu: game (tek oyunun dosyaları ve retired_ids). Hatalar: diğer paketlerde plan_upgrade_required, game_not_found, bulk_not_ready.

curl

curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/bulk?game=pokemon"

JavaScript

const res = await fetch("https://dev.binderim.com/v1/bulk?game=pokemon", {
  headers: { "X-Api-Key": process.env.BINDERIM_API_KEY },
});
const body = await res.json();

Python

import os, requests

res = requests.get(
    "https://dev.binderim.com/v1/bulk?game=pokemon",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
)
body = res.json()

Fiyatlar ve para birimleri

API yalnızca en son fiyatı döndürür. Fiyat geçmişi yoktur. Tazelik sınırından eski bir fiyat, bayat döndürülmek yerine yanıttan çıkarılır.

KaynakNedirPaket
generalBinderim'in bir kart için gösterdiği genel fiyat, varyant başına. Tür market.Bütün paketler
tcgplayer, ebay, ygoprodeck, lorcast, optcgapi, cardmarketBu pazarlardan ve beslemelerden fiyatlar. Türler market, trend ya da card_low (kartın bütün baskıları arasındaki en düşük fiyat). Cardmarket fiyatları Pokémon ve One Piece için döndürülmez.Pro ve Business
binderim-tr, binderim-ukKartların Binderim'de gerçekte ne kadara satıldığı: sold_median (sample_size ile, son 90 gündeki satış sayısı) ve last_sold. Yakın zamanlı verisi olmayan pazar girdi döndürmez.Business
  • Tazelik. Günlük kaynaklar en fazla 3 günlük, ygoprodeck en fazla 8 günlük, Binderim satışları en fazla 24 saatlik olmalıdır.
  • Tutarlar kaynağın para birimindedir (her girdideki currency). condition, kart durumuna bağlı Binderim satışlarında bulunur.
  • Dönüştürme. currency=GBP ile (Pro ve Business) her girdiye ayrıca converted eklenir: tutar, kur ve kurun tarihi. Elimizde taze bir döviz kuru yoksa converted yazılmaz; asıl tutar her zaman vardır.
  • Kaynak seçmek. source=tcgplayer, prices listesini o kaynağa daraltır. pricecharting isteyebileceğiniz bir kaynak adı değildir; ham fiyat general'dir. Yalnızca grades içinde source olarak görünür.
  • Paketinizin içermediği bir şeyi (para birimi, kaynak) istemek 403 plan_upgrade_required döndürür.

Kart kimlikleri ve birleştirmeler

Her kartın hiç değişmeyen, okunabilir bir kimliği vardır; örneğin pkm-sv08-123-en: oyun öneki, set, kart numarası ve dil (en, ja, zh, ko). Kimlikler küçük harf, rakam ve tireden oluşur, en fazla 160 karakterdir. Saklayın; kendi veritabanınızda tutmak güvenlidir.

  • Aynı kartın iki katalog kaydı birleştirilirse emekli kimlik çalışmaya devam eder: birleştirildiği kartı alırsınız ve merged_from hangi kimliği istediğinizi söyler. Toplu istekte sonuçta status: merged ve merged_into bulunur. Elinizden geldiğinde yeni kimliğe geçin; yönlendirme (redirect) yoktur, çünkü ikinci istek kotanızdan yine düşerdi.
  • Katalogdan kaldırılan kart 410 card_deleted yanıtlar (toplu istekte status: deleted).
  • Var olmayan kimlik 404 card_not_found, biçimi bozuk kimlik 400 invalid_id yanıtlar.
  • Bir kimlik başka bir kart için asla yeniden kullanılmaz.

Varyantlar ve dereceler

Bir fiyatın variant alanı, tire ile ayrılmış küçük harfli bir addır; örneğin normal, foil ya da etched. Bu adlar bilerek okunabilirdir ve birkaçının sabit bir dış adı vardır:

VaryantAnlamı
1st-editionBirinci baskı (1st edition)
master-ball-reverseMaster Ball desenli reverse holo
poke-ball-reversePoké Ball desenli reverse holo
reverse-holoReverse holo baskı

Aynı adlar external_ids.pricecharting içinde anahtar olarak da kullanılır; bu alan her varyantı fiyat kaynağının ürün numarasına eşler.

Dereceler (Business) derecelendirilmiş kopyaların fiyatlarıdır. grades içindeki her girdinin bir grade anahtarı vardır:

DereceAnlamı
psa10PSA 10
bgs10Beckett (BGS) 10
cgc10CGC 10
sgc10SGC 10
grade7Herhangi bir derecelendirme şirketinden 7
grade8Herhangi bir derecelendirme şirketinden 8
grade9Herhangi bir derecelendirme şirketinden 9
grade95Herhangi bir derecelendirme şirketinden 9,5

grade9, herhangi bir derecelendirme şirketinden 9 demektir; sayısal dereceleri şirkete göre ayırmayız.

Yapay zekâ bloğu

Business pakette GET /v1/cards/{publicId} yanıtında, görsel analizimizin kartın ön yüzünde bulduklarını içeren bir ai bloğu bulunur: model_version, colors, emotions, mood, style, setting, time_of_day, weather, character_count ve description. beta nesnesi (objects, characters, costumes) deneyseldir ve değişebilir.

Analizin karar veremediği değerler yazılmaz. Analizi olmayan kartta ai alanı yoktur. Yeniden başlatmadan sonra yapay zekâ verisi yüklenirken Business'ın tek kart istekleri kotadan düşmeden 503 warming_up yanıtlar.

Toplu indirme (Business)

Business paketi, kataloğun tamamının haftalık dosyalarını içerir. İlk kurulum ve tam bir kopya tutmak içindir; arada olan değişiklikler için yukarıdaki uçları kullanın. Dosyaları indirmek günlük kotanızdan düşmez.

Takvim

Yeni bir sürüm her Pazartesi yaklaşık 02:00 UTC'de (Türkiye saatiyle 05:00) hazırlanır ve o andaki veriyi taşır. Sürüm kimliği 20261026T020012Z gibidir: hazırlığın başladığı zaman. En son üç sürüm saklanır. Yeni sürüm hazır olana kadar bir öncekisi kullanılabilir kalır; yanıttaki next_release_after, sıradaki sürümü ne zaman bekleyeceğinizi söyler. Hazırlık başarısız olursa önceki sürüm kalır ve hazırlık yeniden denenir.

GET /v1/bulk, en son sürümün dosyalarını her biri için bir indirme bağlantısıyla listeler. İsteğe bağlı game parametresi listeyi tek oyunun dosyaları ve retired_ids ile sınırlar. Her bağlantı 15 dakika geçerlidir ve bir bağlantı sonraki birkaç dakika içinde yeniden verilebilir; bu yüzden bir yanıttaki her bağlantının en az 5 dakikası kalır. url_expires_at, bunlardan en erken bitenin bittiği andır: geçince yeniden isteyin. Başlamış bir indirme kesilmez. Bağlantıyı bir parola gibi görün ve paylaşmayın.

  • Günlük kotanızdan düşmez ve kota dolsa da çalışır. Paketinizin saniye sınırı yine geçerlidir.
  • Diğer paketler 403 plan_upgrade_required alır.
  • İlk sürüm hazırlanırken ya da depolama kullanılamıyorsa Retry-After: 3600 ile 503 bulk_not_ready alırsınız. Daha sonra yeniden deneyin.
{
  "data": {
    "release": "20261026T020012Z",
    "generated_at": "2026-10-26T02:00:12Z",
    "catalog_as_of": "2026-10-26T00:00:09Z", "prices_as_of": "2026-10-26T01:00:03Z", "ai_as_of": "2026-10-25T14:00:21Z",
    "next_release_after": "2026-11-02T02:00:00Z",
    "url_expires_at": "2026-10-26T09:15:00Z",
    "manifest_url": "https://...",
    "files": [
      { "game": "pokemon", "kind": "cards", "records": 76304, "bytes": 2380000, "sha256": "9f2c...", "url": "https://..." },
      { "kind": "retired_ids", "records": 0, "bytes": 20, "sha256": "ac73...", "url": "https://..." }
    ]
  },
  "meta": { ... }
}

Dosyalar

Her oyun için dört dosya vardır: sets, cards, prices ve ai (bir dosyaya koyacak bir şeyi olmayan oyunun dosyası yine vardır, boştur). Bir dosya daha, retired_ids, bütün oyunları kapsar. Her dosya gzip ile sıkıştırılmış JSON Lines'tır (UTF-8): her satırda bir JSON nesnesi. Her satır, API'nin döndürdüğü nesnenin aynısıdır:

DosyaHer satırSatırı olmayan
setsGET /v1/games/{game}/sets yanıtındaki bir öğe-
cardsGET /v1/sets/{id}/cards yanıtındaki bir öğe. grades ve ai içinde yoktur: kendi dosyaları var.-
pricesGET /v1/cards/{publicId}/prices yanıtının data kısmı: card_id, prices ve gradesHiç fiyatı olmayan kart
ai{ "card_id", "ai" }; ai, GET /v1/cards/{publicId} yanıtındaki blokturYapay zekâ bloğu olmayan kart
retired_ids{ "id", "status", "merged_into" }. status, toplu fiyat ucundaki gibi merged ya da deleted'dır.-

Dosyalar, Business paketi için API ile aynı kurallara uyar: aynı fiyat kaynakları, tazelik sınırları, varyant adları, görsel bağlantıları ve yapay zekâ değerleri.

Para birimleri. Tutarlar kendi kaynağının para birimindedir. Döviz kurları manifest'te exchange_rates olarak bulunur (rates[X], bir ABD dolarının X cinsinden değeridir). Dönüştürmek için amount / rates[from] * rates[to] kullanın ve 2 haneye yuvarlayın; API de böyle yapar. Manifest'te exchange_rates yoksa kurlar kullanılamayacak kadar eskidir: dönüştürmeyin.

Manifest ve sağlama toplamları

manifest.json, sürümün her dosyasını kayıt sayısı, boyutu ve SHA-256 sağlama toplamıyla listeler. Sağlama toplamı, indirdiğiniz haliyle sıkıştırılmış dosyaya aittir; kaydettikten sonra kontrol edin.

{
  "format_version": 1,
  "release": "20261026T020012Z",
  "generated_at": "2026-10-26T02:00:12Z",
  "catalog_as_of": "...", "prices_as_of": "...", "ai_as_of": "...",
  "exchange_rates": { "base": "USD", "rate_date": "2026-10-25", "rates": { "EUR": 0.891, "GBP": 0.748, "TRY": 49.6, "USD": 1 } },
  "files": [ { "game": "pokemon", "kind": "cards", "path": "pokemon/cards.jsonl.gz", "records": 76304, "bytes": 2380000, "sha256": "9f2c..." } ]
}

Örnek

Dosyalar saklandığı gibi, Content-Encoding başlığı olmadan gönderilir; bu yüzden HTTP istemciniz onları açmaz: baytları kaydedin, sağlama toplamını kontrol edin, sonra açın. API anahtarınızı hiçbir zaman bir indirme bağlantısına göndermeyin.

# 1. Bağlantıları isteyin (günlük kotanızdan düşmez)
curl -H "X-Api-Key: $BINDERIM_API_KEY" "https://dev.binderim.com/v1/bulk?game=pokemon"

# 2. Yanıttaki url ile bir dosyayı indirin, sonra kontrol edip okuyun
curl -o pokemon-cards.jsonl.gz "<yanıttaki url>"
sha256sum pokemon-cards.jsonl.gz      # yanıttaki sha256 ile karşılaştırın
gunzip -c pokemon-cards.jsonl.gz | head -n 2
import gzip, hashlib, json, os, requests

release = requests.get(
    "https://dev.binderim.com/v1/bulk?game=pokemon",
    headers={"X-Api-Key": os.environ["BINDERIM_API_KEY"]},
).json()["data"]
entry = next(f for f in release["files"] if f["kind"] == "cards")

raw = requests.get(entry["url"]).content          # .gz baytları, saklandığı gibi
assert hashlib.sha256(raw).hexdigest() == entry["sha256"]

for line in gzip.decompress(raw).splitlines():
    card = json.loads(line)
    print(card["id"], card.get("name"))

Kimlikleri güncel tutmak

Sakladığınız kimlikleri güncellemek için retired_ids dosyasını kullanın: merged ise kimliği merged_into ile değiştirin; deleted ise kartı kaldırın. Dosyada olmayan bir kimlik canlı bir karttır (ya da hiç tanımadığımız bir kimlik). Kimliklerin nasıl davrandığı için Kart kimlikleri ve birleştirmeler bölümüne bakın.

Atıf

Free pakette, verimizi gösterdiğiniz her yerde https://binderim.com bağlantılı Powered by Binderim yazısını göstermeniz gerekir. Kullanılacak metin meta.attribution içindedir. Pro ve Business'ta atıf zorunluluğu yoktur. Ayrıntılar şartlardadır.

OpenAPI dosyası

API'nin tamamı bir OpenAPI 3.1 dosyasında tanımlıdır: /openapi/v1.json. Postman'e, Insomnia'ya ya da bir kod üreticiye aktarın. Her ucu, yanıt biçimini ve hata kodunu listeler ve gerçek yanıtlarla karşılaştırılarak denetlenir.

Değişiklik günlüğü

  • v1: ilk herkese açık sürüm: oyunlar, setler, kartlar, birden çok kaynaktan en son fiyatlar, toplu fiyat, birleştirme yönetimli kalıcı kart kimlikleri, dönüştürülmüş tutarlar, Business için dereceli fiyatlar ve yapay zekâ bloğu ve OpenAPI dosyası.
  • Yayından önce: dört iç fiyat varyant kodu yukarıdaki okunabilir adlarla değiştirildi; v1 onları hiç göstermez.
  • v1: Business için toplu indirme: GET /v1/bulk ve haftalık .jsonl.gz dosyaları, bulk_not_ready hata kodu ve /v1/health içinde bulk_generated_utc.

Bir programı bozabilecek değişiklikler yeni sürüm (/v2) gerektirir; /v1 olduğu gibi kalır.