Yarış API

Yarış Radarı, Türkiye'deki yol ve patika koşusu, bisiklet, yüzme, triatlon ve HYROX yarışlarını her gün on kaynaktan tarayıp tek takvimde topluyor. Bu sayfadaki okuma amaçlı JSON API aynı veri kümesini uygulamalara açar: tarihler, şehirler ve koordinatlar, branşlar, parkurlar (mesafe, yükseklik kazanımı, ITRA puanı, ücret), kayıt pencereleri ve son kayıt tarihleri, resmi site ve sonuç bağlantıları. Yarış başına opsiyonel highlights objesiyle parkur GPX ve harita görseli, kontrol noktaları, sonuç arşivi ve katılımcı sayıları da aynı yanıtta geliyor.

Güncel yarış takvimine ihtiyaç duyan uygulamalar, antrenman platformları ve yayınlar için düşünüldü. Taban adres: https://yarisradari.com/api/v1

Kimlik doğrulama

Her istekte anahtarını iki header'dan biriyle gönder. Anahtarlar sunucular arası kullanım için tasarlandı.

Authorization: Bearer yr_live_xxxxxxxx
X-API-Key: yr_live_xxxxxxxx

GET/races

Filtrelenebilir yarış listesi. Tüm parametreler opsiyonel; csv tipindekiler virgülle birden çok değer alır. distance_min/max verilince dönen distances dizisi sadece eşleşen parkurlara filtrelenir.

curl "https://yarisradari.com/api/v1/races?sport=trail_run&from=2026-09-01&limit=5" \
  -H "Authorization: Bearer yr_live_xxxxxxxx"

Yanıt:

