Nav button

Sport Vision API

The Sport Vision API empowers you to transform images into actionable intelligence.

Features

The API allows you to query AI models to extract information from sport or products images and to describe the content of the image.

Sport - identify the sport practiced in a picture, from more than 150 possibilities - determine if an image displays people practicing sports - generate a caption describing the content of the picture, to build smart search engines

Products - identify the type of sport product in the image - identify the brand of the product

Content - identify the list of objects (tent, person, shoes, ...) found in an image - identify the location of these objects in the image - identify the main colors of these objects

The Sport Vision API is deeply linked to the Sports API, which provides a comprehensive and up to date list of sports.

The API is currently under heavy development - stay tuned for future features and releases!

Sign up to receive our newsletter update (required)

To keep our users happy, we want to inform everyone about the amazing upgrades and critical changes.

Sign up now by filling in this form: https://mailchi.mp/decathlon/sportvisionapi

Authentication

A token is required for all of the POST requests. The token is a static randomized string of characters associated with your information; it acts as an api key.

Obtain an Auth Token

You can create your authentication token using our developers console. You can also obtain a token by contacting us at sportvisionapi@decathlon.com

Sport

Generating intelligence from images of sport

Sport practiced in an image

curl -X POST sport-vision-api.decathlon.com/v2/sportclassifier/predict/ \
  -H 'Accept: application/json' \
  -H 'Authorization: XXX' \
  -H 'Content-Type: multipart/form-data' \
  -F file=@YOUR_IMG_PATH.JPG

JSON response:

{
    "data": {
            "location": [
            {
                "name": "indoor",
                "probability": 0.0127
                },
            {
                "name": "outdoor",
                "probability": 0.9873
                }
        ],
        "sport": [
                {
                        "id": "74",
                        "name": "Baseball",
                "probability": 0.9923
                },
            {   
                "id": "76",
                "name": "Cricket",
                "probability": 0.0062
                },
            {   
                "id": "289",
                "name": "Lacrosse",
                "probability": 0.0011
                }
            ]
    }
}

This endpoint returns the sport practiced in an image, along with the probability that the sport has been correctly identified. To get more information about the list of possible sports and their associated information, visit the Sports API. This endpoint also returns the probability that the image was taken outdoor or indoor.

HTTP Request

POST sport-vision-api.decathlon.com/v2/sportclassifier/predict/

curl -X POST sport-vision-api.decathlon.com/v2/sportornot/predict/ \
  -H 'Accept: application/json' \
  -H 'Authorization: XXX' \
  -H 'Content-Type: multipart/form-data' \
  -F file=@YOUR_IMG_PATH.JPG

JSON response:

{
    "data": {
        "probability": 0.9999
    }
}

This endpoint returns the probability that an image displays the practice of a sport or a piece of sport equipment. It can be used for instance in the context of image moderation.

HTTP Request

POST sport-vision-api.decathlon.com/v2/sportornot/predict/

Attaching a caption to your image (alpha)

curl -X POST sport-vision-api.decathlon.com/v2/imagecaptioner/predict/ \
  -H 'Accept: application/json' \
  -H 'Authorization: XXX' \
  -H 'Content-Type: multipart/form-data' \
  -F file=@YOUR_IMG_PATH.JPG

JSON response:

{
    "data": "football players scores his team first goal during the match"
}

Use this endpoint to attach a caption to your sport images. This is an early version of the endpoint - processes are in development to increase the captions' accuracy.

HTTP Request

POST sport-vision-api.decathlon.com/v2/imagecaptioner/predict/

Products

Generating intelligence from images of products

Identify the product in an image

curl -X POST sport-vision-api.decathlon.com/v2/productsclassifier/predict/ \
  -H 'Accept: application/json' \
  -H 'Authorization: XXX' \
  -H 'Content-Type: multipart/form-data' \
  -F file=@YOUR_IMG_ABSOLUTE_PATH.JPG

JSON response:

{
    "data": [
        {   
            "type":"skates",
            "probability": 0.9999,
            "sports_list":  [
                    {
                        "probability": 0.9417,
                        "sports_group": "Hockey"
                        },
                    {
                        "probability": 0.0470,
                        "sports_group": "Inline skating"
                        },
                    {
                        "probability": 0.0112,
                        "sports_group": "Roller skating"
                        }
                ]
            },
        {
            "type":"boots",
            "probability": 0.0001,
            "sports_list":  [
                    {
                        "probability": 0.6640,
                        "sports_group": "Snowboarding"
                        },
                    {
                        "probability": 0.3034,
                        "sports_group": "Hiking,Walking,Camping,Sledding"
                        },
                    {
                        "probability": 0.0324,
                        "sports_group": "Skiing"
                        }
                ]
            },
        {
            "type":"bicycle",
            "probability": 0.0001,
            "sports_list":  [
                    {
                        "probability": 0.9987,
                        "sports_group": "Fitness"
                        },
                    {
                        "probability": 0.0008,
                        "sports_group": "Kids bicycle"
                        },
                    {
                        "probability": 0.0003,
                        "sports_group": "Road cycling"
                        },
                    {
                        "probability": 0.0001,
                        "sports_group": "Mountain biking"
                        }
                ]
            }
    ]
}

This endpoint returns the product in an image, the sports you can practice with the product, and the probability that it has been correctly identified. The list of product types that can be returned by this endpoint can be found here. To know the list of sports potentially returned by the API, refer to the Sports API.

