The API is the Application Programming Interface where the Godville server provides access to some data about goddesses, gods, heroines, and heroes that can be used to write third-party programs.
The API data is available in JSON format:
Replace 'GodName' with the name of the god.
It was previously also available in XML format via the URL http://godvillegame.com/gods/api/Godville.xml, but that format is deprecated and the XML url now returns the same JSON-format output.
In its current form, it supplies only a basic set of information about the hero of the god, about the same amount as the personal page.
The data is updated every minute, so pulling it from the server more often than that is pointless. If requests for the data are made too often (there is a limit, "no more than 30 requests per 10 minutes in a bundle (god + ip)" as a result of the incident described below) data is no longer returned about the hero and you are notified. In addition, there used to be an extended API available only with a private key, but this is no longer available.
|JSON key list|
|max_health||Number||Hero maximum health||Yes|
|inventory_max_num||Number||Maximum size of inventory||Yes|
|clan||String||Name of guild||Yes|
|bricks_cnt||Number||Gold bricks collected for temple (max 1000)||Yes|
|wood_cnt||Number||Gopher wood logs collected (if applicable)||Yes|
|temple_completed_at||String||Timestamp of temple completion (if applicable)||Yes|
|pet||Object||See table below||Yes|
|ark_completed_at||String||Timestamp of ark completion (if applicable)||Yes|
|savings_completed_at||String||Timestamp of savings completion (if applicable)||Yes|
|ark_f||Number||Fenimals in the ark (if applicable)||Yes|
|ark_m||Number||Manimals in the ark (if applicable)||Yes|
|arena_won||Number||Duels won in the arena||Yes|
|arena_lost||Number||Duels lost in the arena||Yes|
|savings||String||Savings towards retirement (max "30M")||Yes|
|t_level||Number||Hero-trader trader levels (if applicable)||Yes|
|shop_name||String||Hero-trader shop name (if applicable)||Yes|
|boss_name||String||Lab boss name (if applicable)||Yes|
|boss_power||Number||Lab boss power (if applicable)||Yes|
|inventory||Empty object||This always contains an empty object.||Yes|
|gold_approx||Empty string||This always contains an empty string.||Yes|
|pet_name||String||Pet name and personality ("Name “Personality”"). A KO'd pet name includes “❌”.|
|pet_class||String||Pet monster type|
|pet_level||Number||Pet levels (if applicable)|
Many moons ago in the first year of Godville, great controversy erupted over the discovery that certain overly-competitive guilds (who will remain unnamed here) had been using the API to effectively spy on members of other guilds (at the time, nobody knew about the API).
Since the API provides access to details normally not accessible (most notably, the health of a god's hero and their current status), members of these guilds could use the API to stalk gods (using things like the Godville chrome extension although the ability to use it to track other gods has since been removed as the API was edited by admin following the incident) and then send their heroes to the arena at the same time that the god being stalked sent their hero to the arena too, ensuring that the heroes would meet in combat. They 'farmed' players, using bots to keep track of them and having found through trial and error when certain players slept, taking advantage of this in the arena (being able to face someone who would not use any influences). This enabled the best gladiators of a guild to gang up on enemies as well as artificially inflate their number of duel wins to dominate the pantheon of gladiatorship (although some players would use alternative accounts to do this too).
A large argument ensued over whether using a tool that nobody else knew about (for a use that the admin did not know of since it was a tool they had not endorsed at all) to gain an unfair advantage over other players counted as cheating or not. Since the admin fixed the problem, it probably did count as cheating. Either way, the argument eventually fizzled out after a lot of shouting (having only got so big in the first place because most of the people involved were at the top of their guild hierarchies) as everyone got bored of it.
The argument also centered around the fact that the guilds in question had been using the API to elevate their positions in secret pantheons not visible through any other means (in order to 'conquer' them), since it was discovered that the API let people see the positions of heroes in these hidden pantheons (they were lying dormant as remnants from the 'Russian Godville template' and those in the know reckoned they would eventually be revealed with their guilds dominating them straight away but most of them have now been officially 'revealed' anyway).
One of the main arguments is available on the forum ("Arena, challenges and more - oh my!") for anyone to see but there's not much point. It is just important that such a disregard for the stochastic and fair philosophy of the game is not repeated, but it cannot be denied that this was a very entertaining period of Godville history nevertheless.
- Information on the extended private API key can be found on the Russian Godville wiki.
- Items in this list are all marked as public, as the private API is not available in the English-language Godville. Additional, non-public, items are available using the private API system on Russian-language Godville.