Services return types documentation

[m4rcel]

The current version of the SDK still lacks on detailled information about the return values and their structure. So I take the opportunity to write all of these information into a nice post. Therefore you will find all methods currently available through the SDK and the return values of each of them below. (As TrackMania\WebServices\Foobar is only for testing purposes, this class does not appear in this overview. And as \TrackMania\WebServices\Exception is very intuitive, this class does neither appear.)
If several methods of a class have the same structure in their return value, they have been grouped together and their return structure is listed only once. Whenever an object appears in the return value, the available fields are given with their datatype and what they are standing for.
If you find any errors, please feel free to contact me via PM. I will update the post as soon as I find the time to do so


Current version: 2.0 Beta 2 (25.07.2011)


TrackMania\WebServices\ManiaHome

• bookmarkButton($manialink, $manialinkName = null, $manialinkImage = null)
  Returns: string - The XML ManiaLink code of the button
• sendNotificationFromManialink($message, $link = null, $iconStyle = null, $iconSubStyle = null)
• sendPublicNotificationToPlayer($playerLogin, $message, $link = null, $iconStyle = null, $iconSubStyle = null)
• sendPrivateNotificationToPlayer($playerLogin, $message, $link = null)
  Returns: boolean - true on success, false on error

TrackMania\WebServices\Manialinks

• get($code)
  Returns: object containing the following fields:
  • code: string - The code of the ManiaLink, equals $code
  • url: string - The URL of the ManiaLink
  • login: string - The login of the owner of this ManiaLink
  • coppersCost: int - The coppers cost of this ManiaLink

TrackMania\WebServices\MultiplayerRankings

• getPlayerRanking($path = 'World', $environment = 'Merge', $offset = 0, $length = 10)
  Returns: object containing the following fields:
  • idZone: int - The ID of the zone
  • path: string - The path of the zone, equals $path
  • environment: string - The environment of the ranking, equals $environment, "Merge" on overall ranking
  • unit: string - Always "Ladder Points"
  • players: array of object, each element containing the following fields:
    • rank: int - The rank of the player
    • points: float - The points of the player
    • player: object containing the following fields:
      • id: int - The unique ID of the player
      • login: string - The login of the player
      • nickname: string - The nick of the player, including the $-formattings
      • united: boolean - True if this login is a TMUF account, false if this login is a TMNF account
      • path: string - The path of the player, zones are seperated with |
      • idZone: int - The ID of the player's zone
• getZoneRanking($path = 'World', $offset = 0, $length = 10)
  Returns: object containing the following fields:
  • environment: string - The environment of the ranking, equals $environment, "Merge" on overall ranking
  • unit: string - Always "Ladder Points"
  • path: string - The path of the zone, equals $path
  • idZone: int - The ID of the zone
  • zones: array of object, each element containing the following fields:
    • points: float - The points of the zone
    • zone: object containing the following fields:
      • id: int - The ID of the zone
      • name: string - The name of the zone
      • path: string - The path of the zone

TrackMania\WebServices\Players

• get($login)
  Returns: object containing the following fields:
  • id: int - The unique ID of the player
  • login: string - The login of the player, equals $login
  • nickname: string - The nick of the player, including the $-formattings
  • united: boolean - True if this login is a TMUF account, false if this login is a TMNF account
  • path: string - The path of the player, zones are seperated with |
  • idZone: int - The ID of the player's zone
• getNicknameHTML($login)
  Returns: string - The nick of the player, formatted as HTML
• getTags($login)
  Returns: array of object, each element containing the following fields:
  • url: string - The URL to the image of the tag
• getMultiplayerRanking($login)
• getMultiplayerRankingForEnvironment($login, $environment)
• getSoloRanking($login)
  Returns: object containing the following fields:
  • environment: string - The environment of this ranking, "Merge" for overall rankings
  • unit: string - "Ladder Points" on Multiplayer rankings, "Skill Points" on Solo rankings
  • points: float - The points of the player
  • ranks: array of object, each element containing the following fields:
    • idZone: int - The ID of the zone
    • path: string - The path to the zone
    • rank: int - The rank in this zone

TrackMania\WebServices\Registrations

• getPlayersCount()
  Returns: int - The number of currently registrated players

TrackMania\WebServices\Servers

• get($login)
  Returns: object containing the following fields:
  • login: string - The login of the server, equals $login
  • name: string - The name of the server, including the $-formattings
  • path: string - The path where the server is located

TrackMania\WebServices\SoloRankings

• getPlayerWorldRanking($offset = 0, $length = 10)
• getPlayerRanking($path, $offset = 0, $length = 10)
  Returns: object containing the following fields:
  • idZone: int - The ID of the zone
  • path: string - The path of the zone
  • environment: string - The environment of the ranking, "Merge" on overall ranking
  • unit: string - Always "Skill Points"
  • players: array of object, each element containing the following fields:
    • rank: int - The rank of the player
    • points: int - The points of the player
    • player: object containing the following fields:
      • id: int - The unique ID of the player
      • login: string - The login of the player
      • nickname: string - The nick of the player, including the $-formattings
      • united: boolean - True if this login is a TMUF account, false if this login is a TMNF account
      • path: string - The path of the player, zones are seperated with |
      • idZone: int - The ID of the player's zone
