Hey,
I've got a few suggestions regarding Kingdom's JSON-API for external tools.
Documentation
There is some documentation in API for external tools but unfortunately that info is outdated (there are still alliances) and the formatting is broken, probably since the forum software switch. While this isn't a huge problem as the most important stuff is still correct and everything else can be figured out by trying things out, a good documentation would make development a lot easier. In addition, it shouldn't take much time to solve this, as the API doesn't have many features (yet). Btw, what's the point of the "version" field as this seems to stay at "1.0" forever even though the API has changed?
Global API
After reading this thread, I think there should be some global API where one can query an overview of all the worlds currently running or starting soon.
Bugs
While working with the API I've encountered two bugs:
1. Sometimes the result of getMapData contains invalid data. In this case, a player has a kingdom id, but the corresponding kingdom does not exist in the result. I've done a quick research on this and in 5 of 5 cases, the corresponding player was shown deleted in gettertools. So I guess this is somewhat related to players deleting (or getting removed because of inactivity) while being king. If needed, I can provide some examples.
2. There seems to be a problem related to timezones. I requested the map data at multiple times around 0:00 on MLTEST. The first column contains the date and time at which I sent the query in CEST / GMT+2. The second column contains the requested date from the API (GET-Parameter "date"). The third column contains the relevant excerpt from the response and the last column contains the "date" field of the response in a readable format in UTC.
Query Time (CEST) | Queried date | Response | "date" (UTC) |
08.10. 21:55 | 07.10. | "lastUpdateTime":"1538949901","date":1538870400 | 2018-10-07T00:00:00+00:00 |
08.10. | empty | ||
08.10. 22:29 | 07.10. | "lastUpdateTime":"1538949901","date":1538870400 | 2018-10-07T00:00:00+00:00 |
08.10. | empty | ||
09.10. 00:00 | 07.10. | "lastUpdateTime":"1538863501","date":1538784000 | 2018-10-06T00:00:00+00:00 |
08.10. | "lastUpdateTime":"1538949901","date":1538870400 | 2018-10-07T00:00:00+00:00 | |
09.10. 00:08 | 07.10. | "lastUpdateTime":"1538863501","date":1538784000 | 2018-10-06T00:00:00+00:00 |
08.10. | "lastUpdateTime":"1538949901","date":1538870400 | 2018-10-07T00:00:00+00:00 | |
09.10. | "lastUpdateTime":"1539036301","date":1538956800 | 2018-10-08T00:00:00+00:00 | |
10.10. | empty | ||
09.10. 01:58 | 07.10. | "lastUpdateTime":"1538863501","date":1538784000 | 2018-10-06T00:00:00+00:00 |
08.10. | "lastUpdateTime":"1538949901","date":1538870400 | 2018-10-07T00:00:00+00:00 | |
09.10. | "lastUpdateTime":"1539036301","date":1538956800 | 2018-10-08T00:00:00+00:00 | |
10.10. | empty | ||
09.10. 02:10 | 07.10. | "lastUpdateTime":"1538949901","date":1538870400 | 2018-10-07T00:00:00+00:00 |
08.10. | "lastUpdateTime":"1539036301","date":1538956800 | 2018-10-08T00:00:00+00:00 | |
09.10. | empty | ||
10.10. | empty |
The highlighted numbers show the problem pretty well. Between 0:00 and 2:00 CEST (22:00 and 0:00 UTC) the date in the response is one day off the requested date.
Greetings,
iTob