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.


  • 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


    This will give you a private and public api key.

    Then you can access the API by calling:


    or, if you want to fetch an older snapshot:


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

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


    (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:…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.
    • is 4446 for a 4-4-4-6 tile, 11115 for a 1-1-1-15 tile, and so on
    • 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.
    • 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…out/images/map/ww_2_2.png . Replace "0.91" with the current game version, if necessary.
    • 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

    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.

  • So how we can access account data. Assume i want to create a tool which will notify me via email when an attack incoming. Because on iOS app notifications not work. Is there any stats api endpoint for example legionnaire attack damage etc we can get memory as json. No more enpoints ?

  • You can NOT access the account data legally and there is no way to make an attack notifier legally. On desktop version you get a pretty loud sound if you get attacked and if you have sound enabled though, maybe that helps?

    There are three endpoints of the API:

    1) registering your tool (required for the other two endpoints)

    2) getting the daily updated list of villages, players, kingdoms, alliances, fields and oases (all one endpoint/request)

    3) the mentioned authentification

    There is also no official API endpoint to obtain the data for unit values, however I have a list: tk.units.json

  • Yes, on desktop version it does. But players cant use pc all time. On profile avatar tab there is a section here. Users can give the input our public keys and we can authenticate them via the result key. But if we cant access user spesific data why we should authenticate him? Thank you for json file. Its worth for calculate some logic.

  • But if we cant access user spesific data why we should authenticate him?

    Tool developers can use this feature for something like a "Login via Kingdoms"-login, or to let a Discord-Bot automatically assign roles to a user, if he authenticates as member of the kingdom. Been there, done that.