{
  "data": [
    {
      "id": "uuid",
      "slug": "istanbul-maratonu-2026",
      "url": "https://yarisradari.com/yaris/istanbul-maratonu-2026",
      "url_en": "https://yarisradari.com/en/yaris/istanbul-maratonu-2026",
      "name": "İstanbul Maratonu",
      "sport": "road_run",
      "scope": "national",
      "status": "scheduled",
      "city": "İstanbul",
      "venue": null,
      "country_code": "TR",
      "start_date": "2026-11-01",
      "end_date": null,
      "latitude": 41.0,
      "longitude": 28.9,
      "website_url": "https://...",
      "results_url": null,
      "photos_url": null,
      "price_excludes_federation_fee": false,
      "description_tr": "...",
      "description_en": null,
      "distances": [
        {
          "label": "Maraton",
          "course_key": "maraton",
          "has_route": false,
          "route_updated_at": null,
          "distance_km": 42.195,
          "start_date": "2026-11-01",
          "start_time": "09:00:00",
          "elevation_gain_m": null,
          "itra_points": null,
          "price": 1500,
          "currency": "TRY",
          "swim_km": null,
          "bike_km": null,
          "run_km": null,
          "gpx_url": null
        }
      ],
      "registration": [
        {
          "kind": "standard",
          "opens_at": null,
          "closes_at": "2026-10-20T23:59:00+03:00",
          "price": null,
          "currency": "TRY",
          "is_lottery": false,
          "registration_url": "https://..."
        }
      ],
      "highlights": {
        "route": {
          "courses_with_gpx": 2,
          "gpx_url": "https://...",
          "map_image_url": "https://yarisradari.com/yaris/istanbul-maratonu-2026/parkur/maraton-parkur-profili.svg"
        },
        "briefing": true,
        "checkpoints": { "count": 8, "with_cutoff": 6, "courses": 2 },
        "results": { "editions": 4, "last_edition_year": 2025, "courses": 3 },
        "participants": { "last_edition_year": 2025, "starters": 2972, "finishers": 2954 }
      },
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "meta": { "total": 90, "count": 25, "limit": 25, "offset": 0, "request_id": "uuid" }
}

url alanı yarışın yarisradari.com'daki sayfası (https://yarisradari.com/yaris/{slug}), url_en aynı sayfanın İngilizcesi (https://yarisradari.com/en/yaris/{slug}). Lisanstaki siteye bağlantı şartını yarış ekranında bu adrese bağlanarak karşılayabilirsin; İngilizce arayüzde url_en'i kullan.

highlights: yarışa özel ek veriler

Her yarış nesnesinde opsiyonel bir highlights objesi gelir. Kural şu: bir anahtar yalnızca o yarış için gerçekten veri varsa gönderilir, boş anahtar, null ya da false gönderilmez, yani anahtarın varlığı verinin varlığı demektir. Değerler yapısal veridir, hazır cümle değil; metni tüketici kendi dilinde kurar. Yeni anahtar eklenebilir, var olan anahtar yeniden adlandırılmaz, bu yüzden tanımadığın anahtarı yok sayabilirsin. Hava durumu bu objeye girmez, tahmin çabuk bayatladığı için ayrı tutulur.

GET/races/{slug}

Tek yarışın detayı, liste ile aynı alan yapısında: { "data": { ... }, "meta": { "request_id": "uuid" } }. Bulunamazsa 404 döner.

Tekil yarış yanıtında iki ek dizi gelir: result_sources (edisyon yılı başına sonuç kaynağı: sağlayıcı, sayfa ve veri adresi, durum, parkur eşlemesi, bib sorgu adresi) ve results_summary (sonuç arşivindeki parkur bazlı başlayan, bitiren, DNF ve bitiş süresi yüzdelikleri). İkisi de sporcu satırı içermez; veri yoksa boş dizi döner.

"result_sources": [
  {
    "edition_year": 2026,
    "provider": "g-live",
    "format": "clax",
    "status": "final",
    "final_at": "2026-07-20T06:10:00Z",
    "last_checked_at": "2026-10-15T04:00:00Z",
    "event_date": "2026-07-18",
    "page_url": "https://...",
    "data_url": "https://.../uput2026.clax",
    "provider_ids": {},
    "course_map": { "UPUT70K": "70K" },
    "lookup_url": "https://yarisradari.com/api/v1/races/uludag-ultra-trail/results?year=2026&bib="
  }
],
"results_summary": [
  {
    "edition_year": 2026, "provider": "g-live", "course_label": "UPUT70K", "label": "70K", "distance_km": 70.83,
    "registered": 197, "starters": 181, "finishers": 152, "dnf": 29,
    "fastest_seconds": 31380, "slowest_seconds": 59700,
    "p10_seconds": 36000, "p25_seconds": 41000, "p50_seconds": 48780, "p75_seconds": 53000, "p90_seconds": 57060,
    "page_url": "https://..."
  }
]

GET/races/{slug}/results

Göğüs numarasıyla kişisel sonuç. Veri sağlayıcıdan anlık okunur ve yalnızca kısa süre önbellekte tutulur; sporcu satırları Yarış Radarı veritabanına yazılmaz. Ad maskelidir (Ahmet Y.), doğum yılı ve uyruk hiçbir zaman dönmez. Sıralama sağlayıcı yayınladıysa onundur, yoksa Yarış Radarı net süreye göre hesaplar, net süre yoksa brüte bakar (ranking_basis).

pending true gelirse sağlayıcı listesi henüz tamamen okunmamıştır: Retry-After başlığındaki süre sonra aynı isteği tekrarla. Durum final olana ya da yarıştan 14 gün sonrasına kadar yoklamak yeterlidir; her istek kotadan düşer. Yıl için kaynak yoksa 404 no_result_source, sağlayıcı cevap vermezse 503 results_unavailable döner. Sağlayıcı sunucu IP'lerine bot duvarı döndürüyorsa (şu an PlusTiming) yanıt status blocked ile gelir ve client_fetch alanı cihazdan yapılacak GET adresini taşır; isim aramasında da aynı alan boş candidates ile 200 döner.

curl "https://yarisradari.com/api/v1/races/uludag-ultra-trail/results?bib=123&year=2026" \
  -H "Authorization: Bearer yr_live_xxxxxxxx"

Yanıt:

{
  "data": {
    "status": "final",
    "pending": false,
    "edition_year": 2026,
    "final_at": "2026-07-20T06:10:00Z",
    "fetched_at": "2026-10-15T09:00:12Z",
    "source": { "provider": "g-live", "page_url": "https://..." },
    "result": {
      "bib": "123",
      "name": "Ahmet Y.",
      "finished": true,
      "course": { "label": "70K", "distance_km": 70.8, "provider_name": "UPUT70K", "mapped": true },
      "net_seconds": 31380,
      "gross_seconds": 31402,
      "rankings": {
        "overall": { "rank": 1, "total": 152 },
        "gender": { "rank": 1, "total": 118, "value": "M" },
        "category": { "rank": 1, "total": 37, "value": "M40-49" }
      },
      "ranking_basis": "provider",
      "splits": [{ "name": "Dere", "km": 10.0, "seconds": 3600 }],
      "page_url": "https://..."
    }
  },
  "meta": { "request_id": "uuid" }
}

GET/races/{slug}/courses/{course_key}/route

Parkurun haritada çizilecek rotası: Google encoded polyline (hassasiyet 5, en fazla 1500 nokta, 5 m tolerans), 100 metrede bir [mesafe_m, irtifa_m] yükseklik profili, başlangıç ve bitiş noktası. Rota günlük taramada organizatörün GPX, TCX, KML ya da KMZ dosyasından üretilir; dosyada yalnız koordinat ve irtifa tutulur, zaman damgası ve nabız atılır. Uzunluğu parkur mesafesinden %15 fazla sapan, şehir merkezine 200 km'den uzak başlayan ya da parkura eşlenemeyen dosya verilmez. Hangi parkurun rotası olduğu distances[].has_route ile, son değişimi distances[].route_updated_at ile görünür.

Yanıt ETag taşır; If-None-Match ile sorarsan rota değişmediyse 304 gövdesiz döner. Rotayı kendi tarafında sakla, route_updated_at değişince yenile. Parkur yoksa 404 course_not_found, parkurun doğrulanmış rotası yoksa 404 route_not_available döner.

curl "https://yarisradari.com/api/v1/races/uludag-ultra-trail/courses/21k/route" \
  -H "Authorization: Bearer yr_live_xxxxxxxx" \
  -H 'If-None-Match: "3f1c...-2026"'

Yanıt:

{
  "data": {
    "course_key": "21k",
    "label": "21K",
    "edition_year": 2026,
    "is_previous_edition": false,
    "distance_km": 21.08,
    "polyline": "_p~iF~ps|U_ulLnnqC...",
    "point_count": 812,
    "elevation_gain_m": 240,
    "elevation_loss_m": 238,
    "start": { "lat": 40.1, "lng": 29.1 },
    "finish": { "lat": 40.1, "lng": 29.1 },
    "is_loop": true,
    "profile": [[0, 1820], [100, 1826], [200, 1833]],
    "source_url": "https://organizator.com/parkur-21k.gpx",
    "updated_at": "2026-10-10T08:00:00Z",
    "checksum": "3f1c..."
  },
  "meta": { "request_id": "..." }
}

GET/tools/hazirlik-suresi

Hazırlık süresi hesaplayıcısının anahtarsız, açık ucu: yarış slug ya da ham mesafe verirsin, kaç hafta gerektiğini, zirve haftayı ve en geç başlama gününü döndürür. Anahtar, kota ve dakika limiti bu uca işlemez; yanıt 5 dakika önbelleklenir.

curl "https://yarisradari.com/tools/hazirlik-suresi?yaris=alanya-ultra-trail&haftalik=30"

Yanıt:

{
  "input": {
    "km": 90,
    "elevation_gain_m": 4500,
    "weekly_km": 30,
    "run_days": 4,
    "today": "2026-09-18",
    "race": {
      "name": "ALANYA ULTRA TRAIL",
      "slug": "alanya-ultra-trail",
      "course": "90K",
      "start_date": "2027-03-27"
    }
  },
  "result": {
    "weeks": 23,
    "months": 5.5,
    "peak_weekly_km": 95,
    "peak_long_run_km": 35,
    "start_by": "2026-10-17",
    "weeks_left": 27,
    "late": false,
    "volume_ready": false
  },
  "sentence": {
    "tr": "ALANYA ULTRA TRAIL 90K parkuru için haftada 30 km koşan biri hazırlığa 23 hafta, yaklaşık 5,5 ay ayırmalı; en geç 17 Ekim 2026 Cumartesi günü başlamalı. Zirve hafta 95 km efor, en uzun antrenman koşusu 35 km.",
    "en": "Someone running 30 km a week needs 23 weeks, about 5.5 months, to prepare for the 90K course of ALANYA ULTRA TRAIL; the latest start is Sat, Oct 17, 2026. The peak week reaches 95 effort km with a 35 km long run."
  },
  "page": "https://yarisradari.com/araclar/hazirlik-suresi?yaris=alanya-ultra-trail&parkur=90K&haftalik=30"
}

sentence alanı Türkçe ve İngilizce hazır cümleyi birlikte verir; bir ajana doğrudan aktarılabilir. page alanı aynı hesabın insan okunur sayfasını gösterir.

Hatalı ya da eksik parametrede 400 bad_request, eşleşen yarış ya da parkur yoksa 404 race_not_found döner; yaris yalnız bugün ve sonrasındaki, iptal edilmemiş yol ve patika koşularını bulur. Hata gövdesi Limitler ve hatalar bölümündeki yapıdadır.

JavaScript örneği

const res = await fetch(
  'https://yarisradari.com/api/v1/races?sport=trail_run&distance_min=40',
  { headers: { Authorization: `Bearer ${process.env.YARISRADARI_API_KEY}` } },
)
const { data, meta } = await res.json()

Limitler ve hatalar

Aylık kota ve dakika limiti anahtar bazındadır; kalan hakkını X-Quota-Remaining ve X-RateLimit-Remaining yanıt başlıklarından izleyebilirsin. Her yanıtta log korelasyonu için X-Request-Id bulunur. Hatalar şu formatta döner:

{
  "error": "missing_api_key",
  "message": "No API key was sent. Send your key in the Authorization header as \"Bearer <key>\" or in the X-API-Key header. To get a key, use request_key_url.",
  "documentation_url": "https://yarisradari.com/en/race-api#kimlik-dogrulama",
  "request_key_url": "https://yarisradari.com/en/contact?konu=api",
  "request_id": "uuid"
}

error makine okunur koddur. message sorunu İngilizce anlatır; documentation_url bu sayfanın ilgili bölümüne, request_key_url (yalnız 401 hatalarında) anahtar isteme formuna götürür.

Lisans ve kullanım koşulları

Sürüm 2026-08-05. Anahtarı alan taraf bu koşulları kabul etmiş sayılır.

Veri organizatör ve federasyon kaynaklarından otomatik derlenir, hata payı vardır ve garanti verilmez. Kayıt kararı öncesinde organizatörün resmi sayfası esastır.

Makine okunur tanım

Tüm uç noktalar, parametreler ve yanıt şeması OpenAPI 3.1 olarak /openapi.json adresinde. İstemci üretmek ya da bir ajana bağlamak için bu dosyayı kullan.

Erişim anahtarı

API erişim anahtarıyla çalışıyor. Kullanmak istersen iletişim sayfasından yazman yeterli; ihtiyacına uygun bir planı birlikte konuşuruz.