Race API

Yarış Radarı scans ten sources every day and gathers road and trail running, cycling, swimming, triathlon and HYROX races in Türkiye into a single calendar. This read-only JSON API opens the same dataset to applications: dates, cities and coordinates, sports, courses (distance, elevation gain, ITRA points, fee), registration windows and deadlines, official site and results links.

Built for apps, training platforms and publications that need an up-to-date race calendar. Base URL: https://yarisradari.com/api/v1

Authentication

Send your key with either header on every request. Keys are meant for server-to-server use.

Authorization: Bearer yr_live_xxxxxxxx
X-API-Key: yr_live_xxxxxxxx

GET /races

A filterable race list. All parameters are optional; csv types accept several comma-separated values. When distance_min/max is given, the returned distances array is filtered down to the matching courses.

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

Response:

{
  "data": [
    {
      "id": "uuid",
      "slug": "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,
      "description_tr": "...",
      "description_en": null,
      "distances": [
        {
          "label": "Maraton",
          "distance_km": 42.195,
          "elevation_gain_m": null,
          "itra_points": null,
          "price": 1500,
          "currency": "TRY"
        }
      ],
      "registration": [
        {
          "kind": "standard",
          "opens_at": null,
          "closes_at": "2026-10-20T23:59:00+03:00",
          "price": null,
          "currency": "TRY",
          "registration_url": "https://..."
        }
      ],
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "meta": { "total": 90, "count": 25, "limit": 25, "offset": 0, "request_id": "uuid" }
}

GET /races/{slug}

A single race, with the same field structure as the list: { "data": { ... }, "meta": { "request_id": "uuid" } }. Returns 404 if not found.

JavaScript example

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()

Limits and errors

The monthly quota and the per-minute limit are per key; track what is left through the X-Quota-Remaining and X-RateLimit-Remaining response headers. Every response carries X-Request-Id for log correlation. Errors come back in this format: { "error": "kod", "request_id": "uuid" }

Licence and terms of use

Version 2026-08-05. Receiving a key counts as accepting these terms.

The data is compiled automatically from organiser and federation sources, carries a margin of error and comes with no warranty. Before entering a race, the organiser official page prevails.

Machine-readable definition

All endpoints, parameters and the response schema are published as OpenAPI 3.1 at /openapi.json . Use that file to generate a client or to plug the API into an agent.

Access key

The API works with an access key. If you want to use it, write through the contact page and we will work out a plan that fits your needs.