Sports API
sports.api.decathlon.com provides an API that provides a collection of micro services pertaining to sport intelligence as well as data and content related to sports.
Getting started
Sport Data Structure
{
"id": 66,
"type": "sport",
"attributes": {
"name": "Skiing",
"description": "On your skis, these longs and narrows kinds of skates, you can practice several disciplines that will transport you, for fun or during competitions, in the heart of the most beautiful winter landscapes. You’ll be able to ride down the hills at a fast pace and execute controlled turns, allowing you to take fresh air and strengthen your cardiovascular system. Have a fun ride!",
"parent_id": null,
"decathlon_id": 66,
"slug": "skiing",
"locale": "en",
"weather": []
},
"relationships": {
"children": {
"data": [
{
"id": 67,
"type": "sport"
},
{
"id": 785,
"type": "sport"
},
{
"id": 786,
"type": "sport"
},
{
"id": 787,
"type": "sport"
},
{
"id": 788,
"type": "sport"
},
{
"id": 789,
"type": "sport"
},
{
"id": 790,
"type": "sport"
},
{
"id": 791,
"type": "sport"
},
{
"id": 792,
"type": "sport"
},
{
"id": 68,
"type": "sport"
}
]
},
"parent": {
"data": null
},
"group": {
"data": {
"id": 22,
"type": "group"
}
},
"related": {
"data": [
{
"id": 156,
"type": "sport"
},
{
"id": 328,
"type": "sport"
},
{
"id": 70,
"type": "sport"
}
]
},
"tags": {
"data": [
"downhill-skiing",
"extreme-skiing",
"giant-slalom",
"glade-skiing",
"grass-skiing",
"skiing-on-grass",
"para-alpine-skiing",
"slalom",
"speed-skiing",
"super-g",
"skis",
"descent",
"ski-station",
"ski-slope",
"glading"
]
},
"images": {
"data": [
{
"id": 170,
"url": "https://sports.api.decathlon.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBYW89IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--150627d59a77c19909396ed9ee88146eb35f2f26/ski.jpg",
"meta": {
"width": 500,
"height": 333
},
"variants": [
{
"thumbnail": {
"url": "https://sports.api.decathlon.com/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBYW89IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--150627d59a77c19909396ed9ee88146eb35f2f26/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9MY21WemFYcGxTU0lJTWpBd0Jqb0dSVlE9IiwiZXhwIjpudWxsLCJwdXIiOiJ2YXJpYXRpb24ifX0=--8ed889d31ac3a5e9d5446846a4f7747f8eaa0bc1/ski.jpg"
},
"medium": {
"url": "https://sports.api.decathlon.com/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBYW89IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--150627d59a77c19909396ed9ee88146eb35f2f26/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9MY21WemFYcGxTU0lKTVRBeU5BWTZCa1ZVIiwiZXhwIjpudWxsLCJwdXIiOiJ2YXJpYXRpb24ifX0=--0e36b4a54e8a5057a18945f67d3ad11a9ef22382/ski.jpg"
}
}
]
}
]
}
}
}
1. Sign up as an API User to receive important communications.
To keep our Users aware of the developement, we will want to make sure we can inform you about amazing upgrades or important changes.
Sign up by filling this form: https://mailchi.mp/decathlon/sportsintelligenceapi
2. Familiarize yourself with our features, sport data structure and the concept of source :
Features
Resourceful list of sports
- Aliases, descriptions, images, relationships, (...) for most sports
Intelligent Sports Search
- Sport attributes indexed and searchable
Combined location and application based sports recommendations
- Geolocalized sport popularity and data driven application specific recommendations
Sports practice similarities matrix
- Relationships between sports based on how similar they are to one another
Data structure
Notable details:
- sports with a parent_id: null are considered parent sports. They are often considered more important sports in term of their historical and popularity relevance.
- Sports with a parent_id: :id, are children of those sports. By children we imply sports who's practice and rules were influenced by their parent.
- Nested inside relationships is the related node where you will find sports which are similar to the current sport. The first sport in the list being the most similar.
Data Sources
Most of the intelligence in the sports API comes from studying and analyzing vast amounts of data. Our artifical intelligence team has created models which can be applied to different data sets. By being able to choose which data set we are sourcing our intelligence from, we can offer results that are better tailored to your application.
| Source | Description |
|---|---|
Popular |
The default source and most complex one. It's based on a machine learning algorithm that will adjust itself based on the quality of the available data near the specified coordinates. Example: Near calgary, we have very litlle sports places data, but we have a lot of events then the popular source will give more weight to the events when calculating the popularity. |
Activites |
Data sourced from the Decathlon activities API |
places |
Data sourced from the Decahtlon sport places API |
decathlon |
Data sourced from the traffic on the Decathlon united websites. (coverage) |
3. Make your first API Call!
You are ready to go! We suggest making your first API call by querying for popular sports recommendations near you
Authentication
No authentication is required. The API is fully OPEN and will stay as such. Keep in mind that a throttle will eventually be imposed on users that have not registered for an key.
API Reference
List of sports
curl "https://sports.api.decathlon.com/sports"
JSON response:
{
"data": [
{
"id": "224",
"type": "sport",
"attributes": {
"name": "Swimming",
"description": null,
"parent_id": null,
"decathlon_id": 224,
"slug": "swimming",
"locale": "en",
"weather": []
},
"relationships": {
"tags": {
"data": [
"bathing",
"swimming-pool",
"triathlon",
"crawl",
"breaststroke",
"butterfly",
"backstroke",
"freestyle",
"open-water-swimming",
"marathon-swimming",
"synchronized-swimming",
"paralympic-swimming",
"aqualearning",
"competitive-swimming"
]
},
"children": {
"data": [
{
"id": "331",
"type": "sport"
},
//...
]
},
//...
},
//...
},
{
"id": "291",
"type": "sport",
"attributes": {
"name": "Body Building / Cross Training",
"description": null,
"parent_id": 486,
"slug": "body-building-cross-training",
"locale": "en"
},
"relationships": {
"parent": {
"data": {
"id": "486",
"type": "sport"
},
//...
}
},
//...
},
//...
]
}
This endpoint returns a detailled collection of all the sports in our database.
HTTP Request
GET https://sports.api.decathlon.com/sports
Request Parameters
| Parameter | Example | Description |
|---|---|---|
| tag | 'race' |
Filter out sports not containing the tag. |
| parents_only | true |
Filter out sports that are not considered parent sports. |
| has_icon | true |
Filter out sports which do not have an associated icon. |
| has_decahtlon_id | true |
Decathlon specific logic: Filter out sports that are not matched to a masterdata sport. |
Querying a single Sport
curl "https://sports.api.decathlon.com/sports/224"
JSON Response
{
"data": {
"id": "224",
"type": "sport",
"attributes": {
"name": "Swimming",
"description": null,
"parent_id": null,
"slug": "swimming",
"locale": "en",
"weather": [ ],
"icon": "https://sports-api-production.s3.amazonaws.com/uploads/sport/icon/224/224.svg"
},
"relationships": {
"children": {
"data": [
{
"id": "331",
"type": "sport"
},
{
"id": "219",
"type": "sport"
},
//...
]
},
//...
}
}
}
This endpoint retrieves a single sport.
The ID parameter can be passed in as a slug or id for convenience.
HTTP Request
GET https://sports.api.decathlon.com/sports/:id
Request Parameters
The only accepted (and required) parameter for this endpoint is the sport id or slug
Intelligent Search
curl "https://sports.api.decathlon.com/sports/search/water?coordinates=-73.5826985,45.5119864"
JSON response:
[
{
"id": 224,
"type": "sport",
"attributes": {
"name": "Swimming",
"description": "Swimming includes several sports that are practiced on the surface and/or under the water. It allows you to use your whole body to move, sometimes in speed trials, sometimes in artistic routines, but requiring at all times a great coordination. Above all, thanks to the effect of gravity, swimming helps to minimize the impact of force on your body and joints, in addition to being a complete and very accessible sport that can easily allow you to feel like a fish in the water!\n",
"parent_id": null,
"decathlon_id": 224,
"slug": "swimming",
"locale": "en",
"weather": []
},
"relationships": {
"children": {
"data": [
{
"id": 331,
"type": "sport"
},
{
"id": 385,
"type": "sport"
},
{
"id": 406,
"type": "sport"
},
{
"id": 228,
"type": "sport"
},
{
"id": 500,
"type": "sport"
},
{
"id": 501,
"type": "sport"
}
]
},
"parent": {
"data": null
},
"group": {
"data": {
"id": 1,
"type": "group"
}
},
"related": {
"data": [
{
"id": 219,
"type": "sport"
},
{
"id": 405,
"type": "sport"
},
{
"id": 12,
"type": "sport"
}
]
},
"tags": {
"data": [
"bathing",
"swimming-pool",
"triathlon",
"crawl",
"breaststroke",
"butterfly",
"backstroke",
"freestyle",
"open-water-swimming",
"marathon-swimming",
"synchronized-swimming",
"paralympic-swimming",
"aqualearning",
"competitive-swimming"
]
},
"images": {
"data": [
{
"id": 204,
"url": "https://sports.api.decathlon.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBY3c9IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--cb60fb5bcf08e4676adace5cf677d12196bafe55/swimming.jpg",
"meta": {
"width": 500,
"height": 333
},
"variants": [
{
"thumbnail": {
"url": "https://sports.api.decathlon.com/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBY3c9IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--cb60fb5bcf08e4676adace5cf677d12196bafe55/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9MY21WemFYcGxTU0lJTWpBd0Jqb0dSVlE9IiwiZXhwIjpudWxsLCJwdXIiOiJ2YXJpYXRpb24ifX0=--8ed889d31ac3a5e9d5446846a4f7747f8eaa0bc1/swimming.jpg"
},
"medium": {
"url": "https://sports.api.decathlon.com/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBY3c9IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--cb60fb5bcf08e4676adace5cf677d12196bafe55/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9MY21WemFYcGxTU0lKTVRBeU5BWTZCa1ZVIiwiZXhwIjpudWxsLCJwdXIiOiJ2YXJpYXRpb24ifX0=--0e36b4a54e8a5057a18945f67d3ad11a9ef22382/swimming.jpg"
}
}
]
}
]
}
}
},
{
"id": 219,
"type": "sport",
"attributes": {
"name": "Aquafit",
//...
},
}
]
Given coordinates and a search query: the endpoint will return you with a list of relevant sports by searching through: synonyms, lexical champ, tags and descriptions.
Assuring location and application relevance: Prior to being returned, the results will be reindexed based on the popularity of the sports in the vicinity of the given coordinates. If a source is provided, the popularity attributed to each sport will be influenced by the specified dataset.
Example: https://sports.api.decathlon.com/sports/search/water?source=activities&coordinates=-73.123,45.123, will return water sports and the results in the query will be sorted by how often these sports have activities listed for them near the coordinates.
HTTP Request
GET https://sports.api.decathlon.com/sportssearch/:query?coordinates=:coordinates"
Request Parameters
The only required parameter for this endpoint is the :coordinates.
| Parameter | Example | Description |
|---|---|---|
| query | 'water' |
Filter sports by their relevance to your query. |
| coordinates | -73.5826985,45.5119864 |
(longitude, latitude) Sport popularity is geolocalized. |
| source | popular |
Influence popularity re-indexing by application: popular, decathlon, activities, places, events (default: popular) |
| has_icon | true |
Filter out sports without an associated icon. |
| parents_only | true |
Filter out sports that are not considered parent sports. |
| strict | true |
If true, will perform a search for sport who's name contains the exact query |
| has_decathlon_id | true |
Decathlon specific logic: Filter out sports that are not matched to a masterdata sport. |
Showcase
To easily explore the various parameters, we built a showcase
Location based recommendations
curl
"https://sports.api.decathlon.com/sports/recommendations/geolocation?coordinates=-73.582,45.511"
JSON Response
[
{
"id": 224,
"type": "sport",
"attributes": {
"name": "Swimming",
"description": "Swimming includes several sports that are practiced on the surface and/or under the water. It allows you to use your whole body to move, sometimes in speed trials, sometimes in artistic routines, but requiring at all times a great coordination. Above all, thanks to the effect of gravity, swimming helps to minimize the impact of force on your body and joints, in addition to being a complete and very accessible sport that can easily allow you to feel like a fish in the water!\n",
"parent_id": null,
"decathlon_id": 224,
"slug": "swimming",
"locale": "en",
"weather": []
},
//...
},
{
"id": 219,
"type": "sport",
"attributes": {
"name": "Aquafit",
//...
},
}
]
From the coordinates, it'll find the nearest city with valid contextual data and return the most popular sports for your desired application.
HTTP Request
GET https://sports.api.decathlon.com/sports/recommendations/geolocation?coordinates=:coordinates"
Request Parameters
The only required parameter for this endpoint is the :coordinates.
| Parameter | Example | Description |
|---|---|---|
| coordinates | -73.5826985,45.5119864 |
(longitude, latitude) Sport popularity is geolocalized. |
| source | popular |
Influence popularity indexing by application: popular, decathlon, activities, places, events (default: popular) |
| has_icon | true |
Filter out sports without an associated icon. |
| parents_only | true |
Filter out sports that are not considered parent sports. |
Listing Sport Groups
curl "https://sports.api.decathlon.com/groups"
JSON response:
{
"data": [
{
"id": 1,
"type": "group",
"attributes": {
"name": "Water Aerobics",
"slug": "water-aerobics",
"locale": "en"
},
"relationships": {
"sports": {
"data": [
{
"id": 484,
"type": "sport"
},
{
"id": 331,
"type": "sport"
},
{
"id": 219,
"type": "sport"
},
// ...
]
}
}
},
{
"id": 2,
"type": "group",
"attributes": {
"name": "Athletics",
"slug": "athletics",
"locale": "en"
},
"relationships": {
"sports": {
"data": [
{
"id": 257,
"type": "sport"
},
{
"id": 390,
"type": "sport"
},
// ...
]
}
}
},
]
This endpoint retrieves all sport groups and allows users to have a bird's eye view on how our sports are organized and related to one another.
HTTP Request
GET https://sports.api.decathlon.com/groups
Request Parameters
This endpoint accepts no parameters.
Querying a single group
curl "https://sports.api.decathlon.com/groups/water-aerobics"
JSON Response
{
"data": {
"id": 1,
"type": "group",
"attributes": {
"name": "Water Aerobics",
"slug": "water-aerobics",
"locale": "en"
},
"relationships": {
"sports": {
"data": [
{
"id": 484,
"type": "sport"
},
{
"id": 224,
"type": "sport"
},
{
"id": 331,
"type": "sport"
},
{
"id": 385,
"type": "sport"
},
{
"id": 406,
"type": "sport"
},
{
"id": 228,
"type": "sport"
},
{
"id": 405,
"type": "sport"
},
{
"id": 221,
"type": "sport"
},
{
"id": 500,
"type": "sport"
},
{
"id": 501,
"type": "sport"
},
{
"id": 502,
"type": "sport"
},
{
"id": 503,
"type": "sport"
},
{
"id": 504,
"type": "sport"
},
{
"id": 505,
"type": "sport"
},
{
"id": 506,
"type": "sport"
},
{
"id": 219,
"type": "sport"
}
]
}
}
}
}
This endpoint retrieves a group (and its children, if any).
The ID parameter can be passed in as a slug or id for convenience.
In the case a group doesn't have any children, the relationship object will return null.
HTTP Request
GET https://sports.api.decathlon.com/groups/water-aerobics
Request Parameters
Search query errors will be rescued with specific error messages, and an HTTP 404 status code.
SDKs
Ruby
A Ruby interface to Decathlon's Sports API is available as a Ruby Gem.
Installation
Add this line to your application's Gemfile:
gem 'decathlon-sports'
And then execute:
$ bundle
Or install it yourself as:
$ gem install decathlon-sports
Usage
Decathlon::Sports.all
sports = Decathlon::Sports.all(params: {}, headers: {})
Decathlon::Sports.find
sport = Decathlon::Sports.find(175)
Decathlon::Sports.find
sport = Decathlon::Sports.search('Snowboarding', params: {}, headers: {})
Decathlon::Sports::Recommendations.get
recommendations = Decathlon::Sports::Recommendations.get(175)
The
params: {}andheaders: {}arguments are optional and interchangeable.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/decathlon/sports-api-wrapper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
Specs
This API follows the JSON:API spec
i18n: Internationalization
For the moment, only english and french are supported.
Add the Accept-Language header to your request to select your language.
Example : Accept-Language: 'fr-CA'
Errors
The Sports API renders the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid - check the JSON format of your request. |
| 401 | Unauthorized -- There's a problem with your credentials. |
| 404 | Not Found -- We can't find the data you're looking for. |
| 422 | Unprocessable Entity -- There was a validation error with your request. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
F.A.Q.
How were the sports chosen?
These sports were humanly curated by Decathlon staff with data from 40+ years of field expertise.
We do plan on expanding research on this data with the help of our community, so application developers and/or data researchers can get the most out of it.
How is it supposed to help me?
The data provided here is a result of countless hours of research and our goal is to make it easy for Sport Tech startups to get ahead by quickly having access to metrics such as popularity, density, weather-based recommendations etc...
What if a sport is missing?
Our team has worked really hard to put together an inclusive list of sports, but we know that sport modalities can differ wildly from country to country. If you can't find info about a specific sport using our API, please don't hesitate in contacting us at developers@decathlon.com
*** Sports can be searched using the q parameter. E.g.: https://sports-decathlon.herokuapp.com/sports?q=soccer**
Where can I see/download the list of sports in a readable format?
As of the time of this writing, we only support JSON, but we're open to other formats as well. Please let us know if your application requires a different format.
Contributing
Everyone is encouraged to help improve this project.
Here are some ways you can contribute:
- by reporting bugs, typos and missing docs
- by suggesting new features
- by writing or editing documentation
- by writing specifications
- by writing code ( no patch is too small : fix typos, add comments, clean up inconsistent whitespace )
- by refactoring sample code
Submit your contribution
URL: https://developers-decathlon.canny.io/sports-api
Submitting a Pull Request
- Fork/Clone the Repository
- Create a [new-feature] branch
- Implement your feature or bug fix.
- Add, commit, and push your changes.
- Submit a Pull Request through Github's UI. (Get in touch for access to our repository)