Docs
Open Lodol
DocumentationIntegrationsAPI

NationStates

App · Gaming · 20 actions

Access NationStates' keyless public data API: look up nations and regions, World Census statistics and leaderboards, the World Assembly (General Assembly and Security Council), dispatches, polls, regional message boards, world happenings, trading cards, and login verification. No account or API key required.

Actions

ActionWhat it does
Get cardGet a single trading card by its id and season.
Get card collectionGet a trading card collection by its id, including the cards in it.
Get card deckGet a nation's trading card deck: the cards it owns plus a summary of its bank, deck value, and rank.
Get dispatchGet a single dispatch by its id, including its full text.
Get nationLook up public data about a nation.
Get nation censusGet one or more World Census statistics for a nation (e.g. Economy, Civil Rights, Influence), as raw scores and/or world and regional rankings.
Get pollGet a regional poll by its id, including its current results.
Get regionLook up public data about a region.
Get region census leaderboardGet a region's leaderboard for a World Census statistic: the nations in that region ranked by that statistic, 20 at a time.
Get regional message boardRead posts from a region's Regional Message Board (RMB), newest last.
Get World Assembly dataGet data about a World Assembly council (General Assembly or Security Council): member and delegate counts, lists, current proposals, the last resolution, and recent happenings.
Get World Assembly resolutionGet a World Assembly resolution with its voting detail.
Get world census leaderboardGet the world-wide leaderboard for a World Census statistic: every nation ranked by that statistic, 20 at a time.
Get world dataGet world-wide data: the total number of nations and regions, the featured region, the newest nations, and the latest event id.
Get world happeningsGet the global feed of recent happenings (events).
List card auctionsList the trading cards currently up for auction.
List dispatchesList dispatches (published factbooks, bulletins, and more).
List nation card collectionsList the trading card collections a nation has created.
List regions by tagFind regions by their tags.
Verify nation loginConfirm that someone controls a nation using the NationStates verification API.

Get card

Get a single trading card by its id and season. Choose which aspects to include: card info, owners, market asks/bids, and trade history.

Inputs

Card IDcard_idnumberRequired
The card's numeric id (a nation's database id).At least 1.
SeasonseasonnumberRequired
The card season (the current season is 4).At least 1. Default: 4.
Includeaspectstext
Which parts of the card to return.One or more of: info (Card info), owners, markets (Market (asks & bids)), trades (Trade history). Default: ["info", "markets"].

Outputs

cardobject
Example output
{
  "card": {
    "CARD": {
      "CARDID": "1",
      "CATEGORY": "legendary",
      "FLAG": "uploads/testlandia__643246.png",
      "GOVT": "Inoffensive Centrist Democracy",
      "MARKETS": {
        "MARKET": [
          {
            "NATION": "frisbeeteria",
            "PRICE": "2.00",
            "TIMESTAMP": "1672280352",
            "TYPE": "bid"
          }
        ]
      },
      "MARKET_VALUE": "776.00",
      "NAME": "Testlandia",
      "SEASON": "1"
    }
  }
}

Get card collection

Get a trading card collection by its id, including the cards in it.

Inputs

Collection IDcollection_idnumberRequired
The collection's numeric id.At least 1.

Outputs

collectionobject
Example output
{
  "collection": {
    "CARDS": {
      "COLLECTION": {
        "DECK": {
          "CARD": [
            {
              "CARDID": "1",
              "CATEGORY": "legendary",
              "SEASON": "1"
            }
          ]
        },
        "LAST_UPDATED": "1778700000",
        "NAME": "Founders",
        "NATION": "testlandia"
      }
    }
  }
}

Get card deck

Get a nation's trading card deck: the cards it owns plus a summary of its bank, deck value, and rank.

Inputs

NationnationtextRequired
The nation's name, e.g. 'Testlandia'.

Outputs

