Kingdoms API
This article is about a feature in Travian Kingdoms. For information on the 
Travian: Legends counterpart visit Legends API.
Travian provides a JSON-API to access some information about running game worlds.[1][2]
Contents
Accessing the API
The base URL for all queries to the API is
https://<gameworld>.kingdoms.com/api/external.php?action=<action>
(e.g. https://com1.kingdoms.com/api/external.php?action=...).
Parameters
Depending on the value of action further parameters have to be specified. For most requests an API key is required.
Response format
╠═ time : int? : javascript timestamp (miliseconds since January 1, 1970, UTC), only present for some actions ╠═ error : object? : Indicates that an error occured. response will contain an empty array in this case. ╠═ type : string ╠═ number : int : error id ╚═ message : string ╚═ response : object | empty array
A question mark after a type indicates that this property is optional. object refers to the JSON meaning of the term (similar to dictionaries or maps in other languages). In the following sections, only the contents of the response object are shown. string(≤255) resp. string(32) indicates a string with a maximum resp. fixed length. The type string(int) represents an integer that is formatted as a JSON string (surrounded by ") for unknown reasons.
Action: requestApiKey
An API key can be requested using this action. The key is required for most other requests.
Parameters
| string(≤255) | valid email address (may be used by Travian staff for questions) | |
| siteName | string(≤255) | name of the tool |
| siteUrl | string(≤255) | URL of the tool |
| public | boolean | whether the tool should be available to the public (and may be used by Travian to create e.g. a tool list in the future) |
Response
╚═ response ╠═ privateApiKey : string(32) ╚═ publicSiteKey : string(32)
Action: updateSiteData
This action can be used to update the data that was provided in the original requestApiKey request.
Parameters
| privateApiKey | string(32) | private api key |
| string(≤255) | valid email address (may be used by Travian staff for questions) | |
| siteName | string(≤255) | name of the tool |
| siteUrl | string(≤255) | URL of the tool |
| public | boolean | whether the tool should be available to the public (and may be used by Travian to create e.g. a tool list in the future) |
Response
╚═ response ╚═ data : boolean : always true (in case of an error, an error object is used instead as descried above)
Action: getMapData
The response to this action contains all available data including information about players, kingdoms and the map.
Parameters
| privateApiKey | string(32) | private api key |
| date | string? | may be specified to request old data, the newest available data is returned if omitted, format is DD.MM.YYYY (e.g. 31.12.2020) |
The API has a bug when querying map data near midnight that leads to data for the wrong day getting returned.[3]
Response
╚═ response
╠═ gameworld : object
╠═ name : string : (e.g. "com1")
╠═ startTime : int : unix timestamp (seconds since January 1, 1970, UTC)
╠═ speed : int
╠═ speedTroops : int
╠═ lastUpdateTime : string(int) : unix timestamp, exact timestamp when returned data was generated
╠═ date : int : unix timestamp, start of the day (00:00:00) of returned data
╚═ version : string : always "1.0"
╠═ players : array
╠═ playerId : string(int)
╠═ name : string
╠═ tribeId : string(int) : 1 = Roman, 2 = Teuton, 3 = Gaul
╠═ kingdomId : string(int) : "0" for no kingdom
╠═ treasures : int : if player is king, then number of treasures of the kingdom, otherwise 0
╠═ role : int : 0 = Governor, 1 = King, 2 = Duke, 3 = Vice King, 0 if not part of any kingdom
╠═ externalLoginToken : string : see Authentication using publicSiteKey
╚═ villages : array
╠═ villageId : string(int)
╠═ x : string(int)
╠═ y : string(int)
╠═ population : string(int)
╠═ name : string
╠═ isMainVillage : boolean
╚═ isCity : boolean
╠═ kingdoms : array
╠═ kingdomId : string(int)
╠═ kingdomTag : string : name of the kingdom
╠═ creationTime : string(int) : unix timestamp, exact time of kingdom creation
╚═ victoryPoints : string(int)
╚═ map
╠═ radius : string(int) : current radius of the map
╠═ cells : array
╠═ id : string(int)
╠═ x : string(int)
╠═ y : string(int)
╠═ resType : string : if cell is an abandoned valley or village, then resource distribution (e.g. "4446"), otherwise "0" = wilderness, "1" = outside of map radius
╠═ oasis : string(int) : if cell is an oasis, then [[#Oases oasis type], otherwise "0"
╠═ landscape : string(int) : landscape id, see Landscapes
╚═ kingdomId : string(int) / int : kingdom id (as string) of the village (not kingdom of the village's owner), 0 (as int) if not within kingdom borders
╚═ landscapes : object
╚═ [ landscape id : int ] : string : relative path to the corresponding image (e.g. "layout/images/map/wood0_0_0.png"), see Landscapes
Oases
An oasis type consists of 2 digits. The first determines the main resource of the oasis according to the table below. If the second digit is a 1 the oasis has an addition 25% crop bonus, otherwise there is no secondary bonus.
| ID | Type |
|---|---|
| 1 | wood |
| 2 | clay |
| 3 | iron |
| 4 | crop |
Examples: "20" is a 25% clay oasis. "21" is a 25% clay and 25% crop oasis. "41" is a 50% crop oasis.
Landscapes
Landscapes are the visualizations used on the ingame map (e.g. trees, mountains, lakes, clay pits). A landscape's id can be mapped to an image path using the landscapes object in the response. This path is relative to the static game files which can be found at https://cdn.traviantools.net/game/0.95/ for that specific version of the game. Example path: https://cdn.traviantools.net/game/0.95/layout/images/map/wood0_0_0.png
Authentication using publicSiteKey
From https://forum.kingdoms.com/index.php?thread/4099-api-for-external-tools/:
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$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.
