NationStates API (nationdata/regiondata)

[Zemnaya Svoboda]

Per requests above, added more shards.

To Nation shards:

• gdp
• sectors
• income
• poorest
• richest

To Region shards:

• officers
• delegateauth
• founderauth

Thank you

[Laevendell]

Per requests above, added more shards.[...]

Fantastic, thanks!

[HMS Unicorn]

Thanks a lot for the additions!

[Athretvari]

Per requests above, added more shards.

To Nation shards:

• gdp
• sectors
• income
• poorest
• richest

To Region shards:

• officers
• delegateauth
• founderauth

I love you.

[Misley]

To Region shards:

• officers
• delegateauth
• founderauth

Any chance these could be added to the daily dumps?

edit: Also, any chance "delegateauth" could still report the authorities granted to an unfilled Delegate seat?

Not sure if this post was missed since it was at the bottom of the page.

"delegateauth" should really report the authorities granted to an unfilled delegate seat. Not sure why it doesn't already. It'd be nice to not have to scrape for that information.

[Imperium Anglorum]

Can we get a region's banList off the API?

Also, if my calculations are correct, the rate limit is 0.6 seconds per request?

[[violet]]

Also, if my calculations are correct, the rate limit is 0.6 seconds per request?

No. It's currently 50 requests per 30 seconds, which isn't the same thing. You can make 50 requests in 1s if you make none for the next 29s.

Rate limit doc is here.

[Trotterdam]

I always just interpreted the rate limits as "try not to make more than one request per second, but we're allowing you a little leeway".

[Railana]

[violet], would you mind adding CORS support to the NationStates API? I'm trying to request data from the NationStates API using a web app, but I can't do so easily unless you add CORS support.

According to this Wikipedia page, you would need to respond to HTTP OPTIONS requests with the header name-value pair "Access-Control-Allow-Origin: *".

[[violet]]

[violet], would you mind adding CORS support to the NationStates API?

Done, I think.

[Trotterdam]

Something I've been wanting for a while:

q=notables and q=admirables shards, which display all tags a nation currently qualifies for that could be returned by q=notable and q=admirable, rather than a randomized selection (much like q=banners does for q=banner).

[[violet]]

Please note I have just banned some scripts from the API that were violating the Terms of Use, primarily by sending no UserAgent. I have also banned one UserAgent because the script has been exhibiting problems and the author as identified in the UserAgent didn't respond to email.

Affected scripts will receive a 403 status code from the API and an explanatory message. You can re-establish access by setting a valid unique UserAgent.

[Svornost]

Please note I have just banned some scripts from the API that were violating the Terms of Use, primarily by sending no UserAgent.

Wow. Apparently my core script component has had a bug for the last three years or so whereby it'd only actually send the useragent header on the very first request after being restarted. I am so sorry; I had no idea it was broken like that. And I probably never would have found out if you hadn't banned it today, so, as strange as it sounds...thanks.

[Drachmaland]

Something I've been wanting for a while:

q=notables and q=admirables shards, which display all tags a nation currently qualifies for that could be returned by q=notable and q=admirable, rather than a randomized selection (much like q=banners does for q=banner).

I wholeheartedly second that.

[Agadar]

I would like to ask whether what I'm trying to do is in accordance with the rules, since it wasn't entirely clear to me when I read them:

If I were to run a script that would on a daily or weekly basis gather information from the region I'm in and present them in a message on my regional message board, would that be in accordance with the rules?

Two examples of what the script could post are: listing and welcoming newly joined nations, and featuring random region members.

I do hope this isn't frowned upon, because I'm looking forward on tinkering with this.

[HMS Unicorn]

Would it be possible to provide a way to check whether an update is ongoing?

This could be, for example, a shard under the World API, which returns "0" if update is not running, and "1" if it is. An alternative would be to have a shard that returns a timestamp for when the latest completed update ended.

The reason this would be useful for me is that I often need to run various processes twice per day shortly after an update is done, and ideally as soon as the update is done.

As I don't know of a reliable way to check when update ends, the workaround I use is to schedule these processes to start at a safe temporal distance from the update (e.g., currently, at 2am EST/EDT for the major update, and 2pm for the minor). However, update duration fluctuates over time, sometimes dramatically: if the update becomes much longer, then these processes may potentially start overlapping with it, and therefore produce invalid results; if the update becomes much shorter, then there is a long time interval between the end of the update and the processes' start, and therefore the information gathered becomes inaccurate.