deckobject
Example output
{
  "deck": {
    "CARDS": {
      "DECK": {
        "CARD": [
          {
            "CARDID": "1",
            "CATEGORY": "legendary",
            "SEASON": "1"
          }
        ]
      },
      "INFO": {
        "BANK": "162.73",
        "DECK_VALUE": "6751.89",
        "ID": "1",
        "NAME": "testlandia",
        "NUM_CARDS": "336",
        "RANK": "418",
        "REGION_RANK": "1"
      }
    }
  }
}

Get dispatch

Get a single dispatch by its id, including its full text.

Inputs

Dispatch IDdispatch_idnumberRequired
The dispatch's numeric id.At least 1.

Outputs

dispatchobject
Example output
{
  "dispatch": {
    "WORLD": {
      "DISPATCH": {
        "@id": "2806702",
        "AUTHOR": "testlandia",
        "CATEGORY": "Factbook",
        "CREATED": "1778700000",
        "EDITED": "1778700000",
        "SCORE": "42",
        "SUBCATEGORY": "Culture",
        "TEXT": "Welcome to our region's roleplay guide...",
        "TITLE": "Regional Roleplay Guide",
        "VIEWS": "1024"
      }
    }
  }
}

Get nation

Look up public data about a nation. Choose which fields (shards) to return, such as its name, government type, region, population, WA membership, and flag.

Inputs

NationnationtextRequired
The nation's name, e.g. 'Testlandia'.
FieldsshardstextRequired
Which fields to return. Defaults to a general summary.One or more of: name, fullname (Full name), type (Government type), motto, category (WA category), wa (WA membership), region, population, flag (Flag URL), influence, and 48 more. Default: ["name", "fullname", "type", "motto", "category", "wa", "region", "population", "flag", "influence", "freedom"].

Outputs

nationobject
Example output
{
  "nation": {
    "NATION": {
      "@id": "testlandia",
      "CATEGORY": "Inoffensive Centrist Democracy",
      "FLAG": "https://www.nationstates.net/images/flags/uploads/testlandia__853435.png",
      "FREEDOM": {
        "CIVILRIGHTS": "Excellent",
        "ECONOMY": "Very Strong",
        "POLITICALFREEDOM": "Superb"
      },
      "FULLNAME": "The Hive Mind of Testlandia",
      "INFLUENCE": "Vassal",
      "MOTTO": "New forum when?",
      "NAME": "Testlandia",
      "POPULATION": "49926",
      "REGION": "Testregionia",
      "TYPE": "Hive Mind",
      "UNSTATUS": "WA Delegate"
    }
  }
}

Get nation census

Get one or more World Census statistics for a nation (e.g. Economy, Civil Rights, Influence), as raw scores and/or world and regional rankings.

Inputs

NationnationtextRequired
The nation's name, e.g. 'Testlandia'.
Census statisticsscalestextRequired
Which World Census statistics to return.One or more of: 0 (Civil Rights), 1 (Economy), 2 (Political Freedom), 3 (Population), 4 (Wealth Gaps), 5 (Death Rate), 6 (Compassion), 7 (Eco-Friendliness), 8 (Social Conservatism), 9 (Nudity), and 80 more. Default: ["0", "1"].
Reportmodestext
Whether to return the raw score and/or the nation's world and regional rankings.One or more of: score, rank (World rank), rrank (Regional rank), prank (World percentile rank), prrank (Regional percentile rank). Default: ["score"].

Outputs

censusobject
Example output
{
  "census": {
    "NATION": {
      "@id": "testlandia",
      "CENSUS": {
        "SCALE": [
          {
            "@id": "0",
            "RANK": "160926",
            "SCORE": "50.00"
          },
          {
            "@id": "1",
            "RANK": "83532",
            "SCORE": "90.52"
          }
        ]
      }
    }
  }
}

Get poll

Get a regional poll by its id, including its current results.

Inputs

Poll IDpoll_idnumberRequired
The poll's numeric id.At least 1.

Outputs

