NationStates API Documentation

The NationStates API helps scripts and bots interact with the site. It is faster than scraping regular HTML pages, easier on our servers, and the data format is guaranteed not to change unexpectedly. It is also the only way to legally automatically perform certain actions, such as sending telegrams and answering issues.

If your script interacts with regular HTML NationStates pages instead of using this API, you are bound by a bunch of special rules: Please read these Script Rules for HTML site.

If you're just getting started, you might want to use a pre-written wrapper rather than interact with this API directly! See Examples: Wrappers.

Please post feedback and questions in the API forum thread.

Table of Contents

API Methods

Nation API

  1. Standard

    A compendium of the most commonly sought information. If you don't need most of this data, please use shards (below) instead.

    https://www.nationstates.net/cgi-bin/api.cgi?nation=(name)

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

    https://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. Public shards provide information on any nation in the world and don't require authentication. They are:

    admirable animal animaltrait banner* banners* capital category census** crime currency customleader customcapital customreligion dbid deaths demonym demonym2 demonym2plural dispatches dispatchlist endorsements factbooks factbooklist firstlogin flag founded foundedtime freedom fullname gavote gdp govt govtdesc govtpriority happenings income industrydesc influence lastactivity lastlogin leader legislation majorindustry motto name notable policies poorest population publicsector rcensus region religion richest scvote sectors sensibilities tax tgcanrecruit*** tgcancampaign*** type wa wabadges 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 1 if the nation will receive a telegram of this type, and 0 if not (because it has blocked recruitment TGs, for example, or is a Class nation). You may optionally supply from=(region_name) which allows the check to also examine whether nations will deny a telegram from that region in particular due to having received one too recently.

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

  3. Private Shards

    These provide access to information that can only be viewed by a logged-in nation, such as its telegrams or issues. They follow the exact same format as public shards, and indeed you can mix and match public and private shards in a single request. However, any request that includes a private shard must authenticate (see below). They are:

    dossier* issues issuesummary nextissue nextissuetime notices* ping** rdossier* unread

    * notices by default displays only new (unread) notices, as well as notices less than 48 hours old, just like on the regular site. For more notices, supply the optional parameter from=(timestamp), where (timestamp) is a Unix epoch time.

    ** ping is ideal for when you don't want to do anything except register a login, to prevent the nation from ceasing to exist due to inactivity.

    Authenticating For Private Shards

    In order to access a private shard, you must:

    1. Connect via HTTPS (not HTTP)

    2. Include one or more of the following headers:

      • X-Pin An integer like: 1234567890

      • X-Password A string like: hunter2

      • X-Autologin A string like: rjK,CEu9b6T5A45zkvHtA

    For example, if Testlandia's password were "hunter2", you could use curl to retrieve its unread notifications like this:

    curl -H "X-Password: hunter2" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia&q=unread"

    This example also sets a UserAgent, which is mandatory, and identifies your script to us.

    The authentication process works like this:

    A flowchart of API authentication process. Requests with a valid PIN always succeed, while other requests may throw a 409 Conflict error.

    The first time you access a private shard, you will probably provide X-Password, since that's all you know. It's fine to keep doing this for all requests in some circumstances, such as if you are running your own script on your own computer, which only makes one request every so often. However, you may want to switch to X-Autologin, which is an encrypted version of your password, to avoid having to store it anywhere in plaintext. Whenever you authenticate with X-Password, the server response will include an X-Autologin header with the code you need, which will work until the nation's password is changed.

    If you plan on making multiple requests for private shards in quick succession for the same nation, you need to use X-Pin. This is a session identifier, created when the nation logs in, and persisting until it logs out or goes idle for two hours. Whenever you authenticate with either X-Password or X-Autologin, the server response will include an X-Pin header with the number you need. This number will work until the nation logs out.

    The advantage of X-Pin is it skips the heavy authentication checks that are required when a nation logs in, allowing you to quickly make multiple requests. Without this, you may encounter a 409 Conflict error, which is triggered when a nation attempts to log in via the API despite having successfully logged in very recently (within a few seconds). To make multiple requests in a short period of time, then, your script should first authenticate with X-Password or X-Autologin, note the value of the X-Pin header returned, and for future requests supply that in your own X-Pin header.

    You can supply one, two, or all three authentication headers with each request, and these will be processed as shown by the flowchart above—notably, X-Pin will always be used first if it's valid.

    The Gotcha: Logging in cancels any existing session, invalidating its Pin. This means that if you have a script running in the background while also browsing NationStates manually, the two will fight each other, with a request from one logging out the other. This can go unnoticed in your browser, assuming you have autologin turned on, because you don't realize you are silently reauthenticating with each click. But you will notice it via the API because too-frequent logins generate a 409 Conflict error.

    This will also happen if you have multiple scripts that don't share Pins. If each one only keeps track of its own session, then a request from one will invalidate the Pin of the other.

  4. Private Commands

    Private Commands allow your nation to do things, such as answer issues. They are very similar in practice to Private Shards, but are for taking action, rather than simply gathering information.

    You must authenticate for Private Commands in the exact same way as for Private Shards.

    Available Private Commands:

    • issue: Address an Issue

      To answer an issue, you must supply an Issue ID number and an Option ID number. Both of these are provided by the issues Nation Private Shard. To dismiss an issue, rather than select an option, specify an Option ID number of -1.

      Note that Option ID numbers begin counting at zero.

      Example: To enact legislation in Testlandia for Issue ID #111 using Option ID #2:
      curl -H "X-Password: hunter2" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=issue&issue=111&option=2"

      This command will return XML describing the result of the passed legislation. It may include these XML elements: OK ERROR DESC RANKINGS UNLOCKS RECLASSIFICATIONS NEW_POLICIES REMOVED_POLICIES

Region API

  1. Standard

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

  2. Shards

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

    Available shards:

    census* censusranks* dbid delegate delegateauth** delegatevotes dispatches embassies embassyrmb*** factbook flag founded foundedtime founder founderauth** gavote happenings history lastupdate messages**** name nations numnations officers** poll power scvote tags wabadges 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 messages posted on a regional message board. By default, returns the 10 most recent messages, sorted from oldest to newest. Accepts additional optional parameters:

    • limit=(maximum number of messages): Return this many messages. Must be in the range 1-100.
    • offset=(number): Skip the most recent (number) messages.
    • fromid=(post ID number): Instead of returning the most recent messages, return messages starting from this post ID.

    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.

World API

  1. Shards

    Look up data about the game world.

    https://www.nationstates.net/cgi-bin/api.cgi?q=(shard1)+(shard2)+(...)

    Available shards:

    banner1 census2 censusid censusdesc3 censusname3 censusranks3 censusscale3 censustitle3 dispatch dispatchlist4 faction5 factions5 featuredregion happenings6 lasteventid nations newnations numnations numregions poll regions regionsbytag6 tgqueue

    1 banner: Supply a comma-separated list of banner IDs with banner=(list)

    2 census: See the nation shard for details.

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

    3 censusranks: Accepts an optional parameter start=(rank number).

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

    5 faction and factions are only available during N-Day, when nations are conducting nuclear exchanges.

    6 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. This is reflected in the id of the event shown through lasteventid: the lasteventid shard shows the event id of the last event currently available through the happenings shard.

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

World Assembly API

  1. Shards

    Look up data about the World Assembly.

    https://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 council_id you use: either will return the same result.

    Available shards:

    numnations numdelegates delegates members happenings proposals resolution voters* votetrack* dellog* delvotes* lastresolution

    * Shards marked with an asterisk, such as dellog, are only available when used in conjunction with resolution for the current at-vote resolution.

    You can also specify a resolution with id:

    https://www.nationstates.net/cgi-bin/api.cgi?wa=(council_id)&id=(resolution_id)&q=resolution

    If you omit id, you will get information on the current at-vote resolution.

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:

(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 'X-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:

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

Verification 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 https://www.nationstates.net/page=verify_login and enter the code displayed into your website.

  2. Have your site make a request to:

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

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.

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: https://www.nationstates.net/page=verify_login?token=(Your token).

  2. Append the same token to your API request:

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

Combining verification with shards

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

https://www.nationstates.net/cgi-bin/api.cgi?a=verify&nation=(Nation Name)&checksum=(code)&q=(shard1)+(shard2)+(...)

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

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

  2. Nations

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

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

As per the Telegrams API documentation, an additional limit applies when sending TGs.

Scraping

The API is designed to support scripts that need to fetch small amounts of real-time data quickly. If instead you need large amounts of world-wide or historical data, e.g. a region's entire Regional Message Board, or information from thousands of nations at once, you should not flood us with API requests.

In particular, it is not feasible to use the API to gather data on every nation in a region at once. If you need region-wide stats that can only be gathered by examining nations, you should compile these from Daily Data Dumps rather than dozens/hundreds/thousands of real-time API requests. For example, if your script wants to allow users to compare their nation's Civil Rights to the rest of the region:

The Daily Data Dumps are only updated once every 24 hours, and scripts should not download them more frequently.

If you must use the API for scraping historical data that isn't contained in Daily Dumps, please do so at a rate well below the maximum, e.g. 1 request per second. Please also respect copyright.

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 or your e-mail address. It can be whatever you want, so long as it 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.

    Check your UserAgent here.

  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:

https://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia&v=2

... or this (using shards):

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

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 & Wrappers

Projects

Some notable sites and projects that use the NationStates API:

Wrappers

These are unofficial libraries and wrappers that make it easier to access the API, since they take care of the details of making a connection and parsing results.

Simple Examples

How to connect directly to the API and fetch data.