• getPlayerWorldRankingForChallenge($challengeUID, $offset = 0, $length = 10)
• getPlayerRankingForChallenge($challengeUID, $path, $offset = 0, $length = 10)
  Returns: object containing the following fields:
  • idZone: int - The ID of the zone
  • path: string - The path of the zone
  • challengeUID: string - The unique ID of the challenge, equals $challengeUID
  • gameMode: string - The game mode of the Challenge
  • unit: string - Always "Score"
  • players: array of object, each element containing the following fields:
    • rank: int - The rank of the player
    • points: int - The points of the player
    • player: object containing the following fields:
      • id: int - The unique ID of the player
      • login: string - The login of the player
      • nickname: string - The nick of the player, including the $-formattings
      • united: boolean - True if this login is a TMUF account, false if this login is a TMNF account
      • path: string - The path of the player, zones are seperated with |
      • idZone: int - The ID of the player's zone

TrackMania\WebServices\Zones

• get($id)
• getByPath($path)
  Returns: object containing the following fields:
  • id: int - The ID of the zone
  • name: string - The name of the zone
  • path: string - The path of the zone
• getAll($offset = 0, $length = 10, $sort = '', $order = '')
• getChildren($id, $offset = 0, $length = 10, $sort = '', $order = '')
• getChildrenByPath($path, $offset = 0, $length = 10, $sort = '', $order = '')
  Returns: array of object, each element containing the following fields:
  • id: int - The ID of the zone
  • name: string - The name of the zone
  • path: string - The path of the zone
  • pathIds: string - A comma separated list of the Zone-IDs, beginning with the World-Zone, ending with the Zone's parent
• getId($path)
  Returns: int - The ID of the zone

TrackMania\WebServices\OAuth2\Client

• getLoginURL($scope = null, $redirectURI = null)
  Returns: string - The URL to login the user into his or her TrackMania account
• getLogoutURL($redirectURL)
  Returns: string - The URL to logout the user from his or her TrackMania account

TrackMania\WebServices\OAuth2\Player

• getPlayer()
  Returns: object containing the following fields:
  • id: int - The unique ID of the player
  • login: string - The login of the player
  • nickname: string - The nick of the player, including the $-formattings
  • united: boolean - True if this login is a TMUF account, false if this login is a TMNF account
  • path: string - The path of the player, zones are seperated with |
  • idZone: int - The ID of the player's zone
• getBuddies()
  Returns: array of object, each element containing the following fields:
  • id: int - The unique ID of the buddy
  • login: string - The login of the buddy
  • nickname: string - The nick of the buddy, including the $-formattings
  • united: boolean - True if this login is a TMUF account, false if this login is a TMNF account
  • path: string - The path of the buddy, zones are seperated with |
  • idZone: int - The ID of the buddy's zone
• getEmail()
  Returns: string - The Email of the player, entered on account registration
• isOnline()
  Returns: boolean - True if the user is currently logged in, false if not

[tcq]

Nice work, well done. This is, how you make it understandable

[gouxim]

That's cool
I updated the title and sticked the topic.
And also linked on http://code.google.com/p/trackmania-ws-sdk/

[htbplayer]

Big thanks to you Marcel really nice work. Now i can find out who has stolen my maniacode

[m4rcel]

I updated the first post to match the current Version 2.0 Beta 2. There were nearly no changes in the existing classes, so I think it does not hurt having the new overview, although the current version is still Beta

The changes in detail:

• Classes are now listed with their namespace, as introduced in version 2.0.
• The two new classes TrackMania\WebServices\OAuth\Client and ...\Player have been added, helpful for those already testing with the new SDK version
• Wherever the field "united" appeared for a player, I changed its datatype to boolean, which fits more imo. (In the end, everything is actual a string ^^)
• Fixed some mistakes, some "idZone" where stated as "id" and vice versa.
• Some methods of ...\Zones do now have a pathIds field, having the IDs of their parents.

I don't know, if I maybe should add sth. like "Introduced in v2.0" for the new classes and the one new field, to help those working with the old version of the SDK...

[zocka]

In case someone still followes this thread:

Is there a way to get a player´s language? like there doesn´t seem to be something returning this bit $_GET["lang"] from the addplayerid.
As alternative: is there any ressource about which zone has wich language or has maybe even someone written such a function?
Would be quite handy for a current project :/

[gouxim]

Language is only handled client-side, so nop unfortunately the API doesn't have any language-related data to offer.

[m4rcel]

You can get the language of the client (i.e. Maniaplanet) with $_SERVER['HTTP_ACCEPT_LANGUAGE']. If the player uses the English version, this value will be set to "en", if he uses the German version, it will be "de", and so on

[gouxim]

Good point, I forgot about that

[TStarGermany]

Out of curiosity : Is there some way to find out when a player was 1st registered ?
Would be nice to have something like "TM member since 2008-Jul-1st" or so...