pollobject
Example output
{
  "poll": {
    "WORLD": {
      "POLL": {
        "@id": "1500000",
        "AUTHOR": "testlandia",
        "OPTIONS": {
          "OPTION": [
            {
              "@id": "0",
              "OPTIONTEXT": "Festival",
              "VOTES": "12"
            },
            {
              "@id": "1",
              "OPTIONTEXT": "Election",
              "VOTES": "7"
            }
          ]
        },
        "REGION": "testregionia",
        "TITLE": "Favourite region event?"
      }
    }
  }
}

Get region

Look up public data about a region. Choose which fields (shards) to return, such as its delegate, founder, population, power, tags, and officers.

Inputs

RegionregiontextRequired
The region's name, e.g. 'The Pacific'.
FieldsshardstextRequired
Which fields to return. Defaults to a general summary.One or more of: name, factbook (Factbook (World Factbook Entry)), numnations (Number of nations), nations (Nation list), wanations (WA member nations), numwanations (WA member count), delegate (WA Delegate), delegatevotes (Delegate vote weight), delegateauth (Delegate authorities), founder, and 23 more. Default: ["name", "numnations", "delegate", "founder", "governor", "power", "flag", "founded", "lastupdate", "tags"].

Outputs

regionobject
Example output
{
  "region": {
    "REGION": {
      "@id": "the_pacific",
      "DELEGATE": "pasybfic",
      "FLAG": "https://www.nationstates.net/images/flags/uploads/rflags/the_pacific__192464.png",
      "FOUNDED": "0",
      "FOUNDER": "0",
      "GOVERNOR": "0",
      "LASTUPDATE": "1786599766",
      "NAME": "the Pacific",
      "NUMNATIONS": "2720",
      "POWER": "Very High",
      "TAGS": {
        "TAG": [
          "Featured",
          "Founderless",
          "Massive"
        ]
      }
    }
  }
}

Get region census leaderboard

Get a region's leaderboard for a World Census statistic: the nations in that region ranked by that statistic, 20 at a time.

Inputs

RegionregiontextRequired
The region's name, e.g. 'The Pacific'.
Census statisticscaletextRequired
Which World Census statistic to rank by.One of: 0 (Civil Rights), 1 (Economy), 2 (Political Freedom), 3 (Population), 4 (Wealth Gaps), 5 (Death Rate), 6 (Compassion), 7 (Eco-Friendliness), 8 (Social Conservatism), 9 (Nudity), and 80 more. Default: 0.
Start at rankstartnumber
The rank to start the leaderboard at.At least 1.

Outputs

censusRanksobject
Example output
{
  "censusRanks": {
    "REGION": {
      "@id": "the_pacific",
      "CENSUSRANKS": {
        "@id": "0",
        "NATIONS": {
          "NATION": [
            {
              "NAME": "testlandia",
              "RANK": "1",
              "SCORE": "100.00"
            }
          ]
        }
      }
    }
  }
}

Get regional message board

Read posts from a region's Regional Message Board (RMB), newest last. Page through history with the starting post id and offset.

Inputs

RegionregiontextRequired
The region's name, e.g. 'The Pacific'.
Number of postslimitnumber
How many posts to return (1-100).From 1 to 100. Default: 10.
Skipoffsetnumber
Skip this many of the most recent posts.At least 0.
Starting post IDfrom_idnumber
Only return posts with this id or newer.At least 1.

Outputs

messagesobject
Example output
{
  "messages": {
    "REGION": {
      "@id": "the_pacific",
      "MESSAGES": {
        "POST": [
          {
            "@id": "45204817",
            "MESSAGE": "Welcome to the Pacific!",
            "NATION": "pasybfic",
            "TIMESTAMP": "1786598000"
          }
        ]
      }
    }
  }
}

Get World Assembly data

Get data about a World Assembly council (General Assembly or Security Council): member and delegate counts, lists, current proposals, the last resolution, and recent happenings.

Inputs

