The following section covers our upcoming approach on pagination. Please read carefully as this will impact your implementation.
As we expand upon our Official Data Coverage across sports at IMG, we want our REST APIs to be as efficient and functional as they can be and as a result, we will be supporting pagination within our Seasons, Fixtures and Squads REST API. When you have a paginated API, it means that the results are split into separate pages, and users need to make multiple requests to get all the results. Each request retrieves a portion of the total results, and includes information about which page of results is being returned.
To consume this type of API and iterate over all the results, you can use a loop to make requests for each page of results. You start by making a request for the first page of results, and extract the data from that page. Then, you check to see if there are more pages of results to fetch. If there are, you make another request for the next page of results and repeat the process until you have retrieved all the results.
Once you have retrieved all the results, you can use them however you like, such as displaying them on a webpage or performing some sort of analysis on them.
From a technical point of view, here is a step by step guide
Make an initial request to the API to get the first page of results using paged=true in the header (the default page return will be 20). For best results, please be sensible when using the page size parameter
Extract the results from the response, and check if there are more pages to fetch. This can be done by checking the pageable metadata in the response, which includes the total number of pages and the current page number.
If there are more pages to fetch, make subsequent requests to the API by incrementing the page number in the query parameters. For example, to fetch the next page, set page=1. Worth noting that page index starts at 0.
Concatenate the results from all the pages into a single list.
Important Info and benefits:
The default view come May 2024 will now be paged results by default as per comms in April 2024
If you run your requests with the header paged=true; you get a subset of your results, restricted to the number of entries of a page (default: 20, but you can choose in the request). Benefit here is that it is faster and reliable.
The endgame for IMGA is to get rid of the current method and return paginated results. Once the switch is done – the header value will be ignored, we’ll just be returning pages.
From the end of 2023 (given there are only 2 matches on that day finishing at ~03:00), we are aiming to get all users migrated over to using paged=true and the current way will no longer be supported.
At present, pagination is not supported within the /actions or /statistics (not applicable), https REST API calls but we will work towards adding that to /actions and communicate in due course.
The API client needs to request a Bearer authentication token from the support team at support@openbet.com to connect to WebSockets endpoints. The token should be used immediately after a connection request. Once a connection to a WebSockets API message is established, the token remains valid indefinitely.
Do not reveal your access tokens publicly - they are secret!
When making public data requests, you may encounter the following error messages. It's important to familiarize yourself with these potential errors to ensure smooth and effective integration with our API.
Supplied token could not be authenticated: Description: This error message indicates that the token provided for authentication could not be verified. Example payload:
Please note that general error messages follow a consistent structure to facilitate easy identification and troubleshooting.
By understanding these error messages, you can effectively handle and address any issues that may arise during your API calls. If you have further questions or require assistance, please don't hesitate to reach out to our support team.
This comprehensive guide provides information on our consumer-facing APIs and WebSockets, enabling seamless connections between our clients and us.
To start, you can head to the following few sections. It offers a step-by-step walkthrough on utilising our REST APIs and WebSocket endpoints. You'll find detailed query parameter explanations, payload examples, responses, and various action types.
If you encounter any issues or require assistance, our dedicated support team is here to help. Feel free to reach out to them at support@openbet.com. We're committed to ensuring a smooth and successful experience for you.
Once again, welcome to the technical documentation, and we look forward to assisting you on your journey!
The REST API follows standard REST patterns.
Applications can manage resources (seasons, fixtures, and player items) through HTTPS requests to corresponding URLs. For details on resources and operations, see the API Reference.
Authentication: To access resources in your account, use an access token provided by the support team. Application credentials are required for production and simulation environments and cannot be shared publicly.
Our REST API and WebSocket endpoints are only tailored for B2B use. Using our data to connect directly with the DDE is prohibited. This helps ensure data integrity and security. If you have integration needs, we can discuss proceeding within our guidelines. Please feel free to reach out with any questions to support@openbet.com.
Making API Calls: To perform operations on a resource, send an HTTPS request with the resource URL, appropriate headers (including the access token), method, request body, and query parameters.
Example cURL command:
Resource URL: Access resources using their URLs, which differ for production and simulation environments. For Production: https://dde-api.data.imgarena.com, and for Simulation: https://dde-api-sims.data.imgarena.com.
HTTP Methods: Specify the HTTP method in the request for actions on resources:
GET: Read or list resources
POST: Create resources
PUT: Update resources
DELETE: Delete resources
Headers and query parameters: Use HTTP headers and query parameters to provide additional information about the call, such as authorization and data format or for sorting, filtering, or paging in list operations. For example:. For example:
Response Handling: API calls return JSON objects with requested resources or an errors list. Success responses have an HTTP 200 status code, while errors have non-200 status codes.
For operations on a single object, the response contains a JSON object with the type of resource (e.g., season, fixture).
For list and search operations, the response includes a named array of objects (e.g., seasons) and a cursor value for pagination.
Ensure to check for the cursor value in list and search operations to retrieve all items.
For more information on handling errors, refer to the documentation on error handling.
In our REST API, every action packet undergoes an enrichment process where the player and team names are appended. However, our system will log a warning if the player or team associated with a specific fixture is not found within the enrichment packet. The warning will either state "Unknown player code: …" or "Unknown team code: …" depending on the missing element. In such cases, the system will substitute an empty string ("") instead of the actual name. This ensures that users are alerted to any discrepancies while maintaining the integrity of the data packet structure.
The WebSocket API provides a powerful technology for establishing two-way interactive communication between users and the FastPath server.
It enables real-time sports betting and media data updates and eliminates the need for polling the server for responses. WebSockets utilize a bidirectional protocol, offering the fastest real-time data transmission for building real-time sports betting and media applications. The following message types require authentication, and data availability depends on the user's subscription license.
Messages sent and received via WebSockets are encoded in JSON format.
Decimal fields, including timestamps, are quoted to preserve precision.
At least one message should be subscribed to in order to maintain an authenticated client connection.
Use the Fixtures REST API endpoints to fetch the list of fixtures that can be subscribed via the WebSockets API. The 'id' field provides the supported fixture ID for subscription.
Our REST API and WebSocket endpoints are only tailored for B2B use. Using our data to connect directly with the DDE is prohibited. This helps ensure data integrity and security. If you have integration needs, we can discuss proceeding within our guidelines. Please feel free to reach out with any questions to support@openbet.com.
Authentication Refer to the Access Tokens documentation for detailed information.
Sequence Numbers FastPath feeds include sequence numbers ("fixtureSeqNum") in their messages. These numbers are monotonically increasing integers starting from 1 and operate on a per-connection and per-feed basis. They help clients identify if they are dropping messages, receiving messages out of order, or processing messages differently from the server's order.
Connection Status WebSockets enable real-time communication between clients and servers. However, disconnections can occur due to various reasons such as network issues, server unavailability, or client-side errors. The URL for the production environment is
wss://dde-streams.data.imgarena.com.
When a WebSocket connection is disconnected, sending and receiving messages from the server becomes impossible. To handle this, a mechanism is implemented to detect and manage disconnections. This includes using heartbeats to detect disconnections, implementing automatic reconnection, and displaying warning messages to the user.
If there are any connection issues with the data collection network, IMG sends connection status packets in WebSocket feeds to indicate that the upstream provider is not sending data. These packets do not contain sequence numbers. Here is a sample format of the expected status packet:
Connected
Disconnected
Valid state values are:
Connected
Disconnected
The Connected status is sent when a packet is received and the previous state was Disconnected. The status change is delivered before the packet.
The Disconnected status is sent if no packets (including heartbeats) have been received for a known feed. A feed is considered known if any data has been received from it, including heartbeats. The system checks for feed disconnection every 10 seconds and marks it as Disconnected if no data has been received within the last 30 seconds. We also added a lastConnectedTimestamp to the /actions websocket in May 2024 which will reference the last timestamp of an action (goal, card, subs, corner etc), or a heartbeat message prior to a disconnection. This will help users understand the time of the last packet during the period of connectivity. This will be tagged on the Disconnected ConnectionStateChangedmessages.
If a packet is received at 5 seconds and no further packets are received, the feed will be marked as disconnected at 40 seconds. This is the first 10-second interval in which at least 30 seconds have passed since receiving the packet.
Note that connection statuses are deduplicated to avoid sending redundant ConnectionStateChanged events unless the new state is different from the previous state.
During a suspension, the collection status is updated manually by the supervisor when the scorer goes offline. However, the scorer continues to collect data locally, which is sent to the server upon reconnection. Users will receive all missing actions upon the scorer's reconnection.
For more information on error handling, please refer to the .