NationStates API (nationdata/regiondata)

[SherpDaWerp]

Bit of an odd question, this one:

What order, if any, does the server return nations when you query:
https://www.nationstates.net/cgi-bin/ap ... &q=nations

It's quite obviously not alphabetical and doesn't seem to be based on any of the census scores, but it doesn't change, so it's not random either. I assume it's something to do with the order the server processes them in? Clarification pls

It appears to be based on residency with the most stationary at the start and as nations move in they are simply appended to the end.

Doesn't seem that way to me...

https://www.nationstates.net/cgi-bin/ap ... &q=nations

1. voice_of_mod
2. a_badly_conceived_designation
3. testlandia
4. lemon_42
5. mesoafricana

Residency Census

1. Voice of Mod
2. A Badly Conceived Designation
3. The Blaatschapens nation
4. Meta Luna
5. Greenerica

The first 5 of each aren't in the same order.

[The Northern Light]

Bug report

The nation dump seems to be containing some mixed up information about endorsements. Here is one example (out of many) from the nation dump produced 30 minutes ago:

Code: Select all

<NATION id="the_kingdom_of_the_greeks">
<NAME>the_kingdom_of_the_greeks</NAME>
<UNSTATUS>WA Member</UNSTATUS>
<ENDORSEMENTS>amerion,qvait,madreia,malonereich,tepertopia,erinor,aidenfieeld,land_without_shrimp,barabarom,bleakfoot,crystal_creation,marinho_islands,volaworand,aumeltopia,isles_of_creckero,tarnik,bawkie,greater_scott_islands,bizzie,mapico,united_federated_states_of_omega,wehraboos,yaorozu,a_world_assembly_member,orado,imperial_joseon,empy,alunya,guer_aike,crader,el_fiji_grande,</ENDORSEMENTS>
<REGION>the_north_pacific</REGION>
<LASTLOGIN>1581630871</LASTLOGIN>
<INFLUENCE>Unproven</INFLUENCE>
<CENSUS>
<SCALE id="66">
<SCORE>31</SCORE>
</SCALE>
</CENSUS>
</NATION>

Note that the nation is in The North Pacific, and has been there since 2/13/2020, 4:22:12 PM EST. Before that, the nation was in The South Pacific.

The list of endorsements contains several nations that are in The South Pacific, and were presumably this nation's endorsements while in The South Pacific:

amerion,qvait,madreia,malonereich,tepertopia,erinor,aidenfieeld,land_without_shrimp,barabarom,bleakfoot,crystal_creation,marinho_islands,volaworand,aumeltopia,isles_of_creckero,tarnik,bawkie,greater_scott_islands,bizzie,mapico,united_federated_states_of_omega,wehraboos

This bug seems to affect several nations, and has been happening since at least the start of the year (I suspect it was happening before that as well, but I didn't check all the way back).

[SherpDaWerp]

Request for a new shard:

Would it be possible to have a shard for a region's activity? Essentially, this:
https://www.nationstates.net/page=activ ... ss_gallows
But as an API shard. Ideally, in the format of the messages shard, where you can specify "since timestamp" or "last x" items.

[Trotterdam]

Request for a new shard:

Would it be possible to have a shard for a region's activity? Essentially, this:
https://www.nationstates.net/page=activ ... ss_gallows
But as an API shard. Ideally, in the format of the messages shard, where you can specify "since timestamp" or "last x" items.

Uh, I'm pretty sure this already exists. https://www.nationstates.net/cgi-bin/api.cgi?q=happenings&view=region.glass_gallows what you want?

Do note the slightly illogcal behavior that while national happenings are included in this regional feed (both links), it includes or excludes nations based on which region they're in at the time you request the shard, not at the time the happening occurred. You can probably make this issue go away by filtering for only happening categories that are genuinely regional in nature, if those are what you're interested in.

[SherpDaWerp]

Request for a new shard:

Would it be possible to have a shard for a region's activity? Essentially, this:
https://www.nationstates.net/page=activ ... ss_gallows
But as an API shard. Ideally, in the format of the messages shard, where you can specify "since timestamp" or "last x" items.

Uh, I'm pretty sure this already exists. https://www.nationstates.net/cgi-bin/api.cgi?q=happenings&view=region.glass_gallows what you want?

Do note the slightly illogcal behavior that while national happenings are included in this regional feed (both links), it includes or excludes nations based on which region they're in at the time you request the shard, not at the time the happening occurred. You can probably make this issue go away by filtering for only happening categories that are genuinely regional in nature, if those are what you're interested in.

Oh. I should have looked in the world shards... I was looking at this:
https://www.nationstates.net/cgi-bin/ap ... happenings
where you're requesting happenings like it's a region shard, and I wanted more information but couldn't find how.

Thanks!

[Eluvatar]

Bug report

The nation dump seems to be containing some mixed up information about endorsements. Here is one example (out of many) from the nation dump produced 30 minutes ago:

Code: Select all

<NATION id="the_kingdom_of_the_greeks">
<NAME>the_kingdom_of_the_greeks</NAME>
<UNSTATUS>WA Member</UNSTATUS>
<ENDORSEMENTS>amerion,qvait,madreia,malonereich,tepertopia,erinor,aidenfieeld,land_without_shrimp,barabarom,bleakfoot,crystal_creation,marinho_islands,volaworand,aumeltopia,isles_of_creckero,tarnik,bawkie,greater_scott_islands,bizzie,mapico,united_federated_states_of_omega,wehraboos,yaorozu,a_world_assembly_member,orado,imperial_joseon,empy,alunya,guer_aike,crader,el_fiji_grande,</ENDORSEMENTS>
<REGION>the_north_pacific</REGION>
<LASTLOGIN>1581630871</LASTLOGIN>
<INFLUENCE>Unproven</INFLUENCE>
<CENSUS>
<SCALE id="66">
<SCORE>31</SCORE>
</SCALE>
</CENSUS>
</NATION>

Note that the nation is in The North Pacific, and has been there since 2/13/2020, 4:22:12 PM EST. Before that, the nation was in The South Pacific.

The list of endorsements contains several nations that are in The South Pacific, and were presumably this nation's endorsements while in The South Pacific:

amerion,qvait,madreia,malonereich,tepertopia,erinor,aidenfieeld,land_without_shrimp,barabarom,bleakfoot,crystal_creation,marinho_islands,volaworand,aumeltopia,isles_of_creckero,tarnik,bawkie,greater_scott_islands,bizzie,mapico,united_federated_states_of_omega,wehraboos

This bug seems to affect several nations, and has been happening since at least the start of the year (I suspect it was happening before that as well, but I didn't check all the way back).

Not a bug. Check the subsequent dump for any such nation.

[Eluvatar]

Bit of an odd question, this one:

What order, if any, does the server return nations when you query:
https://www.nationstates.net/cgi-bin/ap ... &q=nations

It's quite obviously not alphabetical and doesn't seem to be based on any of the census scores, but it doesn't change, so it's not random either. I assume it's something to do with the order the server processes them in? Clarification pls

It's arbitrary and subject to change.

[SherpDaWerp]

Bit of an odd question, this one:

What order, if any, does the server return nations when you query:
https://www.nationstates.net/cgi-bin/ap ... &q=nations

It's quite obviously not alphabetical and doesn't seem to be based on any of the census scores, but it doesn't change, so it's not random either. I assume it's something to do with the order the server processes them in? Clarification pls

It's arbitrary and subject to change.

Arbitrary seems like an interesting way to do it. Thanks for answering though.

[Bormiar]

Is it possible to vote on WA resolutions with the API? If not, that seems like it would be very helpful for stomps / boosts and delegates who vote based on citizen or WA resident votes.

[Flanderlion]

Is it possible to vote on WA resolutions with the API? If not, that seems like it would be very helpful for stomps / boosts and delegates who vote based on citizen or WA resident votes.

Feels like it'll just be used for people to stack votes when the resolution goes to vote.

[Bowzin]

Is it possible to vote on WA resolutions with the API? If not, that seems like it would be very helpful for stomps / boosts and delegates who vote based on citizen or WA resident votes.

Feels like it'll just be used for people to stack votes when the resolution goes to vote.

I agree with this. Too easy for delegates to auto-vote right when a resolution goes to vote. Early vote stacking and the lemming effect already are a problem, and would only get worse if delegates didn't even need to be on.

[Bormiar]

Feels like it'll just be used for people to stack votes when the resolution goes to vote.

I agree with this. Too easy for delegates to auto-vote right when a resolution goes to vote. Early vote stacking and the lemming effect already are a problem, and would only get worse if delegates didn't even need to be on.

Well being on depends on real life (such as sleep), so in other words in favors certain people. In fact, making vote-stacking easier is entirely the point. Like how "if everyone is winning than no one really is, by definition", making it so anyone can vote early evens the odds significantly.

[Evrigenis]

I have recently got involved card-farming and would like to make puppets more efficiently. I am aware that the OSRS prohibits using a tool that interacts with the HTML to do so, but it exempts the API from such rules. However, the nation creation feature is not documented here, and I asked around to find the template for the call, shown below.

Code: Select all

http://www.nationstates.net/cgi-bin/build_nation.cgi?Q0=&Q1=&Q2=&Q3=&Q4=&Q5=&Q6=&Q7=&legal=1&style=50.50.50&name=NATIONNAME&flag=Default.png&email=EMAIL&currency=CURRENCY&slogan=SLOGAN&password=PASSWORD&confirm_password=PASSWORD&type=129&animal=ANIMAL&rname=&regionpw=&history=pioneer


After filling in the URL parameters,¹ I obtained the error message "please supply a national flag." I tried using four different sources—the default, my local storage, imgur,² and the URL from another nation's flag shard³—and all obtained the same error message. That caused me to suspect that the error was not related to the flag, so I tried an incomplete call,⁴ which also returned "please supply a national flag", confirming my suspicion. I heard that API-based nation creation worked before my founding, so I also tried appending "&v="1-9 to the call, all of which continued to return the error message "please supply a national flag." Finally, I tried replacing the _ with %20 and %23 in an attempt to be compatible with different encodings for whitespace, all of which continued to return "please supply a national flag."

As such, I am curious about the following:
1) Is there a way to use the API to create nations?
2) If so, why isn't it documented?
3) If not, when/why was the functionality discontinued?
4) Would it be possible to make the error messages more informative?