CouncilcounciltextRequired
Which World Assembly council to query.One of: 1 (General Assembly), 2 (Security Council). Default: 1.
FieldsshardstextRequired
Which World Assembly fields to return.One or more of: numnations (Member nation count), numdelegates (Delegate count), delegates (Delegate list), members (Member list), happenings (Recent happenings), lastresolution (Last resolution), proposals (Current proposals). Default: ["numnations", "numdelegates", "lastresolution"].

Outputs

worldAssemblyobject
Example output
{
  "worldAssembly": {
    "WA": {
      "@council": "1",
      "LASTRESOLUTION": "The General Assembly resolution <strong>Repeal \"Freedom to Read and Learn\"</strong> was passed 7,272 votes to 3,793.",
      "NUMDELEGATES": "682",
      "NUMNATIONS": "14530"
    }
  }
}

Get World Assembly resolution

Get a World Assembly resolution with its voting detail. Leave the resolution id blank for the one currently at vote, or give an id for a past resolution.

Inputs

CouncilcounciltextRequired
Which World Assembly council to query.One of: 1 (General Assembly), 2 (Security Council). Default: 1.
Resolution IDresolution_idnumber
A past resolution's id. Leave blank for the resolution currently at vote.At least 1.

Outputs

resolutionobject
Example output
{
  "resolution": {
    "WA": {
      "@council": "1",
      "RESOLUTION": {
        "CATEGORY": "Environmental",
        "CREATED": "1786500000",
        "NAME": "Protect the Reefs",
        "PROPOSED_BY": "testlandia",
        "TOTAL_VOTES_AGAINST": "3793",
        "TOTAL_VOTES_FOR": "7272"
      }
    }
  }
}

Get world census leaderboard

Get the world-wide leaderboard for a World Census statistic: every nation ranked by that statistic, 20 at a time.

Inputs

Census statisticscaletextRequired
Which World Census statistic to rank by.One of: 0 (Civil Rights), 1 (Economy), 2 (Political Freedom), 3 (Population), 4 (Wealth Gaps), 5 (Death Rate), 6 (Compassion), 7 (Eco-Friendliness), 8 (Social Conservatism), 9 (Nudity), and 80 more. Default: 0.
Start at rankstartnumber
The rank to start the leaderboard at.At least 1.

Outputs

censusRanksobject
Example output
{
  "censusRanks": {
    "WORLD": {
      "CENSUSRANKS": {
        "@id": "0",
        "NATIONS": {
          "NATION": [
            {
              "NAME": "testlandia",
              "RANK": "1",
              "SCORE": "100.00"
            }
          ]
        }
      }
    }
  }
}

Get world data

Get world-wide data: the total number of nations and regions, the featured region, the newest nations, and the latest event id.

Inputs

FieldsshardstextRequired
Which world fields to return.One or more of: numnations (Number of nations), numregions (Number of regions), featuredregion (Featured region), newnations (Newest nations), lasteventid (Last event ID). Default: ["numnations", "numregions", "featuredregion", "newnations"].

Outputs

worldobject
Example output
{
  "world": {
    "WORLD": {
      "FEATUREDREGION": "novo_brasil",
      "NEWNATIONS": "the_grim_reaper,new_haizea,port_royal",
      "NUMNATIONS": "307951",
      "NUMREGIONS": "33137"
    }
  }
}

Get world happenings

Get the global feed of recent happenings (events). Optionally filter to particular event types and page through with event ids.

Inputs

Event typesfilterstext
Only return these kinds of events.One or more of: law (Law changes), change (Nation setting changes), dispatch (Dispatches), rmb (Regional message board), embassy (Embassies), eject (Ejections), admin (Administrative), move (Nation movements), founding (New foundings), cte (Ceased to exist), and 4 more.
Number of eventslimitnumber
How many events to return (1-200).From 1 to 200. Default: 100.
Since event IDsince_idnumber
Only return events newer than this event id.At least 1.
Before event IDbefore_idnumber
Only return events older than this event id.At least 1.

Outputs

happeningsobject
Example output
{
  "happenings": {
    "WORLD": {
      "HAPPENINGS": {
        "EVENT": [
          {
            "@id": "361794633",
            "TEXT": "@@testlandia@@ was ranked in the Top 1% of the world for Most Cultured.",
            "TIMESTAMP": "1786599800"
          }
        ]
      }
    }
  }
}

