Sport Places API

Get started

The Sport Places API can help you build sport-related applications requiring sport places. Here are a few steps to get you started:

1. Sign up as an API User to receive important communications (mandatory).

To keep our API Users happy, we will want to make sure we can inform about amazing upgrades or important changes.

2. Learn how authenticate.

To get a client_id and JWT Tokens, go to Authentication

3. Make your first API Call!

You are ready to go! We suggest you make your first API Call calling the sport places around you. Let's start with Sport Places.

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"

{
    "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",
                "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"

{
    "type": "Feature",
    "properties": {
        "uuid": "488c45cf-2d7c-4903-9477-01249966adcf",
        "name": "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.

HTTP Request

GET https://sportplaces.api.decathlon.com/api/v1/places/PLACE_UUID

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

{
  "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..."
}

{
    "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

{
  "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.

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
email	`'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`

{
    "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.

{
  "featured": true
}

{
    "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

{
  "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 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.

{
  message: "Deleted"
}

HTTP Request

GET https://sportplaces.api.decathlon.com/api/v1/places/pending

Request Parameters

This GET request accepts no parameters.

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.

{
    "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 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"

[
    {
        "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
  }
}'

{
    ...
    "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
  }
}'

{
    ...
    "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"
      }
    ]
}'

[
    {
        ...
        "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' \

{
    "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'

{
  "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"

[
    "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"
  }'

[
    "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'

{
    "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"

{
    {
        "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"

{
    "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
court_size
difficulty
distance
duration
elevation_gain
equipment
field_size
modality
number_holes
pool_size
quality
ring_size
rink_size
track_size

Filters with string values

age: Adults, Kids, Teenagers
camping_accomodation: RV, Tents
season: Fall, Spring, Summer, Winter
surface: clay, sand, etc.
swim_area: Beach, Lake, Open Water, Pool
type_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"

[
    "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"}'

[
    "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"

[
  "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"}'

[
    "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

Basic Javascript App displaying Badminton facilities

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"

{
  "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 an Accept-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.

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 ;)

Twitter

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