Login

Pinned API for external tools

By using our site, you accept the use of cookies to make your visit more pleasant, to offer you advertisements and contents tailored to your interests, to allow you to share content on social networks, and to create visit statistics for website optimization. More information.

  • API for external tools

    Hello Tool Developers,

    here are some details about the replacement api for our "map.sql".

    In general, the access point for you is http://[gameworld]/api/external.php

    Before you can get data from our api's you need to get an api key from us.

    So first Api is to get this api key:

    General Response Format:


    Every response a json encoded object.

    {
    requestId : string
    error: optional object with more information about the error
    response: api-response
    }

    1. requestApiKey

    You need to call this first, to get an privateApiKey / publicSiteKey. With this privateApiKey you can make further calls to our api's.

    Action:

    requestApiKey

    Parameters:

    email : String (max 255): Needs to be a valid email [should be one where we can reach you if we have some questions]
    siteName: String (max 255): Name of the tool
    siteUrl : String (max 255): Url of the tool - needs to be a valid url
    public : bool : If you set it to true, that means we maybe include your tool in a tool list.

    Response:


    Source Code

    1. privateApiKey : string

    Source Code

    1. [FONT=Verdana] publicSiteKey : string[/FONT]


    2. updateSiteData

    You can call this if you want to update some data of your tool.

    Action:

    updateSiteData

    Parameters:

    privateApiKey : String : Your private Api Key ( you retrieved via requestApiKey)
    email : String (max 255): Needs to be a valid email [should be one where we can reach you if we have some questions]
    siteName: String (max 255): Name of the tool
    siteUrl : String (max 255): Url of the tool - needs to be a valid url
    public : bool : If you set it to true, that means we maybe include your tool in a tool list.

    Response:

    true if everything correct

    3. getMapData

    To get all public map data (old map.sql) from a specific date

    Action:

    getMapData

    Parameters:

    privateApiKey : String : Your private Api Key ( you retrieved via requestApiKey)
    date : String (optional) : Needs to be a date in format: d.m.Y (e.g. 27.08.2014). If no date is present, the today will be used.

    Response:

    Source Code

    1. gameworld

    Source Code

    1. [FONT=Verdana] name: string[/FONT]
    2. [FONT=Verdana] startTime: int[/FONT]
    3. [FONT=Verdana] speed: int[/FONT]
    4. [FONT=Verdana] speedTroops: int[/FONT]
    5. [FONT=Verdana] lastUpdateTime: int[/FONT]
    6. [FONT=Verdana] date : int[/FONT]
    7. [FONT=Verdana] version : string[/FONT]
    8. [FONT=Verdana]players[/FONT]
    9. [FONT=Verdana] playerId : int[/FONT]
    10. [FONT=Verdana] name : string[/FONT]
    11. [FONT=Verdana] tribeId : int[/FONT]
    12. [FONT=Verdana] kingdomId : int[/FONT]
    13. [FONT=Verdana] allianceId : int[/FONT]
    14. [FONT=Verdana] treasures: only >0 when this is a king[/FONT]
    15. [FONT=Verdana] role: int: 1 = King, 2=General, 3=Govenor[/FONT]
    16. [FONT=Verdana] externalLoginToken: string[/FONT]
    17. [FONT=Verdana] villages[/FONT]
    18. [FONT=Verdana] villageId: int[/FONT]
    19. [FONT=Verdana] x: int[/FONT]
    20. [FONT=Verdana] y: int
    21. [/FONT][FONT=Verdana] name: string[/FONT]
    22. [FONT=Verdana] population: int[/FONT]
    23. [FONT=Verdana] isMainVillage: boolean[/FONT]
    24. [FONT=Verdana] isCity: boolean[/FONT]
    25. [FONT=Verdana]alliances[/FONT]
    26. [FONT=Verdana] allianceId: int[/FONT]
    27. [FONT=Verdana] nameShort: string[/FONT]
    28. [FONT=Verdana] nameLong: string[/FONT]
    29. [FONT=Verdana] victoryPoints: int[/FONT]
    30. [FONT=Verdana] population: int[/FONT]
    31. [FONT=Verdana] creationTime: int[/FONT]
    32. [FONT=Verdana]map[/FONT]
    33. [FONT=Verdana] radius: int[/FONT]
    34. [FONT=Verdana] cells: [/FONT]
    35. [FONT=Verdana] id: int[/FONT]
    36. [FONT=Verdana] x: int[/FONT]
    37. [FONT=Verdana] y: int[/FONT]
    38. [FONT=Verdana] resType: string[/FONT]
    39. [FONT=Verdana] oasis: int[/FONT]
    40. [FONT=Verdana] landscape: string[/FONT]
    41. [FONT=Verdana] kingdomId: int[/FONT]
    Display All



    What is the "externalLoginToken" ?
    With the "externalLoginToken" you can authenticate a player - without that the player needs to register for your tool.

    In your call to requestApiKey you were provided a privateApiKey and a publicSiteKey. The privateApiKey should be.. guess what.. private. You shouldn't tell this to anyone. You will need it to make requests to our api's. In contrast your publicSiteKey can be public.

    If a player wants to log-in to your site, he needs first an accessToken for your site. The player needs your publicSiteKey. The player can go to its Settings-Page in T5 and under point "External Tools" click on "Create Access". He enters your publicSiteKey and get an accessToken back.

    If the player enters the accessToken on your site, you can calculate the players externalLoginToken by

    Source Code

    1. $externalLoginToken = md5($accessToken.$privateApiKey);


    Now you can search the player in your player table generated with the data from getMapData and - if you found him - log him into your site.