The NationStates API allows external sites to collect data about the game world. You can access it via your own scripts to gather information and produce extended reports or analysis.
A compendium of the most commonly sought information. If you don't need most of this data, then please use shards (below) instead.
http://www.nationstates.net/cgi-bin/api.cgi?nation=(name)
... where (name) is either the name (e.g. "The Grendels") or ID ("the_grendels") of a nation. Names are not case-sensitive, but spaces should be encoded (i.e. replaced with '+', '%20', or '_').
Request exactly what you want. This is faster for us to generate, and can be used to request data not available from the Standard API.
http://www.nationstates.net/cgi-bin/api.cgi?nation=(name)&q=(shard1)+(shard2)+(...)
... where you can string together as many shards as you like, separated by '+' signs. Available shards are:
name fullname type motto category wa endorsements gavote scvote freedom region population tax animal animaltrait currency flag majorindustry crime sensibilities govtpriority govt govtdesc industrydesc notable admirable founded firstlogin lastlogin lastactivity influence freedomscores publicsector deaths leader capital religion customleader customcapital customreligion rcensus wcensus censusscore censusscore-N* legislation happenings
* To use the censuscore-N shard, replace N with the numberical ID of the census you want. The IDs can be found here or in the URL of Analysis pages (click "Go").
Please do combine shards into a single request, rather than making multiple rapid requests for different shards for the same nation.
Look up data about the game world.
http://www.nationstates.net/cgi-bin/api.cgi?q=(shard1)+(shard2)+(...)
Available shards:
numnations numregions census censusid censussize censusscale censusmedian featuredregion newnations regionsbytag*
* To use the regionsbytag shard, add tag names as ";tags=(tagname1),(tagname2)", with a maximum of 10 tags. This will list all regions that have all of the named tags. For a full list of tag names, see the Tag Cloud.
Look up data about the World Assembly.
http://www.nationstates.net/cgi-bin/api.cgi?wa=council_id&q=(shard1)+(shard2)+(...)
... where council_id is 1 for the General Assembly and 2 for the Security Council. In the case of shards that return data for the overall World Assembly (e.g. numnations), it doesn't matter which ID you use: either ID will return the same result.
Available shards:
numnations numdelegates resolution votetrack* dellog* delvotes* lastresolution
* Shards marked with an asterisk, such as dellog, must be used in conjunction with resolution.
If you need data on large numbers of nations or regions, please don't request them individually from the API. Instead, use a daily dump file, which combines the output from Standard API call for all nations or regions in a single XML file. These are generated once per day at around 22:30 PDT. They are fairly large (approx. 2MB for regions and 15MB for nations) and compressed with gzip.
The advantage of the Daily Dump is it gives you data for far more nations and regions than you can practically retrieve via API calls. The disadvantages are that the data is pre-generated, not up-to-the-second, so can be up to 24 hours old, and it does not include to all shards, only the Standard API data.
Some people use a combination of API calls and dump files. This is a good idea if you want to compare a nation to others in its region. Since regions can contain thousands of nations, it's not practical to request data on all a nation's neighbors at once via the API. Instead, try building region-wide stats (e.g. total region population) using the most recent daily dump, and only drawing on the API for up-to-the-second information on the nation in question.
A list of the 50 most recently created nations.
http://www.nationstates.net/cgi-bin/api.cgi?newnations=1
Note that this information is also available in a slightly different format from the World API, using the newnations shard (see above).
Complete lists of all regions/nations. Please note this information is now available from the Daily Data Dumps, and the API call will be removed in the future.
The API is rate-limited and will temporarily lock you out if you send too many requests within a short period of time. (And return status 421: "Too Many Requests From Your IP Address.")
API Rate Limit: 50 requests per 30 seconds.
Traffic exceeding this rate is automatically banned for 15 minutes, so please try to stay well within it.
If you need to gather information on very large numbers of nations or regions, you should use a Daily Data Dump, not send dozens or hundreds of API queries all at once. It is not feasible to gather data from the API on every nation in a region at once. If you need detailed data on a nation's neighbors, use a Daily Dump.
The Daily Data Dumps are only updated once every 24 hours, and scripts should not download them more frequently.
You must set your script's UserAgent to something informative, such as the URL of your site. This allows us to contact you if something goes wrong with your script, rather than simply banning it.
From time to time, the API may be updated to include new data or change format. If your scripts will regularly contact the server and might stop working when confronted with an unexpected new format, you can make them request a particular API version number. You do this by appending &v=1 to your request, replacing "1" with whichever version number you want.
For example, if the current API version when you write your script is 2, you can send requests like this:
http://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia&v=2
... or this (using shards):
http://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia&q=motto+animal+currency&v=2
... and if the API later changes to version 3, your scripts will continue to receive data in the unchanged version 2 format. This allows you to decide whether the new API version is worth upgrading to, and whether it will break anything, at your leisure.
Check the current API Version here.
If you omit the v parameter, you receive the most recent version of the API.
Note: The Daily Data Dumps are always compiled in the current API version—there is no way to retrieve a Data Dump in an older API version format, sorry. If you use Data Dumps, in order to prevent breakage your script should inspect the version number at the top of the XML file (e.g.: <NATIONS api_version="2">) and abort if it is different than you expect.
Discussion about the API and related tools takes place in the Technical Forum. There is some historical information you may find helpful in this thread.
Some sites using the NationStates API:
Some example scripts for accessing the API: