API Documentation

Technical reference for version 3.0 endpoints.

Global Configuration

Base URL https://api.racinggreyhounds.org/v3/

Format JSON

Timestamps Unix Epoch Seconds (UTC)

Region GB (UK Racing Only)

1. Index 2. Upcoming Races 3. Latest Races 4. Picks 5. Dogs 6. Owners 7. Trainers 8. Tracks

1. API Index

GET /v3/

Returns a live directory of all publicly available API endpoints. This allows consumers to dynamically discover services without hard-coding routes.

Response Example

{
  "data": {
    "timestamp": 1700000000,
    "endpoints": [
      { "name": "latest-races", "path": "/api/v3/latest-races" },
      { "name": "upcoming-races", "path": "/api/v3/upcoming-races" },
      { "name": "picks", "path": "/api/v3/picks" }
    ]
  }
}

2. Upcoming Races

GET /v3/upcoming-races

Returns all scheduled races for today or tomorrow, including full runner cards. Runners are always ordered by trap number.

Parameter	Type	Default	Description
when	string	today	'today' (00:00-23:59) or 'tomorrow'
limit	integer	10	Number of races per page
page	integer	1	Pagination offset

Response Example

{
  "data": {
    "when": "today",
    "time_from": 1700006400,
    "races": [
      {
        "race_id": 123456,
        "track_name": "Hove",
        "race_class": "A3",
        "race_time": "18:42",
        "runners": [
          {
            "trap_number": 1,
            "dog_name": "Swift Rocket",
            "dog_sex": "M",
            "position": null
          }
        ]
      }
    ]
  }
}

Note: 'position' is null for upcoming races.

3. Latest Races (Completed)

GET /v3/latest-races

Returns historical races already run, newest first, with full result cards.

Parameter	Type	Default	Description
limit	integer	10	Number of races per page
page	integer	1	Pagination offset

Response Fragment

"runners": [
  {
    "trap_number": 1,
    "dog_name": "Swift Rocket",
    "position": 1  // Populated for completed races
  }
]

4. Picks (Model Selections)

GET /v3/picks

Returns model-generated selections for today only. This endpoint is forward-looking and designed for automated decision-making. Ranking values are relative to the specific race (1 = Best).

Response Example

{
  "race_id": 123456,
  "pick_1": 3,  // Trap Number
  "pick_2": 1,
  "strongest_trap": 3,
  "runners": [
    {
      "trap_number": 3,
      "dog_name": "Rapid Jet",
      "score_rank": 1,
      "form_rank": 2,
      "sectional_rank": 1
    }
  ]
}

5. Dogs

GET /v3/dogs

Provides dog profiles with pedigree and their last 3 race runs.

Parameter	Type	Description
name	string	Exact lookup. If omitted, returns recent dogs list.
limit	integer	Default 10.

Response Example

{
  "dog_id": 12345,
  "dog_name": "Flying Hawk",
  "dog_sire": "Droopys Jet",
  "last_3_races": [
    {
      "track_name": "Romford",
      "trap_number": 4,
      "position": 2,
      "run_time": 24.89
    }
  ]
}

6. Owners

GET /v3/owners

Lists owners ordered by most recent activity, including all dogs currently or historically owned.

Response Example

{
  "owner_name": "P Green",
  "last_race_id": 456789,
  "dogs": [
    { "dog_id": 1122, "dog_name": "Fast Echo" }
  ]
}

7. Trainers

GET /v3/trainers

Returns trainers ordered by latest race involvement.

Response Example

{
  "trainer_name": "M Hennessy",
  "last_race_id": 654321,
  "dogs": [
    { "dog_id": 9988, "dog_name": "Track Star" }
  ]
}

8. Tracks

GET /v3/tracks

Returns all active UK tracks that have held races in the last 90 days.

Response Example

{
  "data": {
    "tracks": [
      "Hove",
      "Romford",
      "Monmore",
      "Towcester"
    ]
  }
}