Menu
shell
  • Standards
  • API Libraries
  • Sports
  • F.A.Q.
  • Contributing
  • Introduction

    This Sports API can be used by any developer worldwide to obtain details of our Sports. This data is primarily sourced from our global network of sport experts and our beloved friends.

    Getting started with the Sports API

    Standards

    This API follows the JSON:API spec

    Localization

    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

    API Libraries

    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.

    Sports

    List Sports

    curl "https://sports-decathlon.herokuapp.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-dc159b85-6e37-4910-8f78-011ec1c2a041",
                    "locale": "en"
                },
                "relationships": {
                    "parent": {
                        "data": {
                            "id": "486",
                            "type": "sport"
                        }
                    }
                }
            },
            //...
        ]
    }
    
    

    This endpoint retrieves all sports meeting specific criteria

    HTTP Request

    GET https://sports-decathlon.herokuapp.com/sports

    Query Parameters

    Search query errors will be responded to with specific error information, and an HTTP 404 status code.

    Parameter Example Description
    q soccer 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
    parent '1' Boolean parameter to display parent-sports only.

    Querying a single Sport

    curl "https://sports-decathlon.herokuapp.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 can be passed in as either the slug column or the id column, for convenience. If a sport does not 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-decathlon.herokuapp.com/sports/278

    Query Parameters

    Search query errors will be responded to with specific error information, and an HTTP 404 status code.

    Sport Recommendations

    curl
    "https://sports-decathlon.herokuapp.com/sports/:sport_id/recommendations"
    

    JSON Response

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

    This endpoint provides sport recommendations based on AI.

    Parameter Example Description
    sport_id 175 Sport ID
    count 5 Number of recommendations (Default: 3)

    HTTP Request

    GET https://sports-decathlon.herokuapp.com/sports/175/recommendations

    Query Parameters

    Search query errors will be responded to with specific error information, and an HTTP 404 status code.

    Errors

    The Communities API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid - check the JSON format of your request.
    401 Unauthorized -- Your API key is wrong.
    404 Not Found -- The specified community wasn't found.
    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 expertise in the field.

    We plan to expand intelligence on this data with the help of our community, so modern applications and/or data researchers can take advantage of it.

    How is it supposed to empower me?

    The data provided here is a result of many hours of research and our goal is to make it easy for Sport Tech startups to get ahead quickly by having access to metrics such as popularity, density, weather-based likeliness to practice a sport 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 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 require a different format.

    Contributing

    Everyone is encouraged to help improve this project.

    Here are some ways you can contribute:

    Submit your contribution here

    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.