By the Numbers: How to Make Your Own Leaderboard for Mapillary Uploads

You can now build a custom leaderboard for your event or challenge with help of the Mapillary API. Here's how.

Christopher Beddow

12 May 2017

You can now build a custom leaderboard for your event or challenge with help of the Mapillary API. Here's how.

The Mapillary community has sported a number of events throughout the globe, such as the Lesotho competition, mapping the common spaces in Ahmedabad, and a photo walk around the canals in Amsterdam. Recently, a Youthmappers challenge was launched in Uganda, for which we have built a leaderboard and an accompanying map for tracking coverage.

Uganda Mapillary challenge coverage

Whether we are directly or indirectly involved in the event, we’ve seen a demand for custom leaderboards to track progress and foster competition. In response, we have expanded the Mapillary API to support building your own leaderboard. The workflow for this involves a few simple steps.

Get a client ID by registering an application called “My Leaderboard” here: https://www.mapillary.com/app/settings/developers
Make a list of usernames (as many as you like!) to be involved in your competition, best stored in both a comma-separated value list:
```
chrisbeddow,gyllen,quicksand
```

Use our API to build an initial leaderboard list. The call will be like this:

https://a.mapillary.com/v3/leaderboard/images?usernames=chrisbeddow,gyllen,quicksand&client_id=YOURCLIENTID

The output of this API call is a JSON that looks like this:

[{"image_count":306611,"user_key":"Q6aJsEtjqHAEDE0oMFc9Wg","username":"chrisbeddow"},{"image_count":81032,"user_key":"2BJl04nvnfW1y2GNaj7x5w","username":"gyllen"},{"image_count":71601,"user_key":"B256u4hnEdVHHNzStyicxg","username":"quicksand"}]
In this output, you can see that each username has the user_key as well as image_count inside curly brackets. If we had some dates in mind, we can filter by date by adding &start_time= and &end_time= to the URL, with dates in ISO 8601 format.

For a leaderboard between April 1, 2017 and April 30, 2017, we can use:

https://a.mapillary.com/v3/leaderboard/images?usernames=chrisbeddow,gyllen,quicksand&client_id=YOURCLIENTID&start_time=2017-04-01&end_time=2017-04-30

The results of this second call will look different when inspecting the image counts. This is because we just narrowed down the leaderboard to show only the specified date range:

[{"image_count":23631,"user_key":"B256u4hnEdVHHNzStyicxg","username":"quicksand"},{"image_count":9600,"user_key":"Q6aJsEtjqHAEDE0oMFc9Wg","username":"chrisbeddow"},{"image_count":210,"user_key":"2BJl04nvnfW1y2GNaj7x5w","username":"gyllen"}]
We can put this into an HTML document to start making a table with the help of Javascript. In the <head></head> section of your HTML document, let’s make a script that compiles these results into table rows. It will first require that we reference jQuery, then access the API call using jQuery.ajax() method with our API call as the url parameter.
```
<head>
  <script src=https://code.jquery.com/jquery-3.2.1.min.js></script>
</head>
```
The actual jQuery.ajax() method will go in the <body></body> tags of our HTML document.
```
<body>
  <script>
    $.ajax({
    type: "get",
    dataType: "json",
    url: "https://a.mapillary.com/v3/leaderboard/images?usernames=chrisbeddow,gyllen,katrinhumal,quicksand&client_id=YOURCLIENTID&start_time=2017-04-01&end_time=2017-04-30",
    success: function(data) {
      doSomething();
    }
  });
  </script>
</body>
```
In the above, we have accessed the API call, and the JSON we get back—showing user info in curly brackets—is contained in the data variable on the same line as success. This is asking us what we want to do with the JSON once we have it, and I’ve currently put doSomething() as our function. We’ll change this to actually build a leaderboard. The next steps involve pushing the data into an HTML table.
Let’s first add a table with an id="table" between the opening <body> tag and the opening <script> tag (line 2), then make our code push to that table (line 9). The convenient part of this is that the leaderboard already returns the users with the highest number of images first, so we don’t need to sort. We do need to run a for loop, to ensure that we add users from the leaderboard to the table.
If you now preview this HTML document, the output looks like this:
To see a complete code example of this, visit the Mapillary leaderboard Github repo. You can also add some styling to the table to make it look more traditional, using CSS.

With these basics, you can go your own direction, including building this into your own web page, or making a much more expanded leaderboard like the Uganda one above. It’s also possible to use JavaScript to associate each username with a team, and similarly build a second table to get team totals—however, that’s beyond the scope of the Mapillary API and a tutorial for another day.

Uganda leaderboard

Hopefully, this guide has sparked your interest in making custom leaderboards and will help you with your own Mapillary-themed events and competitions! Feel free to reach out to us with additional questions and take a look at our tips on events.

/Chris

Continue the conversation

Twitter LinkedIn Facebook