Nav button

Sports API

Sports API

Introduction

The Sports API can be used by any developer to obtain details on sports. This data is primarily sourced from our global network of partners and experts.

API Reference

Listing Sports

curl "https://sports.api.decathlon.com/sports"

JSON response:

{
    "data": [
        {
            "id": "278",
            "type": "sport",
            "attributes": {
                "name": "Swimming",
                "description": null,
                "parent_id": null,
                "slug": "swimming",
                "locale": "en"
            },
            "relationships": {
                "children": {
                    "data": [
                        {
                            "id": "331",
                            "type": "sport"
                        },
                        {
                            "id": "219",
                            "type": "sport"
                        },
                        {
                            "id": "405",
                            "type": "sport"
                        },
                        {
                            "id": "449",
                            "type": "sport"
                        },
                        {
                            "id": "224",
                            "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 retrieves all sports meeting specific criteria

HTTP Request

GET https://sports.api.decathlon.com/sports

Query Parameters

Search query errors will be rescued with specific error messages, and an HTTP 404 status code.

Parameter Example Description
q socc Query a sport by its name, using a string for searching
tag winter Filter sports by a tag.
decathlon_id 175 Search sports by Decathlon's legacy ID
parents_only true Boolean parameter to display parent-sports only.

Querying a single Sport

curl "https://sports.api.decathlon.com/sports/swimming"

JSON Response

{
    "data": {
        "id": "278",
        "type": "sport",
        "attributes": {
            "name": "Swimming",
            "description": null,
            "parent_id": null,
            "slug": "swimming",
            "locale": "en"
        },
        "relationships": {
            "children": {
                "data": [
                    {
                        "id": "331",
                        "type": "sport"
                    },
                    {
                        "id": "219",
                        "type": "sport"
                    },
                    {
                        "id": "405",
                        "type": "sport"
                    },
                    {
                        "id": "449",
                        "type": "sport"
                    },
                    {
                        "id": "224",
                        "type": "sport"
                    }
                ]
            }
        }
    }
}

This endpoint retrieves a sport (and its children, if any). The ID parameter can be passed in as a slug or id for convenience. In the case a sport doesn't have children, or if it's already a child, the relationship object will return null. If a sport is a child, the parent_id column will display the ID of its parent.

HTTP Request

GET https://sports.api.decathlon.com/sports/278

Query Parameters

Search query errors will be rescued with specific error messages, and an HTTP 404 status code.

Fetching recommendations by geolocation popularity

curl
"https://sports.api.decathlon.com/sports/recommendations/geolocation?coordinates=-73.582,45.511&count=3"

JSON Response

[ "123", "456", "789" ]

Most popular sports in a radius of 15 kilometers around the given coordinates based on an AI that analyses internal and external data-sets (events, places, web traffic, ... )

Parameter Example Description
coordinates -73,45 Longitude, latitude for the geolocation filter
count 5 Number of recommendations (Default: 3)

Fetching recommendations by popularity (DEPRECATION WARNING)

curl
"https://sports.api.decathlon.com/sports/:sport_id/recommendations"

JSON Response

[ "123", "456", "789" ]

This endpoint provides sport recommendations based on machine learning algorithms.

Parameter Example Description
coordinates -73,45 Longitude, latitude of the origin
count 5 Number of recommendations (Default: 3)

Fetching recommendations based on density of places per country (DEPRECATION WARNING)

curl
"https://sports.api.decathlon.com/sports/recommendations/:country"

JSON Response

[ "123", "456", "789" ]

This endpoint provides sport recommendations based on an average density of places in a specified country.

Parameter Example Description
country CA 2-letter country code

HTTP Request

GET https://sports.api.decathlon.com/sports/175/recommendations

Query Parameters

Search query errors will be rescued with specific error messages, and an HTTP 404 status code.

Listing Sport Groups

curl "https://sports.api.decathlon.com/sports"

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": 385,
                            "type": "sport"
                        },
                        {
                            "id": 406,
                            "type": "sport"
                        },
                        {
                            "id": 228,
                            "type": "sport"
                        },
                        {
                            "id": 221,
                            "type": "sport"
                        },
                        {
                            "id": 405,
                            "type": "sport"
                        },
                        {
                            "id": 224,
                            "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"
                        }
                    ]
                }
            }
        },
        {
            "id": 2,
            "type": "group",
            "attributes": {
                "name": "Athletics",
                "slug": "athletics",
                "locale": "en"
            },
            "relationships": {
                "sports": {
                    "data": [
                        {
                            "id": 257,
                            "type": "sport"
                        },
                        {
                            "id": 390,
                            "type": "sport"
                        },
                        {
                            "id": 339,
                            "type": "sport"
                        },
                        {
                            "id": 4,
                            "type": "sport"
                        },
                        {
                            "id": 340,
                            "type": "sport"
                        },
                        {
                            "id": 338,
                            "type": "sport"
                        },
                        {
                            "id": 389,
                            "type": "sport"
                        },
                        {
                            "id": 5,
                            "type": "sport"
                        },
                        {
                            "id": 341,
                            "type": "sport"
                        },
                        {
                            "id": 461,
                            "type": "sport"
                        },
                        {
                            "id": 12,
                            "type": "sport"
                        },
                        {
                            "id": 488,
                            "type": "sport"
                        },
                        {
                            "id": 261,
                            "type": "sport"
                        },
                        {
                            "id": 487,
                            "type": "sport"
                        },
                        {
                            "id": 507,
                            "type": "sport"
                        },
                        {
                            "id": 508,
                            "type": "sport"
                        },
                        {
                            "id": 509,
                            "type": "sport"
                        },
                        {
                            "id": 510,
                            "type": "sport"
                        },
                        {
                            "id": 511,
                            "type": "sport"
                        },
                        {
                            "id": 512,
                            "type": "sport"
                        },
                        {
                            "id": 513,
                            "type": "sport"
                        },
                        {
                            "id": 514,
                            "type": "sport"
                        },
                        {
                            "id": 515,
                            "type": "sport"
                        },
                        {
                            "id": 516,
                            "type": "sport"
                        },
                        {
                            "id": 517,
                            "type": "sport"
                        },
                        {
                            "id": 518,
                            "type": "sport"
                        },
                        {
                            "id": 519,
                            "type": "sport"
                        },
                        {
                            "id": 522,
                            "type": "sport"
                        },
                        {
                            "id": 520,
                            "type": "sport"
                        },
                        {
                            "id": 521,
                            "type": "sport"
                        },
                        {
                            "id": 523,
                            "type": "sport"
                        },
                        {
                            "id": 524,
                            "type": "sport"
                        },
                        {
                            "id": 525,
                            "type": "sport"
                        },
                        {
                            "id": 526,
                            "type": "sport"
                        },
                        {
                            "id": 527,
                            "type": "sport"
                        },
                        {
                            "id": 528,
                            "type": "sport"
                        },
                        {
                            "id": 529,
                            "type": "sport"
                        },
                        {
                            "id": 530,
                            "type": "sport"
                        },
                        {
                            "id": 531,
                            "type": "sport"
                        },
                        {
                            "id": 532,
                            "type": "sport"
                        },
                        {
                            "id": 533,
                            "type": "sport"
                        },
                        {
                            "id": 280,
                            "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

Query 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

Query 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

Decathlon::Sports.find

sport = Decathlon::Sports.find(175)

Decathlon::Sports.find

sport = Decathlon::Sports.search('Snowboarding')

Decathlon::Sports::Recommendations.get

recommendations = Decathlon::Sports::Recommendations.get(175)

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

Our API supports localization of the sports names. Such data can be retrieved by passing in the preferred locale in the request header, as such:

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:

Submit your contribution

URL: https://developers-decathlon.canny.io/sports-api

Submitting a Pull Request

  1. Fork/Clone the Repository
  2. Create a [new-feature] branch
  3. Implement your feature or bug fix.
  4. Add, commit, and push your changes.
  5. Submit a Pull Request through Github's UI. (Get in touch for access to our repository)