EDIT: To elaborate a little further on the above, there is a way to get the time the major update ended, by checking the "Last-Modified" header returned for the region and nation dumps.

However, this only works for the major update, and there is no equivalent for the minor update. Furthermore, it is not clear what the rate limit for such requests is, as it is not clear whether they can be considered part of the NS API.

For curl users, here is a way to get the HTTP headers for the dump files (the region dump in this example):

Code: Select all

curl -I --user-agent "REPLACE_WITH_YOUR_USER_AGENT" "http://www.nationstates.net/pages/regions.xml.gz"

Note that you must use the -I flag to make a HEAD request, which gets only the headers without fetching the content (dump files). Without this flag, running the above command multiple times will also download the huge dump file multiple times, which is a waste of both your and the NS server's bandwidth.

[Imperium Anglorum]

Would it be possible to get a nation's ban list off the API?

[Leppikania]

Would it be possible to get a nation's ban list off the API?

Do you mean a region's ban list? Because I don't see what a nation's ban list would be.

[Drachmaland]

Would it be possible to get a nation's ban list off the API?

Do you mean a region's ban list? Because I don't see what a nation's ban list would be.

Which regions a specific nation is banned from.

[Agadar]

Do you mean a region's ban list? Because I don't see what a nation's ban list would be.

Which regions a specific nation is banned from.

You can retrieve all(*) of a nation's happenings via https://www.nationstates.net/cgi-bin/ap ... happenings. Then, you can filter the retrieved data on the keyword 'banned'. You end up only with the happenings about the nation being banned with the text format "@@agadar@@ was ejected and banned from %%nationstates%% by @@toalla_gritadora@@." From that point on it is easy to filter out the region name.

EDIT: (*) Those aren't ALL of a nation's happenings, actually. I just checked. So, this method will only get you a list of the last few regions the nation was most recently banned from.

EDIT2: You can add an additional filter to https://www.nationstates.net/cgi-bin/ap ... happenings -> https://www.nationstates.net/cgi-bin/ap ... lter=eject but again, it doesn't seem possible to list ALL happenings, just the most recent ones.

[Caelapes]

I'm going to ask one last time on this -- can the "delegateauth" shard be changed to show permissions granted to empty WA Delegate seats? Currently, it returns an empty shard if there is not an active WAD, making it necessary to scrape HTML to find permissions granted to empty WADs. If the answer is no, that's not a big deal to me, but it'd make life easier.

Would it be possible to get a nation's ban list off the API?

Not unless you call the National/Regional Happenings API and save the results somehow. There's no API shard that gives that information.

I would like to ask whether what I'm trying to do is in accordance with the rules, since it wasn't entirely clear to me when I read them:

If I were to run a script that would on a daily or weekly basis gather information from the region I'm in and present them in a message on my regional message board, would that be in accordance with the rules?

Two examples of what the script could post are: listing and welcoming newly joined nations, and featuring random region members.

I do hope this isn't frowned upon, because I'm looking forward on tinkering with this.

Scripts cannot automatically post to Regional Message Boards. You can have the script prepare everything for your post (including formatting and text for the post) but you will have to make the post yourself, as a living person. You can either have it so that you click a button and it posts for you, or you copy-paste the text and post it yourself. It cannot post automatically without your input.

Would it be possible to provide a way to check whether an update is ongoing?

This could be, for example, a shard under the World API, which returns "0" if update is not running, and "1" if it is. An alternative would be to have a shard that returns a timestamp for when the latest completed update ended.

Seconding that this would be valuable. As a current workaround, you can place a nation in the last region to update and check when it receives issues through the RSS feed.

That won't be as helpful a workaround if a different region becomes the last region to update, though.

[Agadar]

I'm going to ask one last time on this -- can the "delegateauth" shard be changed to show permissions granted to empty WA Delegate seats? Currently, it returns an empty shard if there is not an active WAD, making it necessary to scrape HTML to find permissions granted to empty WADs. If the answer is no, that's not a big deal to me, but it'd make life easier.

Would it be possible to get a nation's ban list off the API?

Not unless you call the National/Regional Happenings API and save the results somehow. There's no API shard that gives that information.

I would like to ask whether what I'm trying to do is in accordance with the rules, since it wasn't entirely clear to me when I read them:

If I were to run a script that would on a daily or weekly basis gather information from the region I'm in and present them in a message on my regional message board, would that be in accordance with the rules?

