# NationStates

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

App · Gaming · 20 actions. Web page: https://docs.lodol.com/docs/integrations/nationstates

## Actions

### 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 ID (`card_id`, number, required): The card's numeric id (a nation's database id). At least 1.
- Season (`season`, number, required): The card season (the current season is 4). At least 1. Default: `4`.
- Include (`aspects`, text): 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**

- `card` (object)

**Example output**

```json
{
  "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 ID (`collection_id`, number, required): The collection's numeric id. At least 1.

**Outputs**

- `collection` (object)

**Example output**

```json
{
  "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**

- Nation (`nation`, text, required): The nation's name, e.g. 'Testlandia'.

**Outputs**

- `deck` (object)

**Example output**

```json
{
  "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 ID (`dispatch_id`, number, required): The dispatch's numeric id. At least 1.

**Outputs**

- `dispatch` (object)

**Example output**

```json
{
  "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**

- Nation (`nation`, text, required): The nation's name, e.g. 'Testlandia'.
- Fields (`shards`, text, required): 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**

- `nation` (object)

**Example output**

```json
{
  "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**

- Nation (`nation`, text, required): The nation's name, e.g. 'Testlandia'.
- Census statistics (`scales`, text, required): 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"]`.
- Report (`modes`, text): 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**

- `census` (object)

**Example output**

```json
{
  "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 ID (`poll_id`, number, required): The poll's numeric id. At least 1.

**Outputs**

- `poll` (object)

**Example output**

```json
{
  "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**

- Region (`region`, text, required): The region's name, e.g. 'The Pacific'.
- Fields (`shards`, text, required): 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**

- `region` (object)

**Example output**

```json
{
  "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**

- Region (`region`, text, required): The region's name, e.g. 'The Pacific'.
- Census statistic (`scale`, text, required): 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 rank (`start`, number): The rank to start the leaderboard at. At least 1.

**Outputs**

- `censusRanks` (object)

**Example output**

```json
{
  "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**

- Region (`region`, text, required): The region's name, e.g. 'The Pacific'.
- Number of posts (`limit`, number): How many posts to return (1-100). From 1 to 100. Default: `10`.
- Skip (`offset`, number): Skip this many of the most recent posts. At least 0.
- Starting post ID (`from_id`, number): Only return posts with this id or newer. At least 1.

**Outputs**

- `messages` (object)

**Example output**

```json
{
  "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**

- Council (`council`, text, required): Which World Assembly council to query. One of: `1` (General Assembly), `2` (Security Council). Default: `1`.
- Fields (`shards`, text, required): 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**

- `worldAssembly` (object)

**Example output**

```json
{
  "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**

- Council (`council`, text, required): Which World Assembly council to query. One of: `1` (General Assembly), `2` (Security Council). Default: `1`.
- Resolution ID (`resolution_id`, number): A past resolution's id. Leave blank for the resolution currently at vote. At least 1.

**Outputs**

- `resolution` (object)

**Example output**

```json
{
  "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 statistic (`scale`, text, required): 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 rank (`start`, number): The rank to start the leaderboard at. At least 1.

**Outputs**

- `censusRanks` (object)

**Example output**

```json
{
  "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**

- Fields (`shards`, text, required): 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**

- `world` (object)

**Example output**

```json
{
  "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 types (`filters`, text): 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 events (`limit`, number): How many events to return (1-200). From 1 to 200. Default: `100`.
- Since event ID (`since_id`, number): Only return events newer than this event id. At least 1.
- Before event ID (`before_id`, number): Only return events older than this event id. At least 1.

**Outputs**

- `happenings` (object)

**Example output**

```json
{
  "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**

- `auctions` (object)

**Example output**

```json
{
  "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**

- Sort (`sort`, text): Order the dispatches by newest or best. One of: `new` (Newest first), `best` (Best first). Default: `new`.
- Category (`category`, text): Only return dispatches in this category. One of: `Factbook`, `Bulletin`, `Account`, `Meta`.
- Author (`author`, text): Only return dispatches by this nation.

**Outputs**

- `dispatches` (object)

**Example output**

```json
{
  "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**

- Nation (`nation`, text, required): The nation's name, e.g. 'Testlandia'.

**Outputs**

- `collections` (object)

**Example output**

```json
{
  "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 tags (`include_tags`, text): 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 tags (`exclude_tags`, text): 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**

- `regions` (object)

**Example output**

```json
{
  "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**

- Nation (`nation`, text, required): The nation's name, e.g. 'Testlandia'.
- Verification code (`checksum`, text, required): The code the person copied from nationstates.net/page=verify_login.
- Site token (`token`, text): Optional site-specific token, if you generated the code with one.

**Outputs**

- `verification` (object)

**Example output**

```json
{
  "verification": {
    "raw": "1",
    "verified": true
  }
}
```