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.
... 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.
... 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
Please do combine shards into a single request, rather than making multiple rapid requests for different shards for the same nation.
* By default the messages shard returns the last 10 messages posted on the regional message board. The shard allows an offset to be specified by adding ";offset=(offset)", which will cause the last (offset) messages to be skipped. In that case the messages shard returns the 10 messages posted before the offset.
Look up data about the game world.
* 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. Tags can be preceded by a "-" to select regions which do not have that tag. For a full list of tag names, see the Tag Cloud.
Look up data about the World Assembly.
... 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.
* Shards marked with an asterisk, such as dellog, must be used in conjunction with resolution.
The Telegrams API exists to support things that aren't possible using the in-game Mass Telegram system; e.g. automatically sending a welcome a telegram to nations that enter your region. It's also possible to duplicate what the in-game system does, only slower, to avoid having to buy Telegram Stamps.
The Telegrams API imposes an additional rate limit:
Recruitment TGs: 1 telegram per 180 seconds
Non-recruitment TGs: 1 telegram per 30 seconds
(These rate limits may change in the future.)
Unlike the rest of the API, to use the Telegrams API you need an API Client Key. Currently, you can do this by lodging a Help Request with the moderators, describing:
API Client Keys are tied to a particular region, and each region may only have one (although they can be revoked and re-issued). Multiple people and scripts within a region can use the same API Client Key. If they do, they will be bound by the same rate limit: that is, when anyone uses the API Client Key to send a recruitment telegram, no-one else using the same API Client Key will be able to send more messages until the rate limit expires.
Once approved, a moderator will telegram you an API Client Key, which you can use for future API calls.
You are responsible for all use of your Telegrams API Client Key. If you suspect that it is not being used appropriately, please immediately contact the moderators.
(This process is still being developed and may change in the future. It is currently mostly geared around the idea of using the Telegrams API to send recruitment telegrams for a particular region, and may be confusing to people wishing to do other things as well. If you are unsure, please file a Help Request or post in the Technical Forum.)
If you haven't already, obtain a Telegrams API Client Key, as described above.
Compose your telegram, addressing it to tag:api and click Send. (You may also wish to make use of the %NATION% macro, which auto-expands into the name of each recipient.)
Your telegram will be registered as an API template, and you will be shown instructions on how to deliver it. This entails noting two pieces of information: its TGID and its Secret Key. You can then use these to make API calls to:
Do not share your telegram's Secret Key, as this will allow others to send your telegram to the recipients of their choice. You are responsible for all usage of your keys.
If you need to look up your telegram's TGID or Secret Key again, it can be found in the Delivery Reports section of your telegram, in your Sent Items folder.
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.
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 429: "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.
As per the Telegrams API documentation, an additional limit applies when sending TGs.
Generally, you can use the API however you like, and if you try to do something that isn't allowed, your request will simply be denied. For example, there's no punishment for exceeding the rate limit; it simply won't work.
There are, however, a few basic rules you must follow, or we may remove your access to the API or the site in general.
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.
You must not deliberately attempt to avoid being rate-limited, e.g. by splitting your API requests across different IP addresses so that they appear to come from different people, or using puppet nations to obtain multiple Telegrams API Client Keys in order to send telegrams faster.
You must not present deceptive or misleading information, e.g. spoofing an IP address, setting a misleading User Agent, obtaining an API Client Key under false pretenses.
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:
... or this (using shards):
... 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.
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.
Some sites using the NationStates API:
Some example scripts for accessing the API: