Difference between revisions of "Kingdoms API"
Jump to navigation
Jump to search
(Created page with "<languages/> <translate> {{Kingdoms Topic/en|legends=Legends API}} Travian provides a [https://en.wikipedia.org/wiki/JSON JSON]-[https://en.wikipedia.org/wiki/Application_pr...") |
|||
| (12 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
<translate> | <translate> | ||
| + | <!--T:1--> | ||
{{Kingdoms Topic/en|legends=Legends API}} | {{Kingdoms Topic/en|legends=Legends API}} | ||
| − | 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>. | + | <!--T:2--> |
| + | 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 == | + | == Accessing the API == <!--T:3--> |
The base URL for all queries to the API is <pre>https://<gameworld>.kingdoms.com/api/external.php?action=<action></pre> (e.g. https:<nowiki />//com1.kingdoms.com/api/external.php?action=...). | The base URL for all queries to the API is <pre>https://<gameworld>.kingdoms.com/api/external.php?action=<action></pre> (e.g. https:<nowiki />//com1.kingdoms.com/api/external.php?action=...). | ||
| − | === Parameters === | + | === Parameters === <!--T:4--> |
Depending on the value of ''action'' further parameters have to be specified. For most requests an [[#Action: requestApiKey |API key]] is required. | Depending on the value of ''action'' further parameters have to be specified. For most requests an [[#Action: requestApiKey |API key]] is required. | ||
| − | === Response format === | + | === Response format === <!--T:5--> |
╠═ 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 | ╠═ 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. | ╠═ error : object? : Indicates that an error occured. ''response'' will contain an empty array in this case. | ||
| Line 20: | Line 22: | ||
╚═ response : object | empty array | ╚═ response : object | empty array | ||
| + | <!--T:6--> | ||
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. | 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. | ''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. | The type ''string(int)'' represents an integer that is formatted as a JSON string (surrounded by ") for unknown reasons. | ||
| − | == Action: requestApiKey == | + | == Action: requestApiKey == <!--T:7--> |
An API key can be requested using this action. The key is required for most other requests. | An API key can be requested using this action. The key is required for most other requests. | ||
| − | === Parameters === | + | === Parameters === <!--T:8--> |
{| class="wikitable" | {| class="wikitable" | ||
| email || string(≤255) || valid email address (may be used by Travian staff for questions) | | email || string(≤255) || valid email address (may be used by Travian staff for questions) | ||
| Line 38: | Line 41: | ||
|} | |} | ||
| − | === Response === | + | === Response === <!--T:9--> |
╚═ response | ╚═ response | ||
╠═ privateApiKey : string(32) | ╠═ privateApiKey : string(32) | ||
╚═ publicSiteKey : string(32) | ╚═ publicSiteKey : string(32) | ||
| − | == Action: updateSiteData == | + | == Action: updateSiteData == <!--T:10--> |
This action can be used to update the data that was provided in the original ''requestApiKey'' request. | This action can be used to update the data that was provided in the original ''requestApiKey'' request. | ||
| − | === Parameters === | + | === Parameters === <!--T:11--> |
{| class="wikitable" | {| class="wikitable" | ||
| privateApiKey || string(32) || private api key | | privateApiKey || string(32) || private api key | ||
| Line 59: | Line 62: | ||
|} | |} | ||
| − | === Response === | + | === Response === <!--T:12--> |
╚═ response | ╚═ response | ||
╚═ data : boolean : always true (in case of an error, an error object is used instead as descried [[#Response_format|above]]) | ╚═ data : boolean : always true (in case of an error, an error object is used instead as descried [[#Response_format|above]]) | ||
| − | == Action: getMapData == | + | == Action: getMapData == <!--T:13--> |
| − | The response to this action contains | + | <!--T:14--> |
| + | The response to this action contains all available data including information about players, kingdoms and the map. | ||
| − | === Parameters === | + | === Parameters === <!--T:15--> |
{| class="wikitable" | {| class="wikitable" | ||
| privateApiKey || string(32) || private api key | | privateApiKey || string(32) || private api key | ||
| Line 73: | Line 77: | ||
| 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) | | 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 data near midnight | + | 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 === <!--T:16--> |
╚═ response | ╚═ response | ||
╠═ gameworld : object | ╠═ gameworld : object | ||
| Line 91: | Line 95: | ||
╠═ kingdomId : string(int) : "0" for no kingdom | ╠═ kingdomId : string(int) : "0" for no kingdom | ||
╠═ treasures : int : if player is king, then number of treasures of the kingdom, otherwise 0 | ╠═ treasures : int : if player is king, then number of treasures of the kingdom, otherwise 0 | ||
| − | ╠═ role : int : 0 = Governor, 1 = King, 2 = Duke, 0 if not part of any kingdom | + | ╠═ role : int : 0 = Governor, 1 = King, 2 = Duke, 3 = Vice King, 0 if not part of any kingdom |
| − | ╠═ externalLoginToken : string : see [[#Authentication using publicSiteKey]] | + | ╠═ externalLoginToken : string : see [[#Authentication using publicSiteKey|Authentication using publicSiteKey]] |
╚═ villages : array | ╚═ villages : array | ||
╠═ villageId : string(int) | ╠═ villageId : string(int) | ||
| Line 112: | Line 116: | ||
╠═ x : string(int) | ╠═ x : string(int) | ||
╠═ y : string(int) | ╠═ y : string(int) | ||
| − | ╠═ resType : string : if cell is abandoned valley or village, then resource distribution (e.g. "4446"), otherwise "0" = wilderness, "1" = outside of map radius | + | ╠═ 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 oasis, then oasis type | + | ╠═ oasis : string(int) : if cell is an oasis, then [[#Oases oasis type], otherwise "0" |
| − | ╠═ landscape : string(int) : landscape id, see [[#Landscapes]] | + | ╠═ 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 | ╚═ 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 | ╚═ landscapes : object | ||
| − | ╚═ [ landscape id : int ] : string : relative path to the corresponding image (e.g. "layout/images/map/wood0_0_0.png"), see [[#Landscapes]] | + | ╚═ [ landscape id : int ] : string : relative path to the corresponding image (e.g. "layout/images/map/wood0_0_0.png"), see [[#Landscapes|Landscapes]] |
| − | ==== Landscapes ==== | + | ==== Oases ==== <!--T:26--> |
| + | |||
| + | <!--T:27--> | ||
| + | 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. | ||
| + | |||
| + | <!--T:28--> | ||
| + | {| class="wikitable" | ||
| + | ! ID !! Type | ||
| + | |- | ||
| + | | 1 || wood | ||
| + | |- | ||
| + | | 2 || clay | ||
| + | |- | ||
| + | | 3 || iron | ||
| + | |- | ||
| + | | 4 || crop | ||
| + | |} | ||
| + | |||
| + | <!--T:29--> | ||
| + | Examples: | ||
| + | "20" is a 25% clay oasis. | ||
| + | "21" is a 25% clay and 25% crop oasis. | ||
| + | "41" is a 50% crop oasis. | ||
| + | |||
| + | ==== Landscapes ==== <!--T:17--> | ||
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 | 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 == | + | == Authentication using publicSiteKey == <!--T:18--> |
| + | <!--T:19--> | ||
From https://forum.kingdoms.com/index.php?thread/4099-api-for-external-tools/: | From https://forum.kingdoms.com/index.php?thread/4099-api-for-external-tools/: | ||
<blockquote> | <blockquote> | ||
With the ''externalLoginToken'' you can authenticate a player - without that the player needs to register for your tool. | With the ''externalLoginToken'' you can authenticate a player - without that the player needs to register for your tool. | ||
| + | <!--T:20--> | ||
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. | 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. | ||
| + | <!--T:21--> | ||
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 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. | ||
| + | <!--T:22--> | ||
If the player enters the ''accessToken'' on your site, you can calculate the players ''externalLoginToken'' by | If the player enters the ''accessToken'' on your site, you can calculate the players ''externalLoginToken'' by | ||
| + | <!--T:23--> | ||
<pre>$externalLoginToken = md5($accessToken.$privateApiKey);</pre> | <pre>$externalLoginToken = md5($accessToken.$privateApiKey);</pre> | ||
| + | <!--T:24--> | ||
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. | 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> | </blockquote> | ||
| − | == | + | == References == <!--T:25--> |
<references /> | <references /> | ||
</translate> | </translate> | ||
Latest revision as of 17:49, 17 April 2020
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.
