Get surrounding records for a score

Headers:

• Authorization: nadeo_v1 t={token} An access token for the NadeoLiveServices audience

Path parameters:

• {groupUid} string The ID of the group/season *
• {mapUid} string The UID of the map *
• {lower} integer The amount of records to return that are lower than the requested score *
  Maximum: 1
• {upper} integer The amount of records to return that are higher than the requested score *
  Maximum: 1

Query parameters:

• {score} integer The score/time (in milliseconds) to get surrounding records for
• {onlyWorld} boolean Whether to only retrieve records from the world leaderboard
• {zoneId} string The desired zone to get records for

Remarks:

• The groupUid "Personal_Best" can be used to get the global leaderboard.
• When using a different groupUid, make sure you’re only referencing currently open leaderboards. Maps with closed leaderboards will result in an empty response.
• The lower and upper parameters used to support more than 1, but now no more than one upper and one lower record is returned.
• This endpoint can sometimes include a delay due to leaderboard calculations happening in the background.
• If there exist multiple leaderboard entries with the same score as is being passed, the position returned may be inaccurate.
• This endpoint returns precise positions for the first 100,000 records - anything beyond that is not available at the same level of detail.
• When authenticated through a Ubisoft user account that has a zone assigned, the response will include multiple entries in the tops array - one for each of the account’s assigned sub-zones (representing the leaderboards of the continent, country, city, etc.). Use onlyWorld to only retrieve data for the global leaderboard.
• This endpoint’s response always includes the requested score as a fake record (using the requester’s account information for the accountId and zone data) between the surrounding ones. This is because in-game this endpoint is used to determine surrounding records for your own PB (that might not have fully uploaded to the leaderboards yet), so it supports an arbitrary score value that the game sets based on your PB.
• If the authenticated account has a record on the requested map, no scores lower than that record can be requested - it’s recommended to use this endpoint with an account that does not have any records.
• When using a Ubisoft account, the score parameter may be omitted to retrieve the player’s PB leaderboard position and its surrounding data. When the authenticated player doesn’t have a PB on the requested map (or when using a dedicated server account), any request without a score parameter will return an empty object ({}).
• If the map author has set a secret threshold score for their map, this endpoint will not return any actual score values for some entries. Instead, those leaderboard entries will contain -1 in the score field.
• If using onlyWorld=true, the zoneId will be ignored.
• See the zones endpoint for available zone IDs.

Example request:

GET https://live-services.trackmania.nadeo.live/api/token/leaderboard/group/Personal_Best/map/mVkXbeiVyQQXIIJhVQcmiwlGDL8/surround/1/1?score=60785

Example response:

{
  "groupUid": "Personal_Best",
  "mapUid": "mVkXbeiVyQQXIIJhVQcmiwlGDL8",
  "tops": [
    {
      "zoneId": "301e1b69-7e13-11e8-8060-e284abfd2bc4",
      "zoneName": "World",
      "top": [
        {
          "accountId": "2a13aa7d-992d-4a7c-a3c5-d29b08b7f8cb",
          "zoneId": "30228671-7e13-11e8-8060-e284abfd2bc4",
          "zoneName": "Sweden",
          "position": 29,
          "score": 60783
        },
        {
          "accountId": "924598eb-c042-4f12-a189-b7f03c4b83b2",
          "zoneId": "301ff90f-7e13-11e8-8060-e284abfd2bc4",
          "zoneName": "Stuttgart",
          "position": 30,
          "score": 60785
        },
        {
          "accountId": "794a286c-44d9-4276-83ce-431cba7bab74",
          "zoneId": "302012a4-7e13-11e8-8060-e284abfd2bc4",
          "zoneName": "Duisburg",
          "position": 31,
          "score": 60797
        }
      ]
    }
  ]
}

If the groupUid is invalid (or the referenced leaderboard is closed), the response will be an empty object:

{}

If the map does not exist, the response will be based off an empty leaderboard (i.e. it only shows the requested score):

{
  "groupUid": "Personal_Best",
  "mapUid": "mVkXbeiVyQQXIIJhVQcmiwlGDL8_fake",
  "tops": [
    {
      "zoneId": "301e1b69-7e13-11e8-8060-e284abfd2bc4",
      "zoneName": "World",
      "top": [
        {
          "accountId": "caa61df0-7222-492b-8e39-a23ef67a36bd",
          "zoneId": "301e1b69-7e13-11e8-8060-e284abfd2bc4",
          "zoneName": "World",
          "position": 1,
          "score": 60785
        }
      ]
    }
  ]
}