Sport Places API
Get started
The goal of the Sport Places API is to help you build sport-oriented applications faster as well as easier. Here are a few steps to get you started:
1. 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/sportplacesapi
2. Learn how to authenticate
To get a client_id
and a JWT token
, go to Authentication
3. Make your first API Call
You are ready to go! We suggest that you start off by retrieving all sport places around you.
Bonus: Play with our Postman Collection
We've crafted a collection of pre-configured API calls to make it easier for our users to familiarize themselves with the format of our requests. This, however, is only intended to be a testing tool, not an official or unofficial interface to our API.
Please click here to download our Postman Collection
- In order to use this collection, you must have Postman installed on your system.
Authentication
1. Create an API client application
curl --request POST \
--url 'https://sportplaces.api.decathlon.com/api/v1/clients' \
--header 'content-type: application/json' \
--data '{"client_name":"My Client Application","redirect_uris": ["https://client.example.com/callback"]}'
A JWT token is required for all POST
, PUT/PATCH
, and DELETE
requests.
Currently we use Auth0 to issue JWTs for third-party developers, and Decathlon Login if you are part of Decathlon partner program.
All third-party developers must obtain an application client_id
and client_secret
issued by Auth0 via our dedicated API endpoint.
You MUST set your name correctly, as there is currently no way to alter it after creation.
2. Obtain a JWT Token
https://decathlon.auth0.com/authorize?
audience=sportplaces-api.herokuapp.com&
scope=openid%20profile%20email&
response_type=id_token&
client_id={CLIENT_ID}&
redirect_uri={REDIRECT_URI}&
nonce={CRYPTOGRAPHIC_NONCE}
state={OPAQUE_VALUE}
To obtain a JWT, you must redirect your users to a specific URL containing:
- Your
client_id
- Your desired
redirect_uri
- A cryptographic
nonce
to prevent replay attacks - Your application
state
to prevent CSRF attacks
Please see the Auth0 Documentation for more information about these parameters.
Once the user has completed their login, they will be redirected back to your application with a JWT in the hash fragment of the URI.
3. Using a JWT
curl "https://sportplaces.api.decathlon.com/api/v1/places"
-H "Authorization: Bearer XXXXXX"
GET
requests do not require authentication
You must authenticate all POST
, PUT/PATCH
, and DELETE
requests with a JWT in the Authorization header.
Sport Places
This endpoint retrieves all the sport places meeting specific criterias.
Concrete example
curl "https://sportplaces.api.decathlon.com/api/v1/places?origin=-73.582,45.511&radius=99&sports=175"
JSON response:
{
"links": {
"self": "https://sportplaces.api.decathlon.com/api/v1/places?origin=-73.5826985%2C45.5119864&page=1&radius=99",
"next": "https://sportplaces.api.decathlon.com/api/v1/places?origin=-73.5826985%2C45.5119864&page=2&radius=99"
},
"count": 100,
"data": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"uuid": "8b1e3027-e438-42c2-92ab-5ebd23f68d54",
"name": "McConnell Arena",
"slug": "mcconnell-arena",
"google_place_id": "ChIJ5XD-5zAayUwRIK7t7t89ZJ0",
"contact_details": {
"email": null,
"phone": "+1 514-398-7017",
"website": null,
"booking_url": null,
"facebook_username": null
},
"address_components": {
"address": "3883 Rue University",
"city": "Montréal",
"province": "Québec",
"country": "CA"
},
"activities": [
{
"sport_id": 160,
"tags": [],
"attributes": {
"difficulty": 2,
"distance": 10
}
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-73.5826985,
45.5119864
]
}
}
]
}
}
Return all ice hockey sport places within 99km around McGill University in Montréal, Canada.
Parameter | Value | Description |
---|---|---|
sports | 175 | 175 is the sport id for ice hockey as per our Sports API |
origin | -73.582,45.511 | longitude,latitude of your location |
radius | 99 | 99km around my latitude and longtitude |
Go ahead and copy and paste this request in your browser to test it.
https://sportplaces.api.decathlon.com/api/v1/places?origin=-73.582,45.511&radius=99&sports=175
Works? Great!
Keep reading the documentation to build your own queries. If you have any questions, head to the support section.
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/places
Query Parameters
Most parameters are optional, but certain logical combinations (such as sw
and ne
, or origin
and radius
)
must both be sent together if one is.
Coordinates (sw
, ne
, origin
, user_origin
) are comma separated string representations of geographic locations. As
per the GeoJSON standard, these are formatted as: lng,lat
- the reverse of several other standards.
Results are ordered by proximity to the user_origin
or origin
if the former
isn't provided.
A bounding box (set by sw
& ne
), or the radius
must not exceed 100km in length.
Min/max value pairs do not both need to be specified. For example, use only min_distance=300
to find activities with
a distance of over 300 metres, with no upper limit.
The fields difficulty
, cellphone_service
, and quality
are integer values [0, 1, 2]
representing
['Beginner', 'Intermediate', 'Advanced']
, or ['poor', 'acceptable', 'good']
.
The number of results per page is limited to a max of 100.
E.g.: &page=2
should give you the remaining set of results.
Search query errors will be responded to with specific error information, and an HTTP 422
status code.
Parameter | Example | Description |
---|---|---|
sw | '-73.58,45.51' |
Bounding box corner (South West) |
ne | '-73.08,45.91' |
Bounding box corner (North East) |
origin | '-73.58,45.51' |
Central point from which to search for places |
radius | 10 |
Number of kilometres around the origin to search |
user_origin | '-73.08,45.91' |
The current location of the end-user making the request. Used to calculate proximity. |
sports | '175,160' |
Filters results based on Decathlon Sport ID |
tags | 'free,equipment_rental' |
Restricts search results to only those matching all set tags |
surface | clay,concrete |
Restricts search results to only those matching specified surface types |
min_difficulty | 0 |
Integer [0, 1, 2] representing the minimum difficulty level |
max_difficulty | 2 |
Integer [0, 1, 2] representing the maximum difficulty level |
min_duration | 60 |
Minimum number of minutes for the sporting activities |
max_duration | 3660 |
Maximum number of minutes allowed for the sporting activities |
min_distance | 10 |
Minimum required distance in metres for the activities |
max_distance | 100 |
Maximum allowed distance in metres for the activities |
min_elevation_gain | 50 |
Minimum required vertical elevation change in metres for the activities |
max_elevation_gain | 250 |
Maximum allowed vertical elevation change in metres for the activities |
min_cellphone_service | 0 |
Minimum required cell reception level in the area |
max_cellphone_service | 2 |
Maximum allowed cell reception level in the area |
min_quality | 0 |
Minimum required playing surface quality for the sporting activity |
max_quality | 2 |
Minimum required playing surface quality for the sporting activity |
limit | 10 |
Number of records to be returned per call |
created_at | desc |
Order of results by creation date (asc or desc) |
days | 7 |
Number of days from now from which places have been created |
page | 2 |
Number of pagination of results |
partner | amilia |
Restrict results to only the specified partner (slug) |
featured | true |
Restrict results to only handpicked featured places (boolean) |
Retrieving Place Information
curl "https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID"
# OR
curl "https://sportplaces.api.decathlon.com/api/v1/places/PLACE_SLUG"
JSON response:
{
"type": "Feature",
"properties": {
"uuid": "488c45cf-2d7c-4903-9477-01249966adcf",
"name": "Studio Bizz Mount Royal",
"slug": "studio-bizz-mount-royal",
"proximity": null,
"user": {
"identifier": "0",
"first_name": "Decathlon",
"last_name": "IT",
"staff": true
},
"partner": null,
"featured": false,
"created_at": "2018-04-16 03:19:21 UTC",
"google_place_id": "ChIJJSVAUdAbyUwRKvTXuACHnqg",
"contact_details": {
"email": null,
"phone": "+1 514-526-2499",
"website": null,
"booking_url": null,
"facebook_username": null
},
"address_components": {
"address": "551 Avenue du Mont-Royal Est",
"city": "Montréal",
"province": "Québec",
"country": "CA"
},
"activities": [
{
"sport_id": 100,
"tags": [
"lessons"
],
"photo_reference": "CmRaAAAA7zB04n0YClB-QsAYy5ajwJvw4FbGoPovFwsU0rnvzyXAPbhIrFIgBbD3YP4ktUiLAt08G_Ij0reuSkICg62ycKregB-bG93z9VBZlsKaQQ6_W3oxwSLi4z7m-3GP1NiIEhDIR732x9Vy3hlwiC2Wg4OhGhRGJ9RYl8yhYunKA5HBktDqWj1XRw",
"user": {
"identifier": "0",
"first_name": "Decathlon",
"last_name": "IT",
"staff": true
},
"attributes": {
"difficulty": 0
},
"image": {}
},
{
"sport_id": 292,
"tags": [
"lessons"
],
"photo_reference": "CmRaAAAA7zB04n0YClB-QsAYy5ajwJvw4FbGoPovFwsU0rnvzyXAPbhIrFIgBbD3YP4ktUiLAt08G_Ij0reuSkICg62ycKregB-bG93z9VBZlsKaQQ6_W3oxwSLi4z7m-3GP1NiIEhDIR732x9Vy3hlwiC2Wg4OhGhRGJ9RYl8yhYunKA5HBktDqWj1XRw",
"user": {
"identifier": "0",
"first_name": "Decathlon",
"last_name": "IT",
"staff": true
},
"attributes": {
"difficulty": 0
},
"image": {}
}
],
"notes": "Cours de différents styles de danse, tous niveaux ( débutant à avancé). Cours pour enfants"
},
"geometry": {
"type": "Point",
"coordinates": [
-73.581967,
45.525197
]
}
}
This endpoint retrieves data about a single place rather than a collection of places in a specific geolocation.
Places can be retrieved by their UUID
or slug
properties.
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/places/PLACE_SLUG
Query Parameters
The only accepted (and required) parameter for this endpoint is the place UUID.
Adding Places
curl
-X POST
-H "Content-Type: application/json"
-H 'Authorization: Bearer XXXXXX'
-d "@data.json"
https://sportplaces.api.decathlon.com/api/v1/places
Using a Google Place ID
{
"google_place_id":"ChIJm7QDm0Y36IkRbbD20K2fC24",
"activities": [
{
"sport_id": "175",
"tags": ["free"],
"distance": 10,
"difficulty": 2
},
{
"sport_id": "160",
"tags": ["free"],
"distance": 10,
"difficulty": 2,
"duration": 10,
"elevation_gain": 0,
"cellphone_service": 1
}
],
"notes": "Lorem Ipsum dolor amet sit..."
}
Using GeoJSON geometry
{
"name": "Example Path",
"country": "CA",
"activities": [
{
"sport_id": "175",
"tags": ["free"]
}
],
"notes": "Lorem Ipsum dolor amet sit",
"geometry": {
"type": "Linestring",
"coordinates": [
[-73.5826985, 45.5119864],
[-73.581, 45.512]
]
}
}
This endpoint creates places based on a Google Place ID and an Activity (Sport ID)
HTTP Request
POST https://sportplaces.api.decathlon.com/api/v1/places
Request Parameters (using a Google Place ID)
Parameter | Value | Description |
---|---|---|
google_place_id | ChIJm7QDm0Y36IkRbbD20K2fC24 |
A Google Place ID |
activities | See below | A list of sporting activities to add to this place |
notes | Any text you like |
Optional freeform text notes to add to a place |
Google Place ID
and the activities
array are mandatory.
Within the Activities array are hashes that represent each activity and its filters
Request Parameters (using geometry and name data)
Parameter | Value | Description |
---|---|---|
geometry | GeoJSON geometry feature | A GeoJSON formatted geometry feature, either a Point , Linestring , or Polygon |
activities | See below | A list of sporting activities to add to this place |
country | CA |
Two letter ISO country code |
notes | Any text you like |
Optional freeform text notes to add to a place |
geometry
, name
, country
, and the activities
array are mandatory.
Within the Activities array are hashes that represent each activity and its filters
Activity Properties
Required properties:
Parameter | Example | Description |
---|---|---|
sport_id | 175 |
Reference to the Sport this activity belongs to. |
tags | ['equipment_rental', 'lessons'] |
(optional) Array of tags(strings). See Sport Tags for more info. |
Filters are not required by default, but are highly recommended for a better user experience. Most filters will have a numeric value.
Updating/Editing Places
curl
-X PUT
-H "Content-Type: application/json"
-H 'Authorization: Bearer XXXXXX'
-d "@data.json"
https://sportplaces.api.decathlon.com/api/v1/places/:place_id
JSON request [@data.json]
{
"name": "McGee Park",
"email": "johndoe@decathlon.ca",
"phone": "+1 555 555 5555",
"website": "https://example.com",
"booking_url": "http://example.com/book-now",
"facebook_username": "johndoe",
"address": "123 Easy St",
"city": "Montreal",
"province": "QC",
"country": "CA",
"featured": true,
"notes": "Lorem Ipsum dolor amet sit..."
}
This endpoint updates places parameters.
NOTE: Activities should be updated using the Activities endpoint
HTTP Request
PUT https://sportplaces.api.decathlon.com/api/v1/places/:place_id
Request Parameters
Parameter | Example | Description |
---|---|---|
name | 'McGee Park' |
Name of the place |
'john.doe@example.com' |
Contact Email | |
phone | '1 555 555 5555 ext 123' |
Phone number |
website | 'https://example.com' |
Venue Website |
booking_url | 'https://example.com/book-now' |
Booking Website |
facebook_username | 'mcgee-park' |
Username on Facebook |
address | '123 Easy St.' |
Street address |
city | 'Montreal' |
City where place is located |
province | 'QC' |
Province where place is located |
country | 'CA' |
Country code where place is located |
notes | 'Lorem Ipsum ...' |
Localized arbitrary notes provided by the user. |
featured | `false | true` |
JSON response
{
"type": "Feature",
"properties": {
"uuid": "750cbd99-a9b1-4d2f-a271-ba8866296cf6",
"name": "660 Terry Rd",
"google_place_id": "ChIJm7QDm0Y36IkRbbD20K2fC24",
"featured": true,
"user": [
{
"user_id": "1235781113",
"first_name": "John",
"last_name": "Doe",
"staff": true
}
],
"contact_details": {
"email": null,
"phone": null,
"website": null,
"booking_url": null,
"facebook_username": null
},
"address_components": {
"address": "660 Terry Road",
"city": "Hauppauge",
"province": "New York",
"country": "US"
},
"activities": [
{
"sport_id": 175,
"tags": [
"free"
],
"attributes": {
"difficulty": 2,
"distance": 10
}
},
{
"sport_id": 160,
"tags": [
"free"
],
"attributes": {
"difficulty": 2,
"duration": 10,
"distance": 10,
"elevation_gain": 0,
"cellphone_service": 1
}
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-73.167277,
40.8188078
]
}
}
Marking a place as featured
curl
-X PUT
-H "Content-Type: application/json"
-H "Authorization: Bearer XXXXX"
-d "@data.json"
https://sportplaces.api.decathlon.com/api/v1/places/:place_id
Decathlon Partners are able to mark select places as featured in our API, to do so simply authenticate as a partner and make a PUT request to a place much like updating a place (See above), in fact the process is identical.
JSON request [@data.json]
{
"featured": true
}
JSON response
{
"type": "Feature",
"properties": {
"uuid": "750cbd99-a9b1-4d2f-a271-ba8866296cf6",
"name": "660 Terry Rd",
"google_place_id": "ChIJm7QDm0Y36IkRbbD20K2fC24",
"featured": true,
},
...
}
Updating/Editing Activities of a Place
curl
-X PUT
-H "Content-Type: application/json"
-H 'Authorization: Bearer XXXXXX'
-d "@data.json"
https://sportplaces.api.decathlon.com/api/v1/places/:place_id/activities/:activity_id
JSON request [@data.json]
{
"tags": ["free"],
"photo_reference": "1235ygfrt6547u4trgew23rfv[ew455",
"difficulty": 2,
"distance": 1
}
This endpoint updates activities of a particular place
HTTP Request
POST https://sportplaces.api.decathlon.com/api/v1/places/:place_id/activities/:activity_id
Request Parameters
All activity parameters are accepted, with exception of sport_id
and user
which are immutable.
Errors
Errors will be responded to with specific error information, and an HTTP 422
status code.
Removing places
curl
-X DELETE
-H "Content-Type: application/json"
-H 'Authorization: Bearer XXXXXX'
https://sportplaces.api.decathlon.com/api/v1/places/:place_id
This endpoint deletes places that were added by the current authenticated user.
- Users cannot remove places that weren't created by them.
JSON response
{
message: "Deleted"
}
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/places/pending
Request Parameters
This GET request accepts no parameters.
Errors
Errors will be responded to with specific error information, and an HTTP 422
status code.
Places pending moderation
curl
-X GET
-H "Content-Type: application/json"
-H 'Authorization: Bearer XXXXXX'
https://sportplaces.api.decathlon.com/api/v1/places/pending
This endpoint lists places that were added by the user ID'ed by the JWT token and are pending moderation.
JSON response
{
"type": "Feature",
"properties": {
"uuid": "fe56287f-a1ac-4b71-abe8-845bff595fce",
"name": "Park Street",
"proximity": null,
"user": {
"identifier": "31391277-4202-4d97-88ad-31caad2f9be4",
"first_name": "Caio",
"last_name": "Bianchi",
"staff": true
},
"partner": null,
"created_at": "2018-10-04 20:29:33 UTC",
"google_place_id": "ChIJU2s2Gz6uEmsRIuwzjuh3Qa0",
"contact_details": {
"email": null,
"phone": null,
"website": null,
"booking_url": null,
"facebook_username": null
},
"address_components": {
"address": "Park Street",
"city": "Sydney",
"province": "New South Wales",
"country": "AU"
},
"activities": [
{
"sport_id": 175,
"tags": [
"free"
],
"photo_reference": null,
"user": {
"identifier": "31391277-4202-4d97-88ad-31caad2f9be4",
"first_name": "Caio",
"last_name": "Bianchi",
"staff": true
},
"attributes": {
"difficulty": 2,
"distance": 10
},
"image": {}
}
],
"notes": "Lorem Ipsum Dodfdflor Amet Sit"
},
"geometry": {
"type": "Point",
"coordinates": [
151.2099083,
-33.8732855
]
}
}
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/places/pending
Request Parameters
This GET request accepts no parameters.
Errors
Errors will be responded to with specific error information, and an HTTP 422
status code.
Activities
Get a list of activities for a sport
curl "https://sportplaces.api.decathlon.com/api/v1/places/8b1e3027-e438-42c2-92ab-5ebd23f68d54/activities"
JSON response:
[
{
"sport_id": 160,
"tags": [],
"difficulty": 2,
"duration": 10,
"distance": 10,
"elevation_gain": 0,
"cellphone_service": 1
},
{
"sport_id": 160,
"tags": [],
"difficulty": 2,
"distance": 10
}
]
Retrieves a list of sporting activities at a place.
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/activities
Add a new activity
curl -X POST \
https://sportplaces.api.decathlon.com/api/v1/places/9249f4b3-aff8-4e5c-8e76-9c79f4cf7bf3/activities \
-H 'Authorization: Bearer XXXXXX' \
-d '{
{
"sport_id": 150,
"tags": ["free"],
"cellphone_service": 1
}
}'
JSON response:
{
...
"sport_id": 150,
"tags": ["free"],
"cellphone_service": 1
...
}
Adds a sporting activity to a place. Posted tags must be in the allowed list for the sport, and all properties should be in the allowed filters for the sport.
HTTP Request
POST https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/activities
Update an activity
curl -X POST \
https://sportplaces.api.decathlon.com/api/v1/places/9249f4b3-aff8-4e5c-8e76-9c79f4cf7bf3/activities/150 \
-H 'Authorization: Bearer XXXXXX' \
-d '{
{
"sport_id": 150,
"tags": ["free"],
"cellphone_service": 1
}
}'
JSON response:
{
...
"sport_id": 150,
"tags": ["free"],
"cellphone_service": 1
...
}
Updates a sporting activity at a place. Posted tags must be in the allowed list for the sport, and all properties should be in the allowed filters for the sport. The activity must already exist at the location, else a 404 will be returned.
HTTP Request
PUT https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/activities/150
Update multiple activities
curl -X POST \
https://sportplaces.api.decathlon.com/api/v1/places/9249f4b3-aff8-4e5c-8e76-9c79f4cf7bf3/activities \
-H 'Authorization: Bearer XXXXXX' \
-d '{
"activities": [
{
"sport_id": 150,
"tags": ["free"],
"cellphone_service": 1
},
{
"sport_id": 175,
"tags": ["lessons", "free"],
"surface": "ice"
}
]
}'
JSON response:
[
{
...
"sport_id": 150,
"tags": ["free"],
"cellphone_service": 1
...
},
{
...
"sport_id": 175,
"tags": ["lessons", "free"],
"surface": "ice"
...
},
]
Updates multiple sporting activities at a place. Posted tags must be in the allowed list for the sport, and all properties should be in the allowed filters for the sport. If the activities do not exist, they will be created.
HTTP Request
PUT https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/activities
Remove an activity from a place
curl -X DELETE \
https://sportplaces.api.decathlon.com/api/v1/places/9249f4b3-aff8-4e5c-8e76-9c79f4cf7bf3/activities/150 \
-H 'Authorization: Bearer XXXXXX' \
JSON response:
{
"message": "Deleted"
}
Removes a sporting activity from a place based on its sport ID.
HTTP Request
DELETE https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/activities/SPORT_ID
Uploading Pictures to Activities
curl -X POST \
https://sportplaces.api.decathlon.com/v1/places/*:place_id*/activities/*:activity_id*/images \
-H 'Authorization: Bearer XXXXXX' \
-H 'content-type: multipart/form-data' \
-F '=@/path/to/the/image.png'
JSON response:
{
"sport_id": 175,
"tags": ["equipment_rental"],
"photo_reference": "CmRaAAAAN3qk1mKFY6G...",
"user": {
"id": 1,
"first_name": "Decathlon",
"last_name": "Canada",
"staff": true
},
"attributes": {},
"image": {
"url": "https://sportplaces.api.decathlon.com/remote/path/to/the/image.png"
}
}
Pictures can be uploaded to an activity of a place via a file upload form as such.
Only files of the image type are accepted (png, jpg, jpeg, bmp)
Uploads a picture to an activity within a place, based on the place ID and the activity ID.
HTTP Request
POST https://sportplaces.api.decathlon.com/v1/places/:place_id/activities/:activity_id/images
Activity Tags
Get a list of tags on an activity
curl "https://sportplaces.api.decathlon.com/api/v1/places/8b1e3027-e438-42c2-92ab-5ebd23f68d54/activities/160/tags"
JSON response:
[
"free"
]
Retrieves a list of tags that have been applied to a sporting activity at a place
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/tags
Add a tag to an activity
curl -X POST \
https://sportplaces.api.decathlon.com/api/v1/places/8b1e3027-e438-42c2-92ab-5ebd23f68d54/activities/160/tags \
-H 'Authorization: Bearer XXXXXX' \
-d '{
"slug": "lessons"
}'
JSON response:
[
"free",
"lessons"
]
Adds a new tag to a sporting activity at a specified place. This tag MUST be permitted on a sport.
HTTP Request
POST https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/tags
Remove a tag from an activity
curl -X DELETE \
https://sportplaces.api.decathlon.com/api/v1/places/8b1e3027-e438-42c2-92ab-5ebd23f68d54/activities/160/tags/lessons \
-H 'Authorization: Bearer XXXXXX'
JSON response:
{
"message": "Deleted"
}
Removes a specific tag from a sporting activity at a location.
HTTP Request
DELETE https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID/activities/SPORT_ID/tags/lessons
Sports
Get a list of sports
curl "https://sportplaces.api.decathlon.com/api/v1/sports"
JSON response:
{
{
"id": 186,
"name": "Diving",
"tags": [
"free",
"outdoor",
"lessons",
"space_for_children"
],
"filters": [
"size",
"quality"
]
},
...
}
Retrieves a list of all supported Decathlon sports (as defined by Decathlon), plus the allowed tags and filters for each.
The sports are returned in an object consisting of several key/value groups - the keys of which are the Sport IDs in string format.
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/sports
Show details for one sport
curl "https://sportplaces.api.decathlon.com/api/v1/sports/186"
JSON response:
{
"id": 186,
"name": "Diving",
"tags": [
"free",
"outdoor",
"lessons",
"space_for_children"
],
"filters": [
"size",
"quality"
]
}
Retrieves details for one specific sport. Included are the English name, and the allowed tags and filters.
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/sports/SPORT_ID
Sport Filters
Introduction
A filter is associated with a sport place's activity. As opposed to tags which are boolean, their value must be either numerical, or one of the pre-defined string values.
Ex: How long is this kayaking track? becomes What is the value of the distance
filter?
List of available filters
Each filter has to be linked to a sport before being associated with a sport place's activity. Here's the full list of available filters.
Numerical filters
cellphone_service
courts
(number of courts)court_size
difficulty
distance
(meters)duration
(meters)elevation_gain
(meters)equipment
field_size
modality
number_holes
pool_size
quality
ring_size
rink_size
track_size
Filters with string values
age
: Adults, Kids, Teenagerscamping_accomodation
: RV, Tentsseason
: Fall, Spring, Summer, Wintersurface
: clay, sand, etc.swim_area
: Beach, Lake, Open Water, Pooltype_of_place
: club, hospital, hotel, public residence, school
The full list by sport is also available through this dashboard.
Get a list of allowed filters for a sport
curl "https://sportplaces.api.decathlon.com/api/v1/sports/186/filters"
JSON response:
[
"size",
"quality"
]
Retrieves a list of allowed filter names for a particular sport.
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/sports/SPORT_ID/filters
Allow a filter for a sport
curl -X POST \
https://sportplaces.api.decathlon.com/api/v1/sports/186/filters \
-H 'Authorization: Bearer XXXXXX' \
-d '{"slug": "difficulty"}'
JSON response:
[
"size",
"quality",
"difficulty"
]
Adds a new filter to the allowed list for a specified sport.
HTTP Request
POST https://sportplaces.api.decathlon.com/api/v1/sports/SPORT_ID/filters
Sport Tags
Introduction
A tag is associated with a sport place's activity and answers a YES/NO question.
Ex: Does this place offer swimming lessons?
becomes:
Does this place have the swimming
activity with the lessons
tag?
See the activity tags section for a concrete example.
List of available tags
Each tag has to be linked to a sport before being associated with an activity. Here's the full list of available tags.
catering
changing_room
club
court_adjacent_to_others
equipment_rental
flat
floodlight
free
free_parking
grocery_store
hourly_chargeable
indoor
isolated_court
kids-pool
lessons
lifeguard
members_only
open-swim
open-water
outdoor
paid_parking
practice_wall
security
shower
space_for_children
speed
suitable_for_beginners
toilets
washing_equipment
water_fountain
wave
wheelchair_accessible
The full list of sports is also available on this dashboard.
Get a list of allowed tags for a sport
curl "https://sportplaces.api.decathlon.com/api/v1/sports/186/tags"
JSON response:
[
"free",
"equipment_rental",
"lessons",
"outdoor",
"space_for_children",
"lifeguard",
"beach",
"indoor"
]
Retrieves a list of allowed tag names for a particular sport.
HTTP Request
GET https://sportplaces.api.decathlon.com/api/v1/sports/SPORT_ID/tags
Allow a tag for a sport
Not all tags are relevant to all sports. If you want a tag added to a specific sport, you can add it yourself by following the instructions below:
curl -X POST \
https://sportplaces.api.decathlon.com/api/v1/sports/186/tags \
-H 'Authorization: Bearer XXXXXX' \
-d '{"slug": "grocery_store"}'
JSON response:
[
"free",
"outdoor",
"lessons",
"space_for_children",
"grocery_store"
]
HTTP Request
POST https://sportplaces.api.decathlon.com/api/v1/sports/SPORT_ID/tags
The tag needs to be part of the list of available tags above.
Code Samples
Featured apps
Localization
curl
-X PUT
-H "Accept-Language:fr-CA"
-H 'Authorization: Bearer XXXXXX'
-d "@data.json"
"https://sportplaces.api.decathlon.com/api/v1/places/:place_id"
JSON request [@data.json]
{
"notes": "Lorem Ipsumeé"
}
Important bits of our data are localized, since it's meant to be used in multiple countries/locales.
The way to retrieve/post data in a specific locale, such as fr-CA
(Canadian
French), is to send the Accept-Language
header along with your request (See
CURL request above).
Translatable columns can be localized by either making a POST
or a PUT
request, the former along with other required fields to create a place, and the
latter with just the example request object on the right.
Supported locales at the moment are: en, en-GB, fr-FR, fr-CA, pt-PT, pt-BR, es-ES, es-MX, it, de, ja, cn, pl
- Note that default language in our application is English (
en
), any other languages require anAccept-Language
header.
Locales follow the ISO 639-1 convention.
If your locale isn't listed, please get in touch
At this moment the only supported column is notes
for a place. We plan on localizing more data to cater to our users needs.
Standards
GeoJSON Format
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Point",
"coordinates": [
-73.5826985,
45.5119864
]
}
}
Data returned by this API is designed to be compliant with the GeoJSON Format (RFC 7946)
Query parameters are also expected to be compliant with this spec, including all POST
bodies and query string params.
Coordinates are represented in [longitude, latitude, elevation]
groups. In query strings, these MUST be sent as
comma (,
) separated strings consisting only of the longitude
and latitude
elements.
Example: &origin=-73.5826985,45.5119864
Errors
The Sport Places 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 token is invalid or expired. |
404 | Not Found -- The specified place or activity 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. |
Sandboxes
If you're looking for places to play around with these API calls and/or just run tests against your application, you might want to try our sandbox environments:
Staging
URL: https://sportplaces-api-staging.herokuapp.com
This environment is a replica of our production environment, with a representative dataset and fully functional API endpoints
Development (Bleeding-edge)
URL: https://sportplaces-develop.herokuapp.com
This environment is NOT recommended for production. This contains the latest additions to our API and some of them might not yet be ready for usage. Even though most of what's here is soon to be deployed, we cannot guarantee it will continue to work as features are still being tested/developed.
Postman Collection
We've also crafted a set of pre-configured API calls into a Postman collection for you to play with and get familiar with all the endpoints we offer.
The request examples include all possible filter keys and values.
Link: Postman Collection
Roadmap
Upcoming
June 2019
- Auto-approval of sport place additions by partners and ambassadors
- Ability to mark a place as favorited
- Ability to update multiple activities for one sport place in one call
Q3 2019
- Facilitating data imports from multiple sources
- Javascript public widget to display sport places
- Ability to store place slug and search by slug
- Be able to add several activities in one shot
Q4 2019
- Implement Sport Places User Reviews\
- Multi-region deployment to improve quality of service
Changelog
1.3 - Q1 2019
- Eliminate dependency on
google_place_id
and Google Geolocation in general - Use AI to better tailor recommendations based on arbitrary properties.
- Likely models will be: mood-based, weather-based, proximity, user behaviour etc...
- Booking partner integrations (implemention details TBD)
- Storage or URLs for joining events identified by partner APIs
- Retrieval of events at locations as supplied by partner APIs
1.2 - December 2018
- Add ability for users to upload their own photos and videos
- Reorganization of attributes and more explicit data types
- Storage of complex geometry types: lines & polygons
1.1 - August 2018
- Load Google Image Reference on response
- Standardize Sports API to better organize hierarchy
1.0 - April 2018
- List all places using the GeoJSON format
- Filter Places by Sport
- Filter-based Search
- Geolocation-based listing of places
- Places crowdsourcing
- Decathlon Connect Authentication
Contributing
Everyone is encouraged to help improve this project.
We're open to feature requests, doc improvements, big ideas, suggestions and new implementations. We may reward the best contributors with sport-related stuff ;)
Tweet us at @decathlondev
Documentation improvements
Help us improve the documentation by submitting a PR on here
Support
For all suggestions, bug reports and feature requests please feel free to email us at sportplacesapi@decathlon.com