Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

{{DISPLAYTITLE:Kingdoms API}}<languages/>

Travian provides a [https://en.wikipedia.org/wiki/JSON JSON]-[https://en.wikipedia.org/wiki/Application_programming_interface API] to access some information about running game worlds.<ref>https://forum.kingdoms.com/index.php?thread/4099-api-for-external-tools/</ref><ref>https://forum.kingdoms.com/index.php?thread/21440-official-api-for-external-tools/&postID=149851#post149851</ref>

== Accessing the API ==
The base URL for all queries to the API is <pre>https://&lt;gameworld&gt;.kingdoms.com/api/external.php?action=&lt;action&gt;</pre> (e.g. https:<nowiki />//com1.kingdoms.com/api/external.php?action=...).

=== Parameters ===
Depending on the value of ''action'' further parameters have to be specified. For most requests an [[#Action: requestApiKey |API key]] is required.

=== Response format ===
 ╠═ time : int? : [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#The_ECMAScript_epoch_and_timestamps 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 ===
{| class="wikitable"
| email || 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 ===
{| class="wikitable"
| privateApiKey || string(32) || private api key
|-
| email || 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 [[#Response_format|above]])

== Action: getMapData ==

The response to this action contains all available data including information about players, kingdoms and the map.

=== Parameters ===
{| class="wikitable"
| 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.<ref>https://forum.kingdoms.com/index.php?thread/20863-suggestions-for-the-json-api/&postID=144462#post144462</ref>

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

{| class="wikitable"
! 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/:
<blockquote>
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

<pre>$externalLoginToken = md5($accessToken.$privateApiKey);</pre>

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

== References ==
<references />

Export translations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools