API
GraphQL API

GraphQL API Documentation

Introduction to GraphQL

GraphQL is a query language for your API, and a runtime for executing those queries against your data. Unlike REST, which exposes a fixed set of predefined endpoints, GraphQL allows you to request only the data you need by sending a single query. This makes it more flexible and efficient, especially when working with large or complex data sets.

Getting Started

To make queries to the Betwatch.com GraphQL API, use the endpoint api.betwatch.com/query. There is also a playground (opens in a new tab) endpoint you can use for exploring the API and testing your queries. Note that authentication is required; you must pass your API key as the X-API-KEY header in your requests.

POST https://api.betwatch.com/query
X-API-KEY: <your-api-key>

If you would like access to the API, it requires a separate subscription fee. Please email [email protected] to request access.

Example Queries

Query a Single Race

race(id: $id) {
    id
    betfairMapping {
        win
        place
    }
    meeting {
        id
        track
        location
        type
        date
    }
    name
    number
    status
    startTime
    distance
    results
    links {
        bookmaker
        navLink
    }
    runners {
        id
        number
        name
        trainerName
        riderName
        scratchedTime
        betfairMarkets {
            id
            sp
            marketName
            totalMatched
            marketTotalMatched
            back {
                price
                size
                lastUpdated
            }
            lay {
                price
                size
                lastUpdated
            }
        }
        bookmakerMarkets(bookmakers: $bookmakers, bookmakersWithFlucs: $bookmakersWithFlucs) {
            id
            bookmaker
            fixedWin {
                flucs {
                    price
                    lastUpdated
                }
                openingPrice
                price
                lastUpdated
            }
            fixedPlace {
                flucs {
                    price
                    lastUpdated
                }
                openingPrice
                price
                lastUpdated
            }
        }
    }
}

Query Multiple Races

races(dateFrom: $dateFrom, dateTo: $dateTo, andDates: $andDates) {
    id
    meeting {
        id
        location
        track
        type
        date
    }
    name
    number
    status
    distance
    startTime
    runners {
        id
        name
        number
        trainerName
        riderName
    }
}

For more information on the available query options, refer to the API reference below.

Full Example (cURL)

curl -X POST -H "Content-Type: application/json" -H "X-API-KEY: <your-api-key>" -d '{
  "query": "query ($dateFrom: String, $dateTo: String, $andDates: Boolean) {
    races(dateFrom: $dateFrom, dateTo: $dateTo, andDates: $andDates) {
      id
      meeting {
        id
        location
        track
        type
        date
      }
      name
      number
      status
      distance
      startTime
      runners {
        id
        name
        number
        trainerName
        riderName
      }
    }
  }",
  "variables": {
    "dateFrom": "2023-05-01",
    "dateTo": "2023-05-31",
    "andDates": ["2023-02-02"]
  }
}' https://api.betwatch.com/query

Full Example (Python Requests)

Although it is recommended to use the Python SDK, you can also use the Requests (opens in a new tab) (or any other) library to make requests to the API.

import requests
import json
 
url = "https://api.betwatch.com/query"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "<your-api-key>"
}
data = {
    "query": """
        query ($dateFrom: String, $dateTo: String, $andDates: [String!], $limit: Int, $offset: Int) {
            races(dateFrom: $dateFrom, dateTo: $dateTo, andDates: $andDates, limit: $limit, offset: $offset) {
                id
                meeting {
                    id
                    location
                    track
                    type
                    date
                }
                name
                number
                status
                distance
                startTime
                runners {
                    id
                    name
                    number
                    trainerName
                    riderName
                }
            }
        }
    """,
    "variables": {
        "dateFrom": "2023-05-01",
        "dateTo": "2023-05-31",
        "andDates": ["2023-02-02"],
        "limit": 10,
        "offset": 0
    }
}
 
response = requests.post(url, headers=headers, data=json.dumps(data))
 
# Access the response content
print(response.json())

Websocket subscription

If you have access to the live websocket API, you may create a durable connection that will stream price updates to you as they occur. This is useful for applications that require real-time updates. The Python SDK Subscriptions Example (opens in a new tab) shows an example of implementing this using the SDK. In order to subscribe to all price updates - you may pass an empty race id.

If connecting directly - you may use the following GraphQL query to subscribe to all price updates at the endpoint wss://api.betwatch.com/sub:

subscription PriceUpdates($id: ID!, $bookmakers: [String!]) {
    priceUpdates(id: $id, bookmakers: $bookmakers) {
        id
        bookmaker
        fixedPlace {
            price
            lastUpdated
        }
        fixedWin {
            price
            lastUpdated
        }
    }
}

You will need to initially send the API key in the connection_init message as follows:

{
    "type": "connection_init",
    "payload": {
        "apiKey": "<your-api-key>"
    }
}

Most GraphQL libraries will provide helper methods to pass this payload, such as graphql-ws for Javascript (opens in a new tab) and gql for Python (opens in a new tab). The Betwatch Python SDK handles this automatically.

For more information on how to get access to the live websocket API, please contact us at [email protected].

API Reference

The Betwatch.com GraphQL API currently supports the following two queries:

race(id: ID!): Race!

Retrieve a single race by its ID.

races(andDates: [String!], dateFrom: String, dateTo: String, hasBookmakers: [String!], hasRiders: [String!], hasRunners: [String!], hasTrainers: [String!], limit: Int, locations: [String!], offset: Int, tracks: [String!], types: [RaceType!]): [Race!]!

Retrieve a list of races based on the provided filters.

  • dateFrom is the earliest date to include in the results. The date must be in the format YYYY-MM-DD.
  • dateTo is the latest date to include in the results. The date must be in the format YYYY-MM-DD.
  • andDates is a list of additional dates to include in the results. The dates must be in the format YYYY-MM-DD.
  • hasBookmakers is a list of bookmakers to include in the results.
  • hasRiders is a list of riders to include in the results.
  • hasRunners is a list of runners to include in the results.
  • hasTrainers is a list of trainers to include in the results. A subset of the name will still match.
  • limit is the maximum number of results to return. The default is 100.
  • locations is a list of locations/states to include in the results. These will match the TAB locations.
  • offset is the number of results to skip before returning the results. The default is 0.
  • tracks is a list of tracks to include in the results.
  • types is a list of race types to include in the results. Options are Thoroughbred, Greyhound, or Harness
APIPython SDK