FAQ
Here are some frequently asked questions, so you can use our API like a pro:
Q: What technical knowledge do clients need to use your API?
A: Clients should have a basic understanding of GraphQL and how to write queries and subscriptions. However, our API is designed to be user-friendly and accessible for developers of all skill levels.
Q: How long is a token valid for?
A: A token is valid for 1 hour from time of issue.
Q: Do we have to renew a long running subscription at regular intervals?
A: No, at the time of subscription your token will be validated.
- If the token is valid your subscription will start.
- If the token is invalid your subscription will not start.
- If the subscription disconnects and your token is no longer valid, you will need to obtain a new token to restart your subscription.
- If the subscription disconnects and your token is still valid, you can restart your subscription without obtaining a new token.
Q: When I subscribe to updates (priceUpdates, raceUpdates etc.) will I receive all updates from the time the race is created?
A: No, you will only receive updates from the time that you start your subscription. To get the current state of the race, run a seperate query, then start your subscription to get further updates for that race.
Q: How do we know a subscription is alive in GraphQL?
A: In GraphQL, for subscriptions, regular heartbeats are sent in the form of {"type":"ka"} to indicate that the subscription is still alive. This is used to maintain the connection between the server and the client and ensure that the subscription remains active.
Q: I see subscriptions sometimes disconnect, why is that?
A: Subscriptions run over websockets that connect to a service running in a cluster. Issues such as cluster rebalancing, Software deployments and also network problems can cause subscriptions to be disconnected. We recommend restarting the subscription if it gets disconnected.
Q: How do I prevent missing data if a subscription has been disconnected?
A: When a subscription is disconnected, we recommend running a query to retrieve the data that was missed during the outage. This helps to ensure that your data remains up-to-date and accurate.
Q: How many simultaneous connections are allowed before throttling?
A: Subscriptions are not currently throttled. Therefore, there is no limit on the number of simultaneous connections that can be made.
Q: How often can I Query on GraphQL before throttling?
A: GraphQL queries are currently throttled at 10 per second.
Q: What is the recommended policy for retrying a connection?
A: To prevent "thundering herd" issues on our API, we advise clients to utilize a backoff policy. We recommend using the Exponential Backoff strategy with an initial delay of 10 seconds, followed by an exponential increase in delay time between each retry attempt. For instance, the delay time could be increased to 20 seconds, 40 seconds, and so on.
When retrying, we suggest that clients run a query to obtain the current state, and if successful, resubscribe. This helps to ensure that the client's connection remains stable and reduces the chances of overwhelming the server with too many requests at once.
Q: How does the API flag race cancellations?
A: The API will flag race cancellations by setting the 'status' field of both query and subscription (raceUpdated) to ‘ABANDONED’.
Q. How does the API flag start time change to races?
A: Query and subscription (raceUpdated) contain a startTime property that will change.
Q: Is there an indication if a horse is scratched/not running?
A: ScratchingType and emergencyIndicator are properties of the competitor object which should assist with runner state.
Q: What happens if a meeting has a track change?
A: If a change of tracks occurs for a meeting, the existing races will be abandoned and a new meeting with races will be created to reflect the change. The status of the races will show as ABANDONED.
Q: How do I know I have an SRM (Single Race Multi) Market?
A: SRM will only be available on meetings where you have a market in price manager, and you will be receiving generated prices if such a market is available. Please only use the SRM call when you know there is a market available. We also strongly suggest breaking the SRM query into a separate query as markets will be available at different times.
Q: How much is delay between update been received & update being integrated in state message (aka GraphQL WS message & GraphQL message)?
A: At the time of an update from our feeds, the state is stored in our database, and updates are posted to subscribed clients (web sockets). The delay between receiving an update and integrating it into the state message (GraphQL WS message and GraphQL message) is dependent on various factors such as network latency, server load, and the complexity of the update. Therefore, we cannot provide an exact duration for the delay.
Q: Do you plan to upgrade to the newer graphql-transport-ws standard? Would it be advisable to set up our integration to handle both protocols?
A: At this time, we do not currently support the graphql-transport-ws standard. However, in the event that we implement it, we will notify our clients and ensure that backward compatibility is maintained. It may be advisable to set up your integration to handle both protocols in case of any future updates or changes to our API.
Q: How can we get Starting Price and Top Fluc in CoreAPI feed? In GBS feed, they're being pushed as one type of results with source RacingServices10.
A: To retrieve Starting Price and Top Fluc in the CoreAPI feed, you can query or set up a subscription using the source OP.
Here is an example GraphQL query to retrieve this information:
results(sources: ["OP"]) {
positions {
position
tabNo
}
dividends {
type
dividend
dividendCombinations
dividendNumbers
}
}
This query will return the positions and dividends for the specified sources, including Starting Price and Top Fluc.
Q. What units are distance in?
A. Meters.
Q: How do we handle Dead Heats for results (tie)?
A: In the event of a Dead Heat in our results, duplicate tab numbers will appear under multiple different positions. To handle this, you should take the highest position when this occurs on the TabNo.
Here is an example of the data structure for a Dead Heat in our results where TabNo 1 & 3 finished 1st:
"positions": [
{
"position": 1,
"tabNo": 1
},
{
"position": 1,
"tabNo": 3
},
{
"position": 2,
"tabNo": 1
},
{
"position": 2,
"tabNo": 3
},
{
"position": 3,
"tabNo": 8
},
{
"position": 4,
"tabNo": 5
}
]
Q: Why can I not see all races in the Races query?
A: The races query is limited to 10 races by default, you can change this by modifying the limit parameter on the query filters.
Q: Is there a date limit on the MeetingsDated query?
A: the MeetingsDated query is limited to 5 days.
Q: Why am I getting 429 errors on GraphQL?
A: The meetingsDated query can be an intensive call, largely depending on what you are requesting. We recommend making intensive field calls on a lower level, such as race query. Below are specific fields that will cause 429 errors if included in a MeetingsDated query:
Race > CommentsRace > Competitor > CommentsRace > Competitor > FormHistoryRace > Competitor > JockeyStatisticsRace > Competitor > RatingRace > Competitor > PerformanceRatingsRace > Competitor > RunnerStatistics