From GodWiki
Jump to navigation Jump to search

The API is the Application Programming Interface where the Godville server provides access to some data about gods, goddesses, heroes, and heroines that can be used to write third-party programs.

The API data is available in JSON format:

http://godvillegame.com/gods/api/GodName.json (example)

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)"[citation needed] 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.[1]

JSON key list
Key Data type Description Public[2]
name String Hero name Yes
godname String God name Yes
gender String Hero gender Yes
level Number Hero level Yes
max_health Number Hero maximum health Yes
inventory_max_num Number Maximum size of inventory Yes
motto String Hero motto Yes
clan String Name of guild Yes
clan_position String Guild rank Yes
alignment String Hero personality 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 object
Key Data type Description
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.


  1. Information on the extended private API key can be found on the Russian Godville wiki.
  2. 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.