NationStates API Documentation

The NationStates API allows external sites to collect data about the game world. You can access it with your own scripts to gather information and produce extended reports or analysis. It is faster than scraping regular HTML pages, easier on our servers, and the data format is guaranteed not to change unexpectedly. Please post feedback and questions in the API forum thread.

If your script interacts with regular NationStates pages, rather than this API, please read the Script Rules.

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.

      ... where (name) is the name of a nation (e.g. "The Grendels" or "the_grendels"). Names are not case-sensitive, but spaces in URLs generally need to be encoded, i.e. replaced with + or %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.

      ... where you can string together as many shards as you like, separated by + signs. Available shards are:

      admirable animal animaltrait banner* banners* capital category census** crime currency customleader customcapital customreligion deaths demonym demonym2 demonym2plural dispatches dispatchlist endorsements factbooks factbooklist firstlogin flag founded freedom fullname gavote gdp govt govtdesc govtpriority happenings income industrydesc influence lastactivity lastlogin leader legislation majorindustry motto name notable poorest population publicsector rcensus region religion richest scvote sectors sensibilities tax tgcanrecruit*** tgcancampaign*** type wa wcensus zombie****

      * banner: Returns one Rift banner code that should be displayed for this nation: the nation's primary banner, if one is set; otherwise a randomly chosen eligible banner. The banners shard returns a list of Rift banners that should be displayed: the nation's primary banner (if any) is always listed first, with the remainder in random order. Banner codes can be converted into image URLs by prepending "/images/banners/" and appending ".jpg".

      ** census: By default, returns the score, rank, and region rank on today's featured World Census scale. Can be optionally configured with additional parameters:

      • scale=(census ID/s): Specify the World Census scale(s) to list, using numerical IDs. The IDs can be found here or in the URL of World Census pages. Separate multiple scales with +. For all scales, use all.
      • mode=(name/s): Specify the data you want, separating multiple modes with +.
        • score: Raw value
        • rank: World rank (e.g. "334" means 334th in the world)
        • rrank: Region rank
        • prank: World rank as a percentage (e.g. "15" means "Top 15%")
        • prrank: Region rank as a percentage
        • history: This is a special mode that cannot be combined with other modes, as only scores are available, not ranks. When requesting history, you can optionally specify a time window, using Unix epoch times:

      *** tgcanrecruit / tgcancampaign: Returns 0 if the nation currently blocks all Recruitment / Campaign telegrams; otherwise 1.

      **** zombie: For use during Z-Day (October 31), when NationStates is traditionally overrun with zombies.

      If you are looking for the Number of WA Endorsements, use q=census;scale=66;mode=score or count the entries returned by endorsements.

      Where possible, please combine multiple shards into a single request, rather than making multiple requests for different shards for the same nation.

  2. Region API

    1. Standard

    2. Shards

      Available shards:

      census* censusranks* delegate delegateauth** delegatevotes embassies embassyrmb*** factbook flag founder founderauth** gavote happenings history messages**** name nations numnations officers** poll power scvote tags zombie*****

      * For details, see the Nation shard census / the World shard censusranks.

      ** Authorities are represented by letter codes:

      • X: Executive
      • W: World Assembly
      • A: Appearance
      • B: Border Control
      • C: Communications
      • E: Embassies
      • P: Polls

      *** embassyrmb: Return status is:

      • 0: No embassy posting
      • con: Delegates & Founders of embassy regions
      • off: Officers of embassy regions
      • com: Officers of embassy regions with Communications authority
      • all: All residents of embassy regions

      **** messages: Returns the 10 most recent messages posted on the regional message board. You can add offset=(number) to skip the most recent (number) messages. To interpret the STATUS of a post:

      • 0: A regular post
      • 1: Post is suppressed but viewable. In this case, there will also be a SUPPRESSOR field with the name of the nation who suppressed the post.
      • 2: Post was deleted by the author and is not viewable.
      • 9: Post was suppressed by a moderator and is not viewable.

      ***** See the nation zombie shard for details.

  3. World API

    1. Shards

      Look up data about the game world.

      Available shards:

      census* censusid censusdesc** censusname** censusranks** censusscale** censustitle** dispatch dispatchlist*** featuredregion happenings**** nations newnations numnations numregions poll regions regionsbytag*****

      * census: See the nation shard for details.

      ** censusname, censusscale, etc: Return information on the day's featured World Census ranking by default. You can optionally specify a scale by adding scale=(ID number).

      ** censuranks: Accepts an optional parameter start=(rank number).

      *** dispatchlist: Configure by appending optional extra parameters:

      You can combine the above, e.g. Best ever Factbook:History dispatches.

      Full individual dispatches (including text) can be looked up with the dispatch shard.

      **** happenings: Configure by appending optional 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.

      ***** regionsbytag: You can 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.

  4. World Assembly API

    1. Shards

      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.

      Available shards:

      numnations numdelegates delegates members happenings memberlog proposals 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.)

    If you attempt to send telegrams faster than this, your request will fail, and the response will include a 'Retry-After' header with information on when you can try again successfully. There is no penalty for trying too soon, although each request does count toward your overall API Rate Limit.

    The Telegrams API Rate Limit works by checking the amount of time that has passed since your last successful request. For example, if you sent a telegram via the API 60 seconds ago, you can now successfully send a non-recruitment telegram (since 60 is greater than 30), but not a recruitment telegram (since 60 is less than 180).

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


    1. Ask the user to visit and enter the code displayed into your website.

    2. Have your site make a request to: 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.

    Adding a site-specific token

    For additional security, a third-party site can optionally 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.


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

    2. Append the same token to your API request: Name)&checksum=(code)&token=(Your token)

    Combining authentication with shards

    You can combine authentication with a request for nation data into a single call by appending &q=(shard). In this case, the result of the authentication (1 or 0) is returned within <VERIFY> tags as XML: Name)&checksum=(code)&q=(shard1)+(shard2)+(...)

  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. 3MB for regions and 23MB for nations) and compressed with gzip.

    1. Regions

    2. Nations

    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 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 has moved to the World API shards nations and regions, and is also available in Daily Data Dumps.

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 make a request while rate-banned, you will receive response status 429 and the header 'Retry-After: n', where n is the number of seconds until you can make another request.

A "request" is an HTTP request to the site for any amount of information and any number of shards. That is, an HTTP request like this is a single request, even though it gathers information on three shards.

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. If you don't set a UserAgent, you will receive response status 403 "Forbidden" and some explanatory text.

  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:

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

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 two most recent API versions. Older versions may stop working without notice. For example, if the current API version is 6, then versions 5 and 6 are supported, but versions 1-4 are no longer maintained. You may find that an unsupported API version will suddently default to the most recent API version instead. Historically, each API version has remained current for 6-12 months.


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 and libraries you can use to access the NationStates API:

Visual Basic .NET