Introduction

This documentation aims to familiarize you with our comprehensive sports data API, designed to meet the diverse needs of sports enthusiasts, developers, and businesses alike. With a wide array of endpoints covering various sports, categories, tournaments, fixtures, markets, and providers, our API offers a wealth of information to power your applications, analysis, and services.

Whether you're building a sports betting platform, a sports-oriented application, or simply seeking insights for strategic decision-making, our API provides the essential data you need. From football and basketball to cricket and tennis, we cover a vast spectrum of sports, catering to a global audience with diverse interests and preferences.

Authentication

Access to the API is gated behind a secure authentication mechanism, requiring the inclusion of an access token in the header of each request. This token serves as a digital key, granting permission for users to interact with the API's endpoints and access its functionalities. Without this token, attempts to communicate with the API will be rejected.

To obtain the access token, users must first have an account created by one of our representatives. Once the account is established, the representative will generate a unique access token and securely transmit it to the user. This token acts as a credential, associating the user's identity with the permissions granted within the API ecosystem.

When making API requests, users must include the access token in the header of their HTTP requests using the Bearer Authorization scheme as follows:

Authorization: Bearer [your-access-token]

You must replace [your-access-token] with your personal API access token.

It's important for users to treat their access token with care, as it serves as their digital signature within the API ecosystem. Sharing or exposing the token could potentially compromise the security of their account and data. Users are advised to store the token securely and refrain from including it in publicly accessible code repositories or insecure communication channels.

In the event that a user suspects their access token has been compromised or misplaced, they should promptly contact our support team to revoke the token and issue a new one. This proactive approach helps mitigate security risks and ensures that only authorized individuals retain access to the API's functionalities.

Rate limiting

This API implements a rate limit policy on all its endpoints, ensuring fair usage and optimal performance for all users. Specifically, the rate limit is set to a maximum of one request per second for each endpoint. This means that any attempt to exceed this limit will result in the API returning a status code of 429.

The rate limit serves as a protective measure against abuse or excessive usage of the API resources. By restricting the number of requests allowed within a given time frame, it helps maintain system stability and prevents overload scenarios that could potentially degrade service quality for other users.

For developers integrating with the API, it's essential to be mindful of this rate limit restriction. Adhering to the one-request-per-second guideline ensures smooth and uninterrupted access to the API without triggering any rate limit violations.

The 429 status code, returned by the API when the rate limit is exceeded, serves as a clear indication to the client that their request has been temporarily rejected due to exceeding the permitted request frequency. Upon receiving this status code, the client can implement appropriate measures, such as implementing exponential backoff or adjusting request frequencies, to mitigate future rate limit violations and improve API interaction reliability.

Versioning

In our API, specifying the version is mandatory to ensure compatibility with the desired functionality. Each version of our API is represented by a distinct endpoint, enabling users to select the version that best aligns with their requirements. This approach ensures backward compatibility while accommodating new features and improvements seamlessly.

We require clients to include the desired version in their requests to ensure consistent behavior and to streamline integration efforts. Comprehensive documentation for each endpoint version is provided to facilitate smooth transitions and effective utilization of the API's capabilities.

Pagination

curl "https://api.odds.online/v1/fixtures?with=markets,statistics&page=2&page_size=200" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/fixtures?with=markets,statistics&page=2&page_size=200', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 10,
        "currentPage": 2,
        "pageSize": 200
    },
    [...]
}

This API utilizes pagination to efficiently manage and deliver large datasets. By breaking results into smaller, manageable pages, pagination improves response times and reduces resource consumption. To navigate through the data, clients can specify page numbers and page sizes as query parameters in their requests, allowing for controlled retrieval of specific subsets of the complete dataset. Users can customize the size of each page by supplying the pageSize (alternatively page_size) query parameter. Requesting different pages can be done by supplying the page query parameter. The response from each endpoint contains a pagination property which includes the page size, total pages count and current page.

Supported page sizes

Size	Description
100	Pages will contain up to 100 items each.
200	Pages will contain up to 200 items each.
500	Pages will contain up to 500 items each.
1000	Pages will contain up to 1000 items each.