For instance, looking at this json response, it indicates that there is a 99% probability that this is a picture of skates. Assuming that this is indeed a picture of skates, there is a 94% probability that these are skates to practice hockey, and a 5% probability that these are skates for inline skating.

HTTP Request

POST sport-vision-api.decathlon.com/v2/productsclassifier/predict/

Identify the brand in an image (alpha)

curl -X POST sport-vision-api.decathlon.com/v2/sportbrandsdetector/predict/ \
  -H 'Accept: application/json' \
  -H 'Authorization: XXX' \
  -H 'Content-Type: multipart/form-data' \
  -F file=@YOUR_IMG_ABSOLUTE_PATH.JPG

JSON response:

{
    "data": [
        {
            "name": "Bauer",
            "probability": 0.9940
            },
        {   
            "name": "CCM",
            "probability": 0.0279
            },
        {   
            "name": "chest",
            "probability": 0.0080
            }
    ]
}

This endpoint returns the brand of the product in the image, along with the probability that is has been correctly identified. The endpoint is currently limited to brands selling hockey products, but will be expended to all major sports of the Sports API in a next release.

HTTP Request

POST sport-vision-api.decathlon.com/v2/sportbrandsdetector/predict/

Content

Describing the content of an image

Identify the objects found in an image

curl -X POST https://sport-vision-api.decathlon.com/v2/imagecontent/predict/?obj=person,shoes \
  -H 'Accept: application/json' \
  -H 'Authorization: keep-your-keys-to-yourself' \
  -F file=@"YOUR_ABSOLUTE_PATH_TO_JPG_or_PNG_image"

JSON response

{
    "data": [
        {
            "name": "shoes",
            "probability": 0.5606394410133362
        },
        {
            "name": "person",
            "probability": 0.32351014018058777
        }
    ]
}

This endpoint returns a list of objects found in the image, along with the probability that the object has been properly identified. An object can be, for instance, "shoes", "tent" or "bicycle". The list of all the objects potentially returned by the endpoint is available here. We accept image types of jpg, jpeg or png. The response includes the probability that the object was correctly found and the object name.

To get the location (bounding box coordinates) of these objects, use the object detection endpoint described below

HTTP Request

POST sport-vision-api.decathlon.com/v2/imagecontent/predict/

Identify the location of objects of interest in an image

curl -X POST https://sport-vision-api.decathlon.com/v2/objectdetection/predict/?obj=person,shoes \
  -H 'Accept: application/json' \
  -H 'Authorization: keep-your-keys-to-yourself' \
  -F file=@"YOUR_ABSOLUTE_PATH_TO_JPG_or_PNG_image"

JSON response

{
    "data": [
        {
            "bounding_box": [
                234,
                250,
                323,
                383
            ],
            "name": "shoes",
            "probability": 0.5606394410133362
            "tags": {
                "main_color": [
                    "red",
                    "dark-gray"
                ]
            },
        {
            "bounding_box": [
                69,
                266,
                1128,
                1378
            ],
            "name": "shorts",
            "probability": 0.32351014018058777
            "tags": {
                "main_color": [
                    "white",
                    "blue"
                ]
            }
    ]
}

This endpoint can be used to identify the location (bounding box coordinates) of objects of interest in the image. The objects of interest that you can look for are required to be from this list.

?obj=person,shoes in the url allows you to specify your personal object of interest by listing comma separated entities. If the parameter obj is not given, it will return all object classes.

The response will include the X and Y coordinates of the bounding boxes describing the location of the object in the image, as [topleft_x, topleft_y, bottomright_x, bottomright_y].

The object detection model also returns one or two main colours of the identified object. The colours that could be returned include: Red, Lime, Blue, Yellow, Cyan, Magenta, Silver, Grey, Green, Purple, Teal, Navy, Orange, Mauve, Brown, Pink, Black, and Dark Gray.

HTTP Request

POST sport-vision-api.decathlon.com/v2/objectdetection/predict/

Errors

The Sport Vision 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.
500 Internal Server Error -- We had a problem with our server. Try again later.

Roadmap

This API is currently under heavy developement. Submit your feedback at sportvisionapi@decathlon.com

Upcoming

Q1 2020

F.A.Q.

How were the sports chosen?

The Sports were selected based on extensive research from our skilled sport experts at Decathlon. See the Sports API documentation for more information.

How were the products and brands chosen?

The products and brand were choosen to cover the practice of all the most popular sports in the Sports API.

The list will be continuously extended over time based on user input. Tags (male/female, player/goaltender, etc.) will also be added to describe in greater accuracy the products in pictures.

How is it supposed to help me?

Our objective is to democratize the application of artificial intelligence to sport. Think of us as the Google vision API specialized to sport. Want to build a smart marketplace of sport products? Get to know your sport users better from the pictures that they post on your platform? Automate the countless hours spent on tagging or describing the pictures in your database? That's what we are here for.

What if a sport, product or brand is missing?

If a sport, product or brand is missing that you feel should be included, send us an email at sportvisionapi@decathlon.com.

How can I make a POST request in Python?

POST requests to our API can be made in Python using the Requests library. Here is an example of call for a given endpoint, API key and image filepath:

url = f"https://sport-vision-api.decathlon.com/v2/{endpoint}"
headers = {"Authorization": {API key}}
files = {"file": open({filepath}, "rb")}
response = requests.request("POST", url, files=files, headers=headers)
print(response.text)

Contributing

Everyone is encouraged to help improve this project.

Here are some ways you can contribute:

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)