Official API for external tools

  • Hi,


    I am interested in the travian API for external tools that allows other to develop 3rd party tools that can use data provided by travian. All I could find on this forum is this closed post API for external tools


    If anybody know where can I send my request for the api key, or is there any documentation related to this api please replay.


    Thanks

  • I'm a bit in a hurry, because I'm expecting visitors in ~ 10 minutes. So, sorry if it's very short.


    You need to register for the api first. This can be done automatically by calling

    https://worldurl/api/external.…=yoursiteurl&public=false

    This will give you a private and public api key.


    Then you can access the API by calling:

    https://worldurl/api/external.…eApiKey=yourprivateapikey

    or, if you want to fetch an older snapshot:

    https://worldurl/api/external.…ateapikey&date=dd.mm.yyyy

  • So, if you fill all the information, for instance like this:

    https://com4.kingdoms.com/api/…://google.de&public=false

    You will receive a private & public key, as I mentioned:

    Code
    1. {"time":1545683872842,"response":{"privateApiKey":"a1da4fbc71afb08289dacca9f1f266a0","publicSiteKey":"ad5033100a427037ee76954268c1784b"}}

    (Those are different for you, obviously. Don't share your private key. I do it just for demonstration and with a throwaway key.).


    Then you call the second url, after plugging the data in: https://com4.kingdoms.com/api/…c71afb08289dacca9f1f266a0

    The result will be a json encoded string with the following structure:

    Most of the structure should be selfexplainatory.

    • response.gameworld.version is kind of constant, it never changed, it's always "1.0".
    • response.players.externalLoginToken can be used to create a simple registration / login without a password. You have to tell the player your PUBLIC api key, he has to enter it in the travian settings option, where he can create an access to an external tool, and he will get a token then. He tells you his token and you can calculate md5(token . your_private_key) ... if it's the externalLoginToken, he's authentificated as that account successfully.
    • response.players.tribeId is 1 for roman, 2 for teuton and 3 for gaul.
    • response.players.role is 1 for king, 2 for duke, 3 for governor ... and 3 for vice king.
    • response.map.cells.resType is 4446 for a 4-4-4-6 tile, 11115 for a 1-1-1-15 tile, and so on
    • response.map.cells.oasis is either 0 (for no oasis) or a 2 digit number. First digit is the primary resource bonus type (1 = wood, 2 = clay, 3 = iron, 4 = crop) and the second digit is 1, if the oasis has an additional 25% crop bonus and 0 otherwise. So, for instance, 41 = 50% crop bonus, 20 = 25% clay bonus, 21 = 25% clay + 25% crop bonus.
    • response.map.landscape dictionary: key = number, which corresponds to response.fields.landscape and value = relative/path/to/the/landscape/image
      For instance, if value is "layout/images/map/ww_2_2.png", then the image is located at https://cdn.traviantools.net/g…out/images/map/ww_2_2.png . Replace "0.91" with the current game version, if necessary.
    • response.map.radius is the world radius. It may increase if the map is filled well. If this value doesn't change, then no additional cells will be in response.map.cells.

    Values I marked as constant will not change during the gameround.

  • Well, if you have no idea, you probably can't do anything with it either. ^^


    It's the official API of Kingdoms. An API (application programming interface) is an interface, in this case for third party tools (like getter or my site), such that they can legally obtain some ingame information, for instance playernames, population, which village is the player's capital, and so on. Kingdoms' API is updated daily, which means if you want to create a (legal) third party tool for TK, you can use the API to update the ingame information daily. That way you can, for instance, create a inactive finder, which displays all players that didn't gain inhabitants for X days, or whatever.

  • Hi, sorry for bringing up old topics, but I have a question about the API after reading this - API for external tools


    Is the externalLoginToken used only for authenticating in the 3rd party app? The 3rd party can't "see" player-only info like whether he's under attack or not?

  • The externalLoginToken's only purpose is to proof towards the tool page, that you're in fact the owner (or a dual) of the account, you claim to be.


    Me: I'm Be2-e4!

    Tool page: Proof it, here's our public key.

    (I enter the public key ingame and get back the login token)

    Me to Tool page: Here the login token

    Tool page: Ok I believe you


    That's the only purpose. Tool page can't see into your account, no attacks on you, nothing.