V1 Endpoints

Get providers

curl "https://api.odds.online/v1/providers" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/providers', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 1,
        "currentPage": 1,
        "pageSize": 100
    },
    "providers": [
        {
            "id": 1000,
            "name": "Bet365"
        },
        {
            "id": 2000,
            "name": "Unibet"
        }
    ]
}

This endpoint returns a simple list containing the ID and name of each supported provider within our system.

HTTP Request

GET https://api.odds.online/v1/providers

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
providerId	provider_id	no	Comma separated provider IDs. When provided, only providers with the specified IDs will be returned.

Get sports

curl "https://api.odds.online/v1/sports" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/sports', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 2,
        "currentPage": 1,
        "pageSize": 100
    },
    "sports": [
        {
            "id": 44,
            "name": "Soccer"
        },
        {
            "id": 54,
            "name": "Basketball"
        },
    ]
}

This endpoint provides a concise list of supported sports in our system, featuring the ID and name of each sport.

HTTP Request

GET https://api.odds.online/v1/sports

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
sportId	sport_id	no	Comma separated sport IDs. When provided, only sports with the specified IDs will be returned.

Get categories

curl "https://api.odds.online/v1/categories" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/categories', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 5,
        "currentPage": 1,
        "pageSize": 100
    },
    "categories": [
        {
            "id": 1,
            "sportId": 44,
            "name": "Bulgaria"
        },
        {
            "id": 2,
            "sportId": 44,
            "name": "Romania"
        }
    ]
}

This endpoint provides a list of supported categories, including their ID, name, and associated sport ID. Users can filter results by supplying a specific sport, or category ID.

HTTP Request

GET https://api.odds.online/v1/categories

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
categoryId	category_id	no	Comma separated category IDs. When provided, only categories with the specified IDs will be returned.
sportId	sport_id	no	Comma separated sport IDs. When provided, only categories related to the specified sports will be returned.

Get tournaments

curl "https://api.odds.online/v1/tournaments" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/tournaments', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 10,
        "currentPage": 1,
        "pageSize": 100
    },
    "tournaments": [
        {
            "id": 1,
            "categoryId": 1,
            "sportId": 44,
            "name": "Champions League",
        },
        {
            "id": 2,
            "categoryId": 1,
            "sportId": 44,
            "name": "Premier League",
        }
    ]
}

This endpoint offers users access to essential tournament details such as ID, name, and associated category and sport ID. Users can filter results by supplying a specific tournament, category, or sport ID.

HTTP Request

GET https://api.odds.online/v1/tournaments

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
tournamentId	tournament_id	no	Comma separated tournament IDs. When provided, only tournaments with the specified IDs will be returned.
categoryId	category_id	no	Comma separated category IDs. When provided, only tournaments related to the specified categories will be returned.
sportId	sport_id	no	Comma separated sport IDs. When provided, only tournaments related to the specified sports will be returned.

Get fixtures