Footnotes
¹Specifically,

Code: Select all

http://www.nationstates.net/cgi-bin/build_nation.cgi?Q0=1&Q1=1&Q2=1&Q3=1&Q4=1&Q5=1&Q6=1&Q7=1&legal=1&style=50.50.50&name=Themetest8&flag=Default.png&email=EMAILREDACTED&currency=bank&slogan=test&password=PASSWORDREDACTED&confirm_password=PASSWORDREDACTED&type=129&animal=ANIMAL&rname=the_east_pacific&history=pioneer


²https://imgur.com/a/ZLY20Xf
³On https://www.nationstates.net/cgi-bin/ap ... 002&q=flag, I found https://www.nationstates.net/images/fla ... 689271.png and tried using the latter as the flag parameter
⁴http://www.nationstates.net/cgi-bin/build_nation.cgi?Q0=1

tl;dr: How does one use the API to create new nations?

Edited to clarify questions and to add to the list of things I have tried.

[Frisbeeteria]

flag=Default.png

(Note: player, not admin response. I don't know the rules of the back end of the API, just my apocryphal experience.)

For whatever reason, the API only sees JPG flags. I think even JPEG files fail the test. It's not a matter of the format of the image, it's entirely about the extension. I'm pretty sure that it has to be flagfile.jpg, even if you're just renaming a PNG or GIF file.

[Evrigenis]

flag=Default.png

(Note: player, not admin response. I don't know the rules of the back end of the API, just my apocryphal experience.)

For whatever reason, the API only sees JPG flags. I think even JPEG files fail the test. It's not a matter of the format of the image, it's entirely about the extension. I'm pretty sure that it has to be flagfile.jpg, even if you're just renaming a PNG or GIF file.

Thanks for that insight, but that does not appear to be the issue. I just tried it with "default.jpg", "Default.jpg", converting my png to a jpg and using local storage, a different (JPG) shard, and a JPG uploaded on imgur. Do you have any other suggestions?

[Riemstagrad]

It works if you don't use spaces in any field at all. There must be a trick to circumvent this.
So far tested with underscore, %20 and %23
What else can replace a space in a URL?

[Trotterdam]

In GET/POST query data, a + sign typically gets interpreted as a space (to enter an actual + sign, you need to use %2B).

[Trotterdam]

About 80 minutes ago, my script detected the following effect line on Cahds 117:

Following new legislation in @@cahds_117@@, in a bizarre move the government of Cahds 117 has destroyed all information about a new world map in order to protect the nation's 'mind-carrots' .

Note that the easter egg parenthetical is missing, even though there's still a space to make room for it.

When I check https://www.nationstates.net/cgi-bin/api.cgi?q=happenings&filter=law&view=nation.cahds_117 now, this effect line is still there, but the easter egg parenthetical has now been added:

<EVENT id="58839494">
<TIMESTAMP>1584235994</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, several universities in Cahds 117 have assembled expensive research teams to explore and study new lands and old ruins (Cahds 117 has found 1 easter egg).]]></TEXT>
</EVENT>

