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/
Content of an image related to sport or not
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
- Launch the product recognition endpoint for all major sports of the Sports API
- Launch the brand recognition endpoint for all major sports of the Sports API ### Q2 2020
- Improve the accuracy of image captioning for all major sports of the Sports API
- Reduce the response time of the brand recognition endpoint for all major sports of the Sports API
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)