The leaderboard-server is a RESTful service which implements an API for submitting data which describes the geolocation stumbling efforts of contributions to the Mozilla Location Service project. Mozilla Stumbler users can submit data to the leaderboard-server about how many networks were detected within a geospatial 'tile' at a given time, and then query the top contributions.
Return the version metadata for the deployed version of the code.
URL
https://location-leaderboard.services.mozilla.com/__version__
Method:
GET
URL Params
None
Data Params
None
Request Headers
None
Success Response:
JSON encoding
{
"commit":
Error Responses:
None
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/__version__",
dataType: "json",
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Return the heartbeat metadata for the deployed heartbeat of the code.
URL
https://location-leaderboard.services.mozilla.com/__heartbeat__
Method:
GET
URL Params
None
Data Params
None
Request Headers
None
Success Response:
Error Responses:
The deployment is unhealthy and unable to connect to the database or host healthy traffic.
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/__heartbeat__",
dataType: "json",
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Get the configuration parameters the server uses to integrate with Firefox Accounts.
URL
https://location-leaderboard.services.mozilla.com/api/v1/fxa/config/
Method:
GET
URL Params
None
Data Params
None
Request Headers
None
Success Response:
JSON encoding
{
client_id:
Error Responses:
None
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/fxa/config/",
dataType: "json",
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Handle a post-authorize redirect from Firefox Accounts back to the leaderboard.
URL
https://location-leaderboard.services.mozilla.com/api/v1/fxa/redirect/
Method:
GET
URL Params
The temporary authentication code provided by Firefox Accounts which must be exchanged for a long lived access token.
Data Params
None
Request Headers
None
Success Response:
JSON encoding
{
leaderboard_uid:
Error Responses:
None
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/fxa/redirect/?code=asdf",
dataType: "json",
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Refresh a Firefox Accounts access token for a new token using a refresh token.
URL
https://location-leaderboard.services.mozilla.com/api/v1/fxa/refresh/
Method:
POST
URL Params
None
Data Params
A long lived Firefox Accounts refresh token retrieved through an Oauth redirect process.
Request Headers
A successful submission must include a valid Firefox Accounts authorization bearer token
Example: Authorization: Bearer kf94k5jsgsl3kj
Success Response:
JSON encoding
{
access_token:
Error Responses:
Code: 400 INVALID
Content: {"detail":"JSON parse error - Expecting object: line 1 column 1 (char 0)"}
Code: 401 UNAUTHORIZED
Content: {"detail":"Unable to determine a valid Firefox Accounts authorization token"}
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/fxa/refresh/?refresh_token=asdf",
dataType: "json",
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Get a list of all countries that have been contributed to, the total number of contributions, and their shapes.
URL
https://location-leaderboard.services.mozilla.com/api/v1/locations/countries/
Method:
GET
URL Params
None
Data Params
None
Request Headers
None
Success Response:
JSON encoding
{
iso2:
Error Responses:
None
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/locations/countries/",
dataType: "json",
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Submit the number of networks detected within a series of tiles for a given contributor.
URL
https://location-leaderboard.services.mozilla.com/api/v1/contributions/
Method:
POST
Data Params
The data submitted in a single POST request describes how many observations were made by a contributor. Each observation is made at a given time and place, however to reduce the size of the data sent, the observations are grouped into 'tiles'. The tile size is requested from the server, and is measured in meters. Observations are then grouped into tiles of that size and summed. Each data point sent describes the coordinates of a point within that tile (the server will round the coordinates provided to the nearest containing tile), and the number of observations made within that tile.
POST body (JSON encoded)
{
items: [
{
time:
time
A UNIX time stamp in seconds that represents the time when the observations for the given tile were made.
The number of meters east from 0,0 in the EPSG 3857 coordinate system
The number of meters north from 0,0 in the EPSG 3857 coordinate system
The number of observations made by the contributor since the last time they submitted to the leaderboard within the specified 1km x 1km tile.
Request Headers
The submission API optionally supports gzipped payloads. To submit a gzipped request, include the gzipped JSON data in the request body and add the header to the request.
Example: Content-Encoding: gzip
A successful submission must include a valid Firefox Accounts authorization bearer token
Example: Authorization: Bearer kf94k5jsgsl3kj
Success Response:
Error Responses:
Code: 400 INVALID
Content: {"detail":"JSON parse error - Expecting object: line 1 column 1 (char 0)"}
Code: 401 UNAUTHORIZED
Content: {"detail":"Unable to determine a valid Firefox Accounts authorization token"}
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/",
dataType: "json",
beforeSend: function(xhr) {
xhr.setRequestHeader('Authorization', 'Bearer fksdf90sek4jk50');
},
data : {
items: [
{
time: 1234567890,
tile_easting_m: -8872100,
tile_northing_m: 5435700,
observations: 100
},
{
time: 1234567890,
tile_easting_m: -8872100,
tile_northing_m: 5435700,
observations: 100
},
{
time: 1234567890,
tile_easting_m: -8892100,
tile_northing_m: 5435700,
observations: 100
}
]
},
type : "POST",
success : function(req) {
console.log(req);
}
});
Get a leader that has contributed, and their rank globally and in each country that they have contributed to.
URL
https://location-leaderboard.services.mozilla.com/api/v1/leaders/profile/<uid: str>/
Method:
GET
GET Params
str
The uid of the contributor.
Success Response:
JSON encoding
{
uid: <str>,
name: <str>,
ranks: [
{
country: {
iso2: <str>,
name: <str>
},
observations: <int>,
rank: <int>
}
]
}
Error Responses:
{"detail":"Not found."}
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/leaders/profile/abcdefg/",
dataType: "json",
data: {
country_id: 1,
}
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Get all leaders that have contributed and set their public display name, sorted by the highest contributions.
URL
https://location-leaderboard.services.mozilla.com/api/v1/leaders/global/
Method:
GET
GET Params
int
Each page contains 20 leaders.
Success Response:
JSON encoding
{
count:
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/leaders/global/?offset=20",
dataType: "json",
data: {
country_id: 1,
}
type : "GET",
success : function(r, data) {
console.log(data);
}
});
Get the leaders for a given Country.
URL
https://location-leaderboard.services.mozilla.com/api/v1/leaders/country/<country_id: str>/
Method:
GET
URL Params
str
A country_id is a 2 letter ISO country code which can be found here.
GET Params
int
Each page contains 20 leaders.
Success Response:
JSON encoding
[
{
uid: <str>,
name: <str>,
observations: <int>,
rank: <int>
}
]
Error Responses:
{"detail":"Unknown country code."}
Sample Call:
$.ajax({
url: "https://location-leaderboard.services.mozilla.com/api/v1/leaders/country/ca/?offset=20",
dataType: "json",
data: {
country_id: 1,
}
type : "GET",
success : function(r, data) {
console.log(data);
}
});