Two examples of what the script could post are: listing and welcoming newly joined nations, and featuring random region members.

I do hope this isn't frowned upon, because I'm looking forward on tinkering with this.

Scripts cannot automatically post to Regional Message Boards. You can have the script prepare everything for your post (including formatting and text for the post) but you will have to make the post yourself, as a living person. You can either have it so that you click a button and it posts for you, or you copy-paste the text and post it yourself. It cannot post automatically without your input.

Would it be possible to provide a way to check whether an update is ongoing?

This could be, for example, a shard under the World API, which returns "0" if update is not running, and "1" if it is. An alternative would be to have a shard that returns a timestamp for when the latest completed update ended.

Seconding that this would be valuable. As a current workaround, you can place a nation in the last region to update and check when it receives issues through the RSS feed.

That won't be as helpful a workaround if a different region becomes the last region to update, though.

While I appreciate you weighing in on the matter of my script's legality, there is little reason to point to the rules, as the rules failed to convince me one way or the other that my script would be illegal, which is the whole reason why I'm here to ask an official moderator's opinion in the first place.

A) For starters, sending RMB messages isn't explicitly stated as a restricted action, nor is the 'gameworld' explicitly defined: only examples are given, among which the RMB is not. So, is the RMB part of the gameworld? Are the forums part of the gameworld? Is the entire website the gameworld? It is not clear where the borders exactly are.

B) Furthermore, IF the RMB is indeed considered part of the gameworld, then I would still argue for the legality of my script. Consider the following two scenarios:
- Every day before breakfast, I run a script that pulls data from the API, compiles it neatly in a message, and sends that message to the RMB. (This is legal according to the rules);
- Every day before breakfast, a script is run automaticaly that pulls data from the API, compiles it neatly in a message, and sends that message to the RMB. (This MIGHT be legal or not according to the rules);

The outcome is exactly the same: the exact same neatly composed message is posted on the RMB at the exact same time every day. Not only that, but if one were to launch an investigation, one would not even be able to prove whether the message was posted using the first, legal option, or the second maybe-legal option. The result is exactly the same for everyone, which I find a solid argument for my script's legality.

[Caelapes]

While I appreciate you weighing in on the matter of my script's legality, there is little reason to point to the rules, as the rules failed to convince me one way or the other that my script would be illegal, which is the whole reason why I'm here to ask an official moderator's opinion in the first place.

You're right that I am not a moderator or admin. I don't presume to give an "official" answer, but I would argue that since the script rules explicitly say that "It is illegal to use a tool to automatically cause something in the gameworld to change, other than your own nation" and the fact that the Regional Message Board is not a part of any player's nation, that it is against the rules for a script to automatically (that is, without player input at the rate of one input--mouse click, for example--to one action) make a change to it (for example, by adding a post, suppressing a post, or unsuppressing a post).

A) For starters, sending RMB messages isn't explicitly stated as a restricted action, nor is the 'gameworld' explicitly defined: only examples are given, among which the RMB is not. So, is the RMB part of the gameworld? Are the forums part of the gameworld? Is the entire website the gameworld? It is not clear where the borders exactly are.

My understanding is that everything at nationstates.net is part of the gameworld. Regions, nations, the WA, factbooks/dispatches, Activity pages, dossiers, etc. The Regional Message Board is a part of the region, which definitely places it within the borders of the gameworld. The examples listed in the Script Rules do not suggest that they are exhaustive, as that would be a ridiculously long list.

forum.nationstates.net is the forum, which is not a part of the game world as far as I am aware. Players are allowed to use scripts to scrape the gameworld, but scripts are explicitly prohibited on the forum.

B) Furthermore, IF the RMB is indeed considered part of the gameworld, then I would still argue for the legality of my script. Consider the following two scenarios:
- Every day before breakfast, I run a script that pulls data from the API, compiles it neatly in a message, and sends that message to the RMB. (This is legal according to the rules);
- Every day before breakfast, a script is run automaticaly that pulls data from the API, compiles it neatly in a message, and sends that message to the RMB. (This MIGHT be legal or not according to the rules);

If my interpretation is correct, since the second scenario causes a change to the gameworld outside your own nation automatically, it is illegal per the script rules. The first one relies on a player input (one input per action) to cause the script to produce its result, which would be legal.