<EVENT id="58839005">
<TIMESTAMP>1584235827</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, rich people sell their mansions to pay for endless rows of mobile homes.]]></TEXT>
</EVENT>

<EVENT id="58839003">
<TIMESTAMP>1584235826</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, many Cahds 117ians twitch nervously at the sight of nuns.]]></TEXT>
</EVENT>

<EVENT id="58839001">
<TIMESTAMP>1584235826</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, the realistic depiction of tentacles is on the core syllabus of most art schools.]]></TEXT>
</EVENT>

<EVENT id="58838492">
<TIMESTAMP>1584235597</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, country folk are sent to obligatory boarding schools to learn how to be civilized.]]></TEXT>
</EVENT>

<EVENT id="58838491">
<TIMESTAMP>1584235597</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, in a bizarre move the government of Cahds 117 has destroyed all information about a new world map in order to protect the nation's 'mind-carrots' (Cahds 117 has found 1 easter egg).]]></TEXT>
</EVENT>

<EVENT id="58781856">
<TIMESTAMP>1584198534</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, the tenet of free speech is held dear.]]></TEXT>
</EVENT>

<EVENT id="58781670">
<TIMESTAMP>1584198460</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, meat-eating is frowned upon.]]></TEXT>
</EVENT>

<EVENT id="58781665">
<TIMESTAMP>1584198459</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, the tenet of free speech is held dear.]]></TEXT>
</EVENT>

<EVENT id="58781664">
<TIMESTAMP>1584198459</TIMESTAMP>
<TEXT><![CDATA[Following new legislation in @@cahds_117@@, a nation-wide cull of MV hawks is in effect.]]></TEXT>
</EVENT>

In addition, I now notice that an effect line appears to have been reported twice.

By contrast, on Cahds 117's nation page, the happenings look like this:

69 minutes ago: Following new legislation in Cahds 117, several universities in Cahds 117 have assembled expensive research teams to explore and study new lands and old ruins (Cahds 117 has found 1 easter egg).
72 minutes ago: Following new legislation in Cahds 117, rich people sell their mansions to pay for endless rows of mobile homes.
72 minutes ago: Following new legislation in Cahds 117, many Cahds 117ians twitch nervously at the sight of nuns.
72 minutes ago: Following new legislation in Cahds 117, the realistic depiction of tentacles is on the core syllabus of most art schools.
76 minutes ago: Following new legislation in Cahds 117, country folk are sent to obligatory boarding schools to learn how to be civilized.
11 hours ago: Following new legislation in Cahds 117, the tenet of free speech is held dear.
11 hours ago: Following new legislation in Cahds 117, meat-eating is frowned upon.
11 hours ago: Following new legislation in Cahds 117, a nation-wide cull of MV hawks is in effect.

The mind-carrot easter egg is completely missing, and the doubled effect line is listed only once, like it (probably) should.

What's going on here?

[Ballotonia]

Greetings,

Newly added to the API: a list of all cards currently at auction. It purposely does not contain price information, as that would encourage near-continuous pulling of that page.

See item 5 on: https://www.nationstates.net/pages/api.html#cards

Ballotonia

[Agadar]

I happened to be running my telegrammer for the first time in a few days, and I'm suddenly getting a 'javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure' when calling 'https://www.nationstates.net/cgi-bin/api.cgi?v=9&q=NEWNATIONS' or when sending a second telegram after the first one. My telegrammer hasn't changed since 21 Nov 2019. Has anything changed to the way the API handles requests?

[[violet]]

I happened to be running my telegrammer for the first time in a few days, and I'm suddenly getting a 'javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure' when calling 'https://www.nationstates.net/cgi-bin/api.cgi?v=9&q=NEWNATIONS' or when sending a second telegram after the first one. My telegrammer hasn't changed since 21 Nov 2019. Has anything changed to the way the API handles requests?

No, but there is a similar Tech thread, which may be caused by outdated SSL protocols.

[SherpDaWerp]

A request and a suggestion:

1. Can the "total amount bid" (as viewable on the bottom of this page) be added to the Deck Owner Info shard? It's publicly viewable information anyway, and it would make it possible to calculate the amount of bank a nation has "free" to use.
   
2. The API Documentation page has the two cardlists under Daily Dumps, and mentions it at the bottom of the "Trading Cards API" section as a good way to get "lots of card data at once". Given that is is not updated daily, nor is it a good way to get lots of API-hosted card data (auctions, trades, bids, asks, decks, owner info, and collection info do not appear in the cardlists), should the cardlists perhaps be situated elsewhere?

[Aurum Raider]

Would it be possible to add the
TGCANRECRUIT
and
TGCANCAMPAIGN
to the nation data dumps?

EDIT: Read this idea, have some questions and feedback.

There would be a new thing called a 'report':

1. A report could be generated through the private API with a set of parameters such as q=region.nations+nation.name+nation.scale&scale=65&mode=score&region=europeia
2. A valid request to generate a report would get a 202 (Accepted) response back
3. A report which has been generated would stick around for some period of time (24h? until a newer report has been generated with the same dataset?).
4. We'd watch reports creation and possibly introduce extra rate limitations
5. There would be a public index of available reports, searchable by the parameters, and returning URLs
6. The index would include reports that are in progress and mark them as such
7. The report itself would be publicly accessible at some particular URL and would return 503 until it was complete

You say private API - I assume this means you must be logged in to request a report be generated, not to view one?

I can see reports being a very useful tool beyond API-only use - would it be possible to generate reports using the dossier as well as with API requests?

[[violet]]

API version number has been bumped to 11: from this version onwards, it supports UTF8-encoded uploaded content (e.g. in dispatch text).

If you require the older method, specify version 10 or earlier via the "v" parameter: https://www.nationstates.net/pages/api.html#versions

[Aurum Raider]

Also, I hate to bring the topic up again, since it's been discussed to death, but I think even if a 'reports' feature was implemented, the Raw Influence is still something that should be included in the national data dump.

Apart from interesting data visualization projects (I'd like to create visualizations of regional influence growth), in the context of R/D tools, the reports feature only helps if you are looking at a single region.

I also want to follow up on this post in particular.

The nation dumps already include a few other censuses in various forms, namely CENSUSIDs 0, 1, 2, 3, and 49 (there is also a "PUBLICSECTOR" field for which I could not determine whether it corresponds to a CENSUSID). I understand that at least the first four are "special" censuses (respectively: the three censuses that determine a nation's category, and population). I'd argue that SPDR is also special, given its role in determining the feasibility/outcome of many gameplay actions. Therefore, it should be included in the nation dumps, just as CENSUSIDs 0-3 are.

I would actually take an even more extreme position than saying that SPDR is 'special,' and I would say that it literally should not have be grouped with the other census scores in the first place. Unlike Cheerfulness, or Recreational Drug Use, how much influence a nation has is extremely relevant to gameplay.

Spending an hour scraping the API for the influence of every nation in a region should not be necessary. It would take three hours of polling the API at maximum speed to get the influence of every nation In TNP alone. If I want try get the influence of every nation in the world to find good raiding targets, it will take me two days of continuous maximum speed polling and by the time I'd be done, one quarter of the influence scores I've gathered will have become useless.

When accessing any of the other census scores, it is because you are interested in an individual nation. This is not how influence is considered at all - I don't think it should have to be said that influence is something you look at on a regional level. Nobody is scraping their region daily to figure out the regional cheerfulness level (as amusing as the thought is), however how much influence is floating around in your region is critical for regional security.