The REST API follows standard REST patterns.
Applications can interact with resources through HTTPS requests to specific URLs. Our REST API is designed exclusively for business-to-business (B2B) applications, and direct connections to the DDE using our data are not permitted to maintain data integrity and security.
To interact with a resource, send an HTTPS request, including the resource URL, necessary headers (such as the access token), the method, request body, and query parameters. For example:
Access resources via URLs, which vary for production (https://dde-api.data.imgarena.com) and simulation (https://dde-api-sims.data.imgarena.com) environments.
The request should specify the HTTP method, with options including:
GET for reading or listing resources
POST for creating resources
PUT for updating resources
DELETE for removing resources
Incorporate HTTP and query parameters to convey additional call details, like authorisation and data format, or for specific needs in listing operations like sorting or filtering. For instance:
API calls yield JSON objects with the requested resources or an error list. Successful responses display an HTTP 200 status code, while errors have non-200 codes.
The response for single object operations includes a JSON object with the resource type (like season or fixture).
For list and search operations, expect a named array of objects (like seasons) and a cursor value for pagination. Please always check the cursor value in these operations to make sure it's finished item retrieval.
In our REST API, each action packet is enriched by adding player and team names. If the system doesn't find a player or team linked to a particular fixture in the enrichment packet, it logs a warning. The warning message will indicate "Unknown player code: …"
or "Unknown team code: …"
based on the missing information. When this occurs, the system replaces the missing name with an empty string ("")
. This approach alerts users to any inconsistencies while preserving the structural integrity of the data packet.
Application credentials are required for production and simulation environments and cannot be shared publicly.
To utilise resources in your account, an access token from the support team is required. Obtain a Bearer authentication token by contacting the support team at datasupport@imgarena.com, necessary for connecting to the REST API endpoints. Use the token when making a connection request.
It's important to keep your access tokens private, as they are meant to be secure and confidential.
Pagination means results are divided into pages, requiring multiple requests to access all data.
Each request fetches a part of the total results, indicating the current page.
Start by requesting the first page with paged=true
in the header (default page size is 20).
Extract data from the response, then check for more pages using the pageable metadata, which shows total and current page numbers.
For additional pages, increment the page number in the query (e.g., set page=1
for the next page). Worth noting that page index starts at 0.
Combine results from all pages into one list.
Existing non-paginated requests remain functional but can be slow or truncated with large volumes.
Paginated requests (paged=true
) are faster and more reliable, limited to a specified page size (default 20).
We aim to phase out non-paginated results, focusing solely on pagination.
Pagination isn't yet supported for the Actions and Statistics APIs but will be added later.
Knowing potential error messages for efficient API integration is crucial when using public data requests.
One standard error you might encounter is related to token authentication:
Error: "Supplied token could not be authenticated."
Description: This error indicates that the authentication token must be validated or recognised.
All general error messages are formatted consistently for straightforward identification and troubleshooting. Understanding these errors enables effective handling of issues during API interactions.
Our APIs rely on rate limits to help provide a predictably pleasant experience for users.
The details of how and when rate limiting works differ between features. This article overviews the rate limits you're likely to encounter for our features and then notes how the limits apply to each feature. Although not real-time, API polling involves the repetitive transmission of client requests to an endpoint for the purpose of identifying information changes. We recommend the following frequency for your REST requests to ensure that you always have the most up-to-date information.
Feature | Limit | Notes |
---|---|---|
REST API Tier 1
Every 24 hours
Squads, All fixtures
REST API Tier 2
Every 12 hours
Seasons
REST API Tier 3
Every 60 seconds
Live fixtures
REST API Tier 4
Every 30 seconds
Live upcoming fixtures
Post-Match
Once post-match
Actions, Statistics