Contributing to Decathlon Sport Places API

Previously, we saw how to find places to practice sports in your area. This gives sports tech developers unique data, and lets them focus on building their product.

SportPlaces API lists 187,541 soccer spots worldwide

Since then, we added more than 1,000,000 places which is more than a 15x increase. Here are a few:

• United States ~around 380k new places,
• Great-Britain ~69k new places,
• Brazil ~52k,
• Russia ~32.4k,
• China ~21k,
• Turkey ~13k,
• Chile~8k,
• etc.

Here is a distribution of sport places in logarithmic scale:

Sport Places in big and small countries — from USA to Chile

More places and countries are coming!

Besides places by Decathlon, third-party developers can add their own. Here are a few use cases:

• You know local information, such as the name of the place in your country’s local language. Or it can be as simple as knowing the correct contact information,
• You work on a remote geographic zone that we overlooked,
• You work on an under-represented sport. For example, you have the list of southern Chinese martial arts in your region,
• A gymnasium or an outdoor field is offering now a new sport,

There are other valuable use cases. By inviting all developers to use and enrich the API, we can have together the most complete and up-to-date sport places data.

In these cases, it can be the developer, or end-users who updates the information. Then it is available to the wider public. For those who are working with private data, we are also working on a way to mark an uploaded place as private.

How does it work?

While listing sport places is open, creating and updating requires an API key. This is for security, and also gives you later the ability to retrieve the places you created.

Before, we supported a variety authentication methods such as JSON web token or Decathlon’s own DKConnect. These were complex and needed discussion with our team, with sparse documentation.

We’ve made it simpler with a developer’s web console, which lets you get your own key seamlessly. After creating an account and confirming your email, you can get an API key. You will see you can use this across multiple APIs in minutes.

Use your new API key to authenticate POST/PUT/DELETE requests. For example:

This adds a sport with id 257 to an existing place

We’ve also published an extensive Swagger documentation that gives an overview of the API as well as in-depth detail of every endpoint. Along with the developer console, this is a major effort to increase developer accessibility.

Swagger docs

Walkthrough

Let’s take the example of a developer working on a capoeira mobile app. The developer wants capoeira fans to tag favorite places, such as capoeira style, music and add capoeira graduação events.

Currently, the developer knows only about a few places, through him and friends. He can add these and send invitations to teachers, asking them to register their school to get more places on the map. Capoeira masters are always eager to get new students and spread their craft, so this is a good way to get new places.

Step 1.

First, get the id of the main sport.

Many capoeira schools also offer complimentary activities, such as fitness, Brazilian jiu-jitsu, yoga and dance classes. You can read the previous blog post to get the id of these sports.

Step 2.

Add the school. For example, I’m adding the caopeira brasilieira center in Montreal. I can view the endpoint on Swagger to get parameters details and responses:

This endpoint accepts either GeoJson or a google map id. Using GeoJson format is more flexible and allows you to add any place, as long as you also have a name and country. Instead of GeoJson, sending the place’s google maps id allows us to retrieve key information such as opening hours. These places with enriched information are also much more likely to be reused by other developers. If you have the choice, do use google maps id.

The POST request returns the id of the place that you can save for later use. You can also query /api/v1/places/user to get this id.

Step 3.

In this scenario, capoeira students can also update their school’s details. For example,

You can also use the Decathlon Activities API to register new events such as a new capoeira festival.

Imagine everyone from the community adding new capoeira schools and new events. Other community friends then add cousin sports such as brazilian jiu-jitsu or dance. Soon you become a one-stop shop for the sports community in your city!

DELETE

Remove a place :

The place is then marked as discarded and cannot be found in search. Please use this sparingly, as this might impact other existing applications.

What next?

We have seen that we have reached a significant milestone of more than 1M sport places worldwide. With the sport places API and an API key, it is straightforward to add new sport places and enrich existing places. Crowdsourcing will increase the quantity and quality of the data.

Furthermore, our team is working hard to add new places, with your participation. We hope that a variety of sport tech developers leverage this wealth of data to offer sport apps or integrate it in their own solution, effectively increasing sport accessibility worldwide. We can’t wait to hear what you will do with the Sport Places API!