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
- exclusively for the sport Yoga, identify the pose in a picture, from a pool of 18 popular yoga poses including bridge, lotus, tree and more
- identify if people are smiling in an image
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 https://sport-vision-api.decathlon.com/v2/sportclassifier/predict/ \
-H 'Accept: application/json' \
-H 'Authorization: XXX' \
-H 'Content-Type: multipart/form-data' \
-F file=@YOUR_JPG_OR_PNG_IMG_PATH
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/
Image relevance
curl -X POST https://sport-vision-api.decathlon.com/v2/sportornot/predict/ \
-H 'Accept: application/json' \
-H 'Authorization: XXX' \
-H 'Content-Type: multipart/form-data' \
-F file=@YOUR_JPG_OR_PNG_IMG_PATH
JSON response:
{
"data": {
"probability": 0.9999
}
}
This endpoint returns the probability that the theme of an image is related to sport (for instance, an image of people practicing sport or of sport equipment). This endpoint can be used in the context of image moderation: for instance, flagging any image with a low probability of being related to sport.
HTTP Request
POST sport-vision-api.decathlon.com/v2/sportornot/predict/
Attaching a caption to your image (alpha)
curl -X POST https://sport-vision-api.decathlon.com/v2/imagecaptioner/predict/ \
-H 'Accept: application/json' \
-H 'Authorization: XXX' \
-H 'Content-Type: multipart/form-data' \
-F file=@YOUR_JPG_OR_PNG_IMG_PATH
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 https://sport-vision-api.decathlon.com/v2/productsclassifier/predict/ \
-H 'Accept: application/json' \
-H 'Authorization: XXX' \
-H 'Content-Type: multipart/form-data' \
-F file=@YOUR_JPG_OR_PNG_IMG_PATH
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 of the product in an image
curl -X POST https://sport-vision-api.decathlon.com/v2/sportbrandsdetector/predict/ \
-H 'Accept: application/json' \
-H 'Authorization: XXX' \
-H 'Content-Type: multipart/form-data' \
-F file=@YOUR_JPG_OR_PNG_IMG_PATH
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/
Decathlon's catalog product retrieval
curl -X POST sport-vision-api.decathlon.com/v2/productretrieval/predict/ \
-H 'Accept: application/json' \
-H 'Authorization: XXX' \
-H 'Content-Type: multipart/form-data' \
-F file=@YOUR_JPG_OR_PNG_IMG_PATH
JSON response:
{
"data": [
{
"brand_label": "BTWIN",
"color_label": "DARK BLUE",
"season_years_list": ['2018', '2019', '2020'],
"country_code": "CA",
"image_url": "https://contents.mediadecathlon.com/p1341693/sq/1341693.jpg?f=224x224",
"product":
{
"decathlon_id": 8487186,
"name": "500 ORIGINAL 9-12"
},
"sports_list": [
{
"decathlon_id": 284,
"name": "HYBRID BIKES"
},
{
"decathlon_id": 283,
"name": "URBAN CYCLING"
}
],
"type":
{
"decathlon_id": 325792,
"name": "HYBRID BIKE"
}
}
...
]
}
This endpoint returns the list of products from Decathlon catalog that are most visually similar to the input image. The endpoint returns the id of the product, along with relevant product information that include: the name of the product, the brand of the product, the color of the product, the list of years the product was sold, the type of product (also called the product nature), the sports that you can practice with the product, and the url of the product image. The number of products returned by the API (default of 10) can be selected by passing the rec_qty argument.
The top recommendations can be filtered by passing the brand, type, and sport arguments (for example, you can set the type argument to "shoes" if you are only looking for products of that type).
Visual search is currently available for the catalog of products of Decathlon Canada. Contact us at sportvisionapi@decathlon.com to deploy this service for the catalog of your country.
HTTP Request
POST sport-vision-api.decathlon.com/v2/productretrieval/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_JPG_OR_PNG_IMG_PATH
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_JPG_OR_PNG_IMG_PATH
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/
Identify the yoga pose in an image
curl -X POST https://sport-vision-api.decathlon.com/v2/yogaposesclassifier/predict/ \
-H 'Accept: application/json' \
-H 'Content-Type: multipart/form-data' \
-H 'Authorization: keep-your-keys-to-yourself' \
-F 'file=@YOUR_JPG_OR_PNG_YOGA_IMG_PATH'
JSON response
{
"data": [
{
"name": "Child",
"probability": 100.0
},
{
"name": "Forward bends",
"probability": 0.0
},
{
"name": "Bridge",
"probability": 0.0
}
]
}
This endpoint can be used to identify the displayed yoga pose in the image. Note that this is an image of yoga. The poses of interest that you can look for are reported in this list.
For instance, looking at the json response and assuming that the posted image is a picture of yoga practice, there is a 100% probability that the pose displayed is a child pose.
HTTP Request
POST sport-vision-api.decathlon.com/v2/yogaposesclassifier/predict
Identify smiles in an image
curl -X POST https://sport-vision-api.decathlon.com/v2/smile-detector/predict/ \
-H 'Accept: application/json' \
-H 'Content-Type: multipart/form-data' \
-H 'Authorization: keep-your-keys-to-yourself' \
-F 'file=@YOUR_JPG_OR_PNG_YOGA_IMG_PATH'
JSON response
{
"data": [
{
"coordinates": [
504,
572,
628,
729
],
"landmarks": [
[
508,
642
],
[
506,
656
],
[
504,
670
],
[
505,
685
],
[
507,
700
],
[
512,
712
],
...
],
"probability": 0.6
}
]
}
This endpoint can be used to detect faces in an image and to identify if the persons are smiling. The location of the faces on the image is reported, along with a list of 68 landmark points on the face, as described here.
All the points are reported in the openCV coordinates where the origin is at the top left of the image and the y-axis points down. The first 2 numbers returned in the "coordinates" field correspond to the top left corner of the rectangle enclosing the face and the last 2 to the bottom right corner. The probability is a score between 0 and 1 computed from a number of indicators suggesting that the person is smiling in the picture.
HTTP Request
POST sport-vision-api.decathlon.com/v2/smile-detector/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 2021
- Improve the accuracy of the yoga classifier endpoint.
Q2 2021
- Improve the performance (stability, speed, accuracy) of the product retrieval endpoint.
- Add new sports to the sport classification endpoint.
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:
- 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
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)