curl "https://api.odds.online/v1/fixtures?details=statistics,markets" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/fixtures?details=statistics,markets', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 100,
        "currentPage": 1,
        "pageSize": 100
    },
    "fixtures": [
        {
            "id": 1,
            "sportId": 44,
            "categoryId": 1,
            "tournamentId": 1,
            "periodId": 10,
            "time": 600,
            "status": "ongoing",
            "startsAt": "2024-06-05 21:00:00",
            "participants": [
                {
                    "id": 15,
                    "position": 1,
                    "statistics": [
                        {
                            "id": 1,
                            "amount": 2
                        }
                    ]
                },
                {
                    "id": 20,
                    "position": 2,
                    "statistics": [
                        {
                            "id": 1,
                            "amount": 1
                        }
                    ]
                }
            ],
            "markets": {
                "inplay": [
                    {
                        "id": 1,
                        "name": "1x2",
                        "outcomes": [
                            {
                                "id": 1,
                                "name": "Arsenal",
                                "odds": 2,
                                "status": "available"
                            },
                            {
                                "id": 2,
                                "name": "Draw",
                                "odds": 1.5,
                                "status": "available"
                            },
                            {
                                "id": 3,
                                "name": "Chelsea",
                                "odds": 1.2,
                                "status": "available"
                            }
                        ]
                    }
                ],
                "prematch": [
                    {
                        "id": 1,
                        "name": "1x2",
                        "outcomes": [
                            {
                                "id": 1,
                                "name": "Arsenal",
                                "status": "unavailable"
                            },
                            {
                                "id": 2,
                                "name": "Draw",
                                "status": "unavailable"
                            },
                            {
                                "id": 3,
                                "name": "Chelsea",
                                "status": "unavailable"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

This endpoint provides users access to the fixtures they have subscribed to through their dashboard. Users can filter results by supplying one or more filtering parameters. This endpoint can also return additional fixture details such as statistics and markets. In order to get those you must explicitly specify that you want to receive them using the details parameter (alternatively with). If no details are requested the response will not contain neither statistics nor markets properties.

HTTP Request

GET https://api.odds.online/v1/fixtures

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
fixtureId	fixture_id	no	Comma separated fixture IDs. When provided, only fixtures with the specified IDs will be returned.
tournamentId	tournament_id	no	Comma separated tournament IDs. When provided, only fixtures related to the specified tournaments will be returned.
categoryId	category_id	no	Comma separated category IDs. When provided, only fixtures related to the specified categories will be returned.
sportId	sport_id	no	Comma separated sport IDs. When provided, only fixtures related to the specified sports will be returned.
status	-	no	Comma separated statuses. When provided, only fixtures with the specified statuses will be returned.
fromDate	from_date	no	Unix timestamp. When provided, only fixtures starting from the specified date will be returned.
toDate	to_date	no	Unix timestamp. When provided, only fixtures starting up to the specified date will be returned.
details	with	no	Comma separated fixture details that will be included in the response only if explicitly specified.

Supported details

Name	Description
statistics	Includes the latests statistics for each participant.
markets	Includes inplay and prematch markets and their outcomes.

Supported statuses

Name	Description
upcoming	The fixture has not started yet (i.e. prematch).
starting	The fixture is about to start.
ongoing	The fixture is currently being played (i.e. inplay).
coverage.lost	We have lost fixture coverage.
postponed	The fixture was postponed.
canceled	The fixture was canceled.
finished	The fixture finished and will be removed soon.

Get participants

curl "https://api.odds.online/v1/participants" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/participants', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 200,
        "currentPage": 1,
        "pageSize": 100
    },
    "participants": [
        {
            "id": 1,
            "sportId": 44,
            "name": "Arsenal"
        },
        {
            "id": 2,
            "sportId": 44,
            "name": "Real Madrid"
        }
    ]
}

This endpoint provides a list of supported participants, including their ID, name, and associated sport ID. Users can filter results by supplying a specific sport, or participant ID.

HTTP Request

GET https://api.odds.online/v1/participants

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
participantId	participant_id	no	Comma separated participant IDs. When provided, only participants with the specified IDs will be returned.
sportId	sport_id	no	Comma separated sport IDs. When provided, only participants related to the specified sports will be returned.

Get periods

curl "https://api.odds.online/v1/periods" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/periods', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 3,
        "currentPage": 1,
        "pageSize": 100
    },
    "periods": [
        {
            "id": 1,
            "sportId": 2,
            "name": "Quarter 1",
            "property": "quarters.1st"
        },
        {
            "id": 2,
            "sportId": 2,
            "name": "Quarter 2",
            "property": "quarters.2nd"
        },
        {
            "id": 3,
            "sportId": 2,
            "name": "HT",
            "property": "halftime"
        },
        {
            "id": 4,
            "sportId": 2,
            "name": "Quarter 3",
            "property": "quarters.3rd"
        },
        {
            "id": 5,
            "sportId": 2,
            "name": "Quarter 4",
            "property": "quarters.4th"
        }
    ]
}

This endpoint provides a list of supported periods, including their ID, name, property, and associated sport ID. Users can filter results by supplying a specific sport, or period ID.

HTTP Request

GET https://api.odds.online/v1/periods

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
periodId	period_id	no	Comma separated period IDs. When provided, only periods with the specified IDs will be returned.
sportId	sport_id	no	Comma separated sport IDs. When provided, only periods related to the specified sports will be returned.

Get statistics

curl "https://api.odds.online/v1/statistics" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/statistics', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 5,
        "currentPage": 1,
        "pageSize": 100
    },
    "statistics": [
        {
            "id": 1,
            "sportId": 44,
            "name": "Score",
            "property": "score.total",
            "position": 1
        },
        {
            "id": 2,
            "sportId": 44,
            "name": "Corners",
            "property": "corners.total",
            "position": 2
        }
    ]
}

This endpoint provides a list of supported statistics, including their ID, name, property, position and associated sport ID. Users can filter results by supplying a specific sport, or statistic ID.

HTTP Request

GET https://api.odds.online/v1/statistics

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
statisticId	statistic_id	no	Comma separated statistic IDs. When provided, only statistics with the specified IDs will be returned.
sportId	sport_id	no	Comma separated sport IDs. When provided, only statistics related to the specified sports will be returned.

Get structures

curl "https://api.odds.online/v1/structures" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/structures', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 1,
        "currentPage": 1,
        "pageSize": 100
    },
    "structures": [
        {
            "id": 4,
            "name": "1X2",
            "property": "participant1_draw_participant2",
            "outcomes": [
                {
                    "id": 1,
                    "name": "{{$participant1}}",
                    "position": 1
                },
                {
                    "id": 5,
                    "name": "Draw",
                    "position": 2
                },
                {
                    "id": 2,
                    "name": "{{$participant2}}",
                    "position": 3
                }
            ]
        }
    ]
}

