Services return types documentation

Trackmania Forever public API and its open source PHP SDK.

Moderator: NADEO

User avatar
m4rcel
Posts: 653
Joined: 15 Jun 2010, 11:12
Contact:

Services return types documentation

Post by m4rcel » 21 Jun 2011, 16:17

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
Last edited by m4rcel on 25 Jul 2011, 19:27, edited 1 time in total.
ImageImage
Image

tcq
Posts: 2684
Joined: 15 Jun 2010, 11:02
Contact:

Re: [1.0] All return values and their structures

Post by tcq » 21 Jun 2011, 16:47

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

User avatar
gouxim
Nadeo
Nadeo
Posts: 1153
Joined: 14 Jun 2010, 17:20

Re: Services return types documentation

Post by gouxim » 21 Jun 2011, 16:48

That's cool 8-)
I updated the title and sticked the topic.
And also linked on http://code.google.com/p/trackmania-ws-sdk/
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

htbplayer
Posts: 31
Joined: 14 Jun 2011, 15:05

Re: Services return types documentation

Post by htbplayer » 21 Jun 2011, 18:46

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

User avatar
m4rcel
Posts: 653
Joined: 15 Jun 2010, 11:12
Contact:

Re: Services return types documentation

Post by m4rcel » 25 Jul 2011, 19:36

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...
ImageImage
Image

zocka
Posts: 186
Joined: 15 Jun 2010, 17:56

Re: Services return types documentation

Post by zocka » 14 Jan 2013, 07:16

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? :D
Would be quite handy for a current project :/
manialink minigame shatter
my manialink: zockaml
my maniaflash: maniaflash?zocka

User avatar
gouxim
Nadeo
Nadeo
Posts: 1153
Joined: 14 Jun 2010, 17:20

Re: Services return types documentation

Post by gouxim » 14 Jan 2013, 11:00

Language is only handled client-side, so nop unfortunately the API doesn't have any language-related data to offer.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

User avatar
m4rcel
Posts: 653
Joined: 15 Jun 2010, 11:12
Contact:

Re: Services return types documentation

Post by m4rcel » 14 Jan 2013, 21:10

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 ;)
ImageImage
Image

User avatar
gouxim
Nadeo
Nadeo
Posts: 1153
Joined: 14 Jun 2010, 17:20

Re: Services return types documentation

Post by gouxim » 16 Jan 2013, 17:52

Good point, I forgot about that :thumbsup:
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

User avatar
TStarGermany
Posts: 470
Joined: 15 Jun 2010, 11:05
Contact:

Re: Services return types documentation

Post by TStarGermany » 17 Jan 2013, 04:08

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...

Post Reply

Return to “Trackmania Forever Web Services”

Who is online

Users browsing this forum: No registered users and 2 guests