List card auctions

List the trading cards currently up for auction.

Inputs

None.

Outputs

auctionsobject
Example output
{
  "auctions": {
    "CARDS": {
      "AUCTIONS": {
        "AUCTION": [
          {
            "CARDID": "1",
            "CATEGORY": "legendary",
            "NAME": "testlandia",
            "SEASON": "1"
          }
        ]
      }
    }
  }
}

List dispatches

List dispatches (published factbooks, bulletins, and more). Optionally filter by category and author, and sort by newest or best.

Inputs

Sortsorttext
Order the dispatches by newest or best.One of: new (Newest first), best (Best first). Default: new.
Categorycategorytext
Only return dispatches in this category.One of: Factbook, Bulletin, Account, Meta.
Authorauthortext
Only return dispatches by this nation.

Outputs

dispatchesobject
Example output
{
  "dispatches": {
    "WORLD": {
      "DISPATCHLIST": {
        "DISPATCH": [
          {
            "@id": "2806702",
            "AUTHOR": "testlandia",
            "CATEGORY": "Factbook",
            "CREATED": "1778700000",
            "EDITED": "1778700000",
            "SCORE": "42",
            "SUBCATEGORY": "Culture",
            "TITLE": "Regional Roleplay Guide",
            "VIEWS": "1024"
          }
        ]
      }
    }
  }
}

List nation card collections

List the trading card collections a nation has created.

Inputs

NationnationtextRequired
The nation's name, e.g. 'Testlandia'.

Outputs

collectionsobject
Example output
{
  "collections": {
    "CARDS": {
      "COLLECTIONS": {
        "COLLECTION": [
          {
            "COLLECTIONID": "42",
            "LAST_UPDATED": "1778700000",
            "NAME": "Founders"
          }
        ]
      }
    }
  }
}

List regions by tag

Find regions by their tags. Include regions that have any of the chosen tags, and/or exclude regions that have others.

Inputs

Include tagsinclude_tagstext
Return regions that have any of these tags.One or more of: anarchist, anime, anti_capitalist (Anti-Capitalist), anti_communist (Anti-Communist), anti_fascist (Anti-Fascist), anti_general_assembly (Anti-General Assembly), anti_security_council (Anti-Security Council), anti_world_assembly (Anti-World Assembly), capitalist, casino, and 73 more.
Exclude tagsexclude_tagstext
Leave out regions that have any of these tags.One or more of: anarchist, anime, anti_capitalist (Anti-Capitalist), anti_communist (Anti-Communist), anti_fascist (Anti-Fascist), anti_general_assembly (Anti-General Assembly), anti_security_council (Anti-Security Council), anti_world_assembly (Anti-World Assembly), capitalist, casino, and 73 more.

Outputs

regionsobject
Example output
{
  "regions": {
    "WORLD": {
      "REGIONS": "the_pacific,the_north_pacific,the_east_pacific"
    }
  }
}

Verify nation login

Confirm that someone controls a nation using the NationStates verification API. The person gets a code from nationstates.net/page=verify_login; this checks it is valid.

Inputs

NationnationtextRequired
The nation's name, e.g. 'Testlandia'.
Verification codechecksumtextRequired
The code the person copied from nationstates.net/page=verify_login.
Site tokentokentext
Optional site-specific token, if you generated the code with one.

Outputs

verificationobject
Example output
{
  "verification": {
    "raw": "1",
    "verified": true
  }
}

Nationalize

Previous Page

Navidrome

Next Page

On this page

ActionsGet cardGet card collectionGet card deckGet dispatchGet nationGet nation censusGet pollGet regionGet region census leaderboardGet regional message boardGet World Assembly dataGet World Assembly resolutionGet world census leaderboardGet world dataGet world happeningsList card auctionsList dispatchesList nation card collectionsList regions by tagVerify nation login