This endpoint provides a list of supported market structures, including their ID, name, property, and outcomes. Users can filter results by supplying a specific structure ID.

HTTP Request

GET https://api.odds.online/v1/structures

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
structureId	structure_id	no	Comma separated structure IDs. When provided, only structures with the specified IDs will be returned.

Get markets

curl "https://api.odds.online/v1/markets" \
  -H "Authorization: Bearer [your-access-token]"

await fetch('https://api.odds.online/v1/markets', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer [your-access-token]'
  }
});

{
    "pagination": {
        "totalPages": 5,
        "currentPage": 1,
        "pageSize": 100
    },
    "markets": [
        {
            "id": 1,
            "sportId": 44,
            "structureId": 1,
            "position": 1
        },
        {
            "id": 2,
            "sportId": 44,
            "structureId": 2,
            "position": 2
        }
    ]
}

This endpoint provides a list of supported markets, including their ID, name, associated sport, as well as its structure. Users can filter results by supplying a specific sport, market, or structure ID.

HTTP Request

GET https://api.odds.online/v1/markets

Headers

Name	Required	Description
Authorization	yes	Bearer scheme access token.

Query Parameters

Name	Alternative	Required	Description
marketId	market_id	no	Comma separated market IDs. When provided, only markets with the specified IDs will be returned.
sportId	sport_id	no	Comma separated sport IDs. When provided, only markets for the specified sports will be returned.
structureId	structure_id	no	Comma separated structure IDs. When provided, only markets with the specified structures will be returned.

Errors

This API relies on standard HTTP response codes to communicate the outcome of each request made to it. Generally, response codes falling within the 2xx range signify successful operations. If you encounter a response code in the 4xx range, it typically indicates an error stemming from incorrect query parameters or headers provided with the request. On the other hand, response codes in the 5xx range signify errors that are internal to the server and not caused by the client.

Error Code	Description
400	Bad Request: Your request is invalid.
401	Unauthorized: Your API key is wrong.
404	Not Found: The specified resource could not be found.
405	Method Not Allowed: You tried to access a resource with an invalid method.
429	Too Many Requests: You're sending too many requests! Slow down!
500	Internal Server Error: We had a problem with our server. Try again later.
503	Service Unavailable: We're temporarily offline for maintenance. Please try again later.