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
- Binderim hesabınızla giriş yapın (sağ üstte).
- API şartlarını kabul edin ve panelinizde bir API anahtarı oluşturun. Anahtar bir kez gösterilir; o anda kopyalayın.
- Anahtarı her istekle gönderin ve yanıtın
datakı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.
| Paket | Günlük istek | Saniyede istek | Yanıt başına kart | Günlük kart | Fiyat 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 istekX-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. ..." } }
| Kod | HTTP | Anlamı |
|---|---|---|
invalid_api_key | 401 | API anahtarı yok, yanlış ya da iptal edilmiş; ya da adresin içinde gönderilmiş. |
plan_upgrade_required | 403 | Paketiniz bu özelliği, fiyat kaynağını ya da para birimi dönüşümünü içermiyor. |
invalid_id | 400 | Kart kimliği geçerli değil (küçük harf, rakam ve tire). |
invalid_parameter | 400 | Bir sorgu parametresi geçerli değil; örneğin page=0. |
page_size_too_large | 400 | page_size, paketinizin yanıt başına izin verdiği sayıdan büyük. |
batch_too_large | 400 | Toplu istekte, paketinizin istek başına izin verdiğinden fazla farklı kimlik var. |
invalid_body | 400 | İstek gövdesi beklenen JSON nesnesi değil. |
unknown_source | 400 | Fiyat kaynağı adı tanınmıyor. |
unknown_currency | 400 | Para birimi desteklenmiyor. USD, EUR, GBP ya da TRY kullanın. |
game_not_found | 404 | Bu kimlikte bir oyun yok. GET /v1/games'e bakın. |
set_not_found | 404 | Bu kimlikte bir set yok. |
card_not_found | 404 | Bu kimlikte bir kart yok. |
not_found | 404 | Bilinmeyen uç. |
method_not_allowed | 405 | Uç var ama bu HTTP yöntemiyle değil. İzin verilenler Allow başlığındadır. |
card_deleted | 410 | Kart katalogdan kaldırıldı. |
payload_too_large | 413 | İstek gövdesi 64 KB'tan büyük. |
rate_limited | 429 | Saniyede paketinizin izin verdiğinden fazla istek gönderdiniz. Retry-After saniye bekleyin. |
daily_quota_exceeded | 429 | Günlük kotanız doldu. 00:00 UTC'de sıfırlanır. |
internal_error | 500 | Bizim tarafımızda bir sorun oldu. Daha sonra yeniden deneyin. |
warming_up | 503 | Servis açılıyor (ya da yapay zekâ verisi hâlâ yükleniyor). Retry-After saniye sonra yeniden deneyin. Kotanızdan düşmez. |
bulk_not_ready | 503 | Haftalı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_busy | 503 | Aynı 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;
nulldönmez. meta.attributionyalnızca Free pakette bulunur (bkz. Atıf).catalog_as_ofveprices_as_ofverinin 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'tagradesda)merged: gönderdiğiniz kimlik emekli edilmiş;merged_intokullanmanız gereken kimliktir, fiyatlar o kartındırdeleted,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.
| Kaynak | Nedir | Paket |
|---|---|---|
general | Binderim'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, cardmarket | Bu 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-uk | Kartları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,
ygoprodecken 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=GBPile (Pro ve Business) her girdiye ayrıcaconvertedeklenir: tutar, kur ve kurun tarihi. Elimizde taze bir döviz kuru yoksaconvertedyazılmaz; asıl tutar her zaman vardır. - Kaynak seçmek.
source=tcgplayer,priceslistesini o kaynağa daraltır.pricechartingisteyebileceğiniz bir kaynak adı değildir; ham fiyatgeneral'dir. Yalnızcagradesiçindesourceolarak görünür. - Paketinizin içermediği bir şeyi (para birimi, kaynak) istemek
403 plan_upgrade_requireddö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_fromhangi kimliği istediğinizi söyler. Toplu istekte sonuçtastatus: mergedvemerged_intobulunur. 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_deletedyanıtlar (toplu istektestatus: deleted). - Var olmayan kimlik
404 card_not_found, biçimi bozuk kimlik400 invalid_idyanı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:
| Varyant | Anlamı |
|---|---|
1st-edition | Birinci baskı (1st edition) |
master-ball-reverse | Master Ball desenli reverse holo |
poke-ball-reverse | Poké Ball desenli reverse holo |
reverse-holo | Reverse 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:
| Derece | Anlamı |
|---|---|
psa10 | PSA 10 |
bgs10 | Beckett (BGS) 10 |
cgc10 | CGC 10 |
sgc10 | SGC 10 |
grade7 | Herhangi bir derecelendirme şirketinden 7 |
grade8 | Herhangi bir derecelendirme şirketinden 8 |
grade9 | Herhangi bir derecelendirme şirketinden 9 |
grade95 | Herhangi 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.
Bağlantıları almak
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_requiredalır. - İlk sürüm hazırlanırken ya da depolama kullanılamıyorsa
Retry-After: 3600ile503 bulk_not_readyalı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:
| Dosya | Her satır | Satırı olmayan |
|---|---|---|
sets | GET /v1/games/{game}/sets yanıtındaki bir öğe | - |
cards | GET /v1/sets/{id}/cards yanıtındaki bir öğe. grades ve ai içinde yoktur: kendi dosyaları var. | - |
prices | GET /v1/cards/{publicId}/prices yanıtının data kısmı: card_id, prices ve grades | Hiç fiyatı olmayan kart |
ai | { "card_id", "ai" }; ai, GET /v1/cards/{publicId} yanıtındaki bloktur | Yapay 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/bulkve haftalık.jsonl.gzdosyaları,bulk_not_readyhata kodu ve/v1/healthiçindebulk_generated_utc.
Bir programı bozabilecek değişiklikler yeni sürüm (/v2) gerektirir; /v1 olduğu gibi kalır.