The outcome is exactly the same: the exact same neatly composed message is posted on the RMB at the exact same time every day. Not only that, but if one were to launch an investigation, one would not even be able to prove whether the message was posted using the first, legal option, or the second maybe-legal option. The result is exactly the same for everyone, which I find a solid argument for my script's legality.

Whether or not the result is the same is not a consideration that goes into determining script legality. Rate limits and one-input-per-action are the biggest factors.

Nations that violate the Script Rules have had severe punishments in the past. I'm sure an admin will come along and give an official ruling as to your script's legality sometime. I don't think I'm misreading the rules, though.

[Agadar]

While I appreciate you weighing in on the matter of my script's legality, there is little reason to point to the rules, as the rules failed to convince me one way or the other that my script would be illegal, which is the whole reason why I'm here to ask an official moderator's opinion in the first place.

You're right that I am not a moderator or admin. I don't presume to give an "official" answer, but I would argue that since the script rules explicitly say that "It is illegal to use a tool to automatically cause something in the gameworld to change, other than your own nation" and the fact that the Regional Message Board is not a part of any player's nation, that it is against the rules for a script to automatically (that is, without player input at the rate of one input--mouse click, for example--to one action) make a change to it (for example, by adding a post, suppressing a post, or unsuppressing a post).

A) For starters, sending RMB messages isn't explicitly stated as a restricted action, nor is the 'gameworld' explicitly defined: only examples are given, among which the RMB is not. So, is the RMB part of the gameworld? Are the forums part of the gameworld? Is the entire website the gameworld? It is not clear where the borders exactly are.

My understanding is that everything at nationstates.net is part of the gameworld. Regions, nations, the WA, factbooks/dispatches, Activity pages, dossiers, etc. The Regional Message Board is a part of the region, which definitely places it within the borders of the gameworld. The examples listed in the Script Rules do not suggest that they are exhaustive, as that would be a ridiculously long list.

forum.nationstates.net is the forum, which is not a part of the game world as far as I am aware. Players are allowed to use scripts to scrape the gameworld, but scripts are explicitly prohibited on the forum.

B) Furthermore, IF the RMB is indeed considered part of the gameworld, then I would still argue for the legality of my script. Consider the following two scenarios:
- Every day before breakfast, I run a script that pulls data from the API, compiles it neatly in a message, and sends that message to the RMB. (This is legal according to the rules);
- Every day before breakfast, a script is run automaticaly that pulls data from the API, compiles it neatly in a message, and sends that message to the RMB. (This MIGHT be legal or not according to the rules);

If my interpretation is correct, since the second scenario causes a change to the gameworld outside your own nation automatically, it is illegal per the script rules. The first one relies on a player input (one input per action) to cause the script to produce its result, which would be legal.

The outcome is exactly the same: the exact same neatly composed message is posted on the RMB at the exact same time every day. Not only that, but if one were to launch an investigation, one would not even be able to prove whether the message was posted using the first, legal option, or the second maybe-legal option. The result is exactly the same for everyone, which I find a solid argument for my script's legality.

Whether or not the result is the same is not a consideration that goes into determining script legality. Rate limits and one-input-per-action are the biggest factors.

Nations that violate the Script Rules have had severe punishments in the past. I'm sure an admin will come along and give an official ruling as to your script's legality sometime. I don't think I'm misreading the rules, though.

I suppose the scenarios I posted and the argument for legality I derive from them is approaching philosophical levels, so I won't indulge in that and wait for a moderator to give an official ruling.

Just as a little thought game, though: what if instead of my own person pressing the send button for my script, I trained a crow to do that? Would that be legal? Is an action committed by a trained animal considered 'automatic'?

Or let's go even further: what if instead of my own person pressing the send button, I had an AI do it for me, and said AI had all qualifications of a sentient, self-aware individual? Would it still be considered 'automatic' if this AI, indistinguishable from Man, were to press the send button?

[Eluvatar]

Once again some questionable characters have made their way into the happenings stream and caused me grief:

Event 71933277:

Code: Select all

<EVENT id="71933277">
<TIMESTAMP>1453310360</TIMESTAMP>
<TEXT><![CDATA[@@i11uminati666@@ changed its national demonym adjective to "I11uminati" and its demonym plural to "I11uminatis".]]></TEXT>
</EVENT>

Edit: to clarify, as it is invisible in my post, there appears to be a 0x08 byte in there, between the s and the ". (0x08 is of course backspace in ASCII).

If this could be prevented in future and/or corrected in the database I would greatly appreciate it