NationStates API Documentation

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.

Table of Contents

API Methods

  1. Nation API

    1. Standard

      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 '_').

    2. Shards

      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 demonym demonym2 demonym2plural

      * 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.

  2. Region API

    1. Standard

      http://www.nationstates.net/cgi-bin/api.cgi?region=(name)

    2. Shards

      http://www.nationstates.net/cgi-bin/api.cgi?region=(name)&q=(shard1)+(shard2)+(...)

      Available shards:

      name factbook numnations nations delegate delegatevotes gavote scvote founder power flag embassies tags happenings messages* history

      * 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.

  3. World API

    1. Shards

      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 happenings newnations regionsbytag

      To use the regionsbytag shard, add tag names as ;tags=(tagname1),(tagname2), up to a maximum of 10 tags. This will list all regions belonging to any of the named tags. Tags can be preceded by a - to select regions which do not have that tag; for example, like this. For a full list of tag names, see the Tag Cloud.

      The happenings shard can be configured by appending extra parameters:

      You may combine the above; for example, like this.

      The happenings shard has a 28-second delay between a nation doing something and it becoming visible via this API.

  4. World Assembly API

    1. Shards

      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 delegates members happenings memberlog resolution votetrack* dellog* delvotes* lastresolution

      * Shards marked with an asterisk, such as dellog, must be used in conjunction with resolution.

  5. Telegrams API

    The Telegrams API exists to support things that aren't possible using the in-game Mass Telegram system; for example, automatically targeting telegrams at nations with capitalist leanings in regions with more than 50 residents. It's also possible to duplicate what the in-game system offers you via Telegram Stamps, only slower.

    Important Note: You must use this API if you want to send telegrams with a script or browser tool. Using a script or tool to send telegrams from the regular Telegrams page is a violation of our Script Rules, and may lead to deletion of your nation as well as penalties for the region for which you are recruiting.

    Telegram API Rate Limits

    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.)

    Telegrams API Client Key

    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:

    1. The purpose of your script (e.g. to send recruitment TGs, welcome-to-my-region TGs...)
    2. The region your script will be serving
    3. The nation primarily responsible for the script

    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.)

    To send telegrams via the API

    1. If you haven't already, obtain a Telegrams API Client Key, as described above.

    2. Compose your telegram, addressing it to tag:api and click Send. (Tip: When composing, you may wish to make use of the %NATION% macro—see here.)

    3. 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:

      http://www.nationstates.net/cgi-bin/api.cgi?a=sendTG&client=(Client Key)&tgid=(TGID)&key=(Secret Key)&to=(nation_name)

      You must make one API call per recipient. If, for example, you want to send a message to 1,000 recipients, you need to compose the telegram, send it to tag:api, then make 1,000 API calls, spaced sufficiently far apart to abide by the ratelimit, to deliver all copies.

    Never 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.

  6. Authentication API

    This can be used by a third-party website to verify that a user owns a particular nation, without requiring that user to divulge sensitive information.

    Steps:

    1. Ask the user to visit http://www.nationstates.net/page=verify_login and enter the code displayed into your website.

    2. Have your site make a request to:

      http://www.nationstates.net/cgi-bin/api.cgi?a=verify&nation=(Nation Name)&checksum=(code)

    3. The API will return 1 if the checksum code is correct for the specified logged-in nation. If the code is incorrect, or the nation does not exist, or is not currently logged in, the API will return 0.

    The code will expire if the nation logs out, if it performs a significant in-game action such as moving regions or endorsing another nation, and after it is successfully verified.

    The code only allows nation verification by a third party website, and does not provide any extra access to or control over the nation.

    Advanced: Adding a site-specific token

    For additional security, a third-party site can add its own token to the verification process. This means that the generated checksum code will only be valid for that site. Without this, it is possible for a third-party site to use the user's supplied checksum code to impersonate them on a separate third-party site.

    Steps:

    1. Append ?token=(Your token) to the verify_login URL you ask the user to visit, where your token is a string of characters you generate and is unique to that nation. The important thing is that you should be able to re-generate the same token given the same nation name, but nobody else knows how you do it. For example, you might produce an MD5 hash of the nation name using a private key. Your user then fetches their code from this URL: http://www.nationstates.net/page=verify_login?token=(Your token).

    2. Append the same token to your API request:

      http://www.nationstates.net/cgi-bin/api.cgi?a=verify&nation=(Nation Name)&checksum=(code)&token=(Your token)

  7. Daily Data Dumps

    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 of the Standard API 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.

    1. Regions

      http://www.nationstates.net/pages/regions.xml.gz

    2. Nations

      http://www.nationstates.net/pages/nations.xml.gz

    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.

    Daily Dumps from the past are archived here.

  8. Name Lists [obsolete]

    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.

    http://www.nationstates.net/cgi-bin/api.cgi?allregions=1

    http://www.nationstates.net/cgi-bin/api.cgi?allnations=1

Rate Limits

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.

Terms of Use

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.

  1. Set a User Agent

    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.

  2. Do Not Sneakily Exceed Rate Limits

    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.

  3. Be Transparent

    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.

API Versions

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.

NationStates supports the three most recent API versions. Older versions may stop working without notice. For example, if the current API version is 6, then versions 4-6 are all supported, but versions 1-3 are no longer maintained. You may find that an unsupported API version will suddently default to the most recent API version instead.

Help

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.

Examples

Some sites using the NationStates API:

Some example scripts for accessing the API: