NationStates API (nationdata/regiondata)

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

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.

Aye, that's true, and I used to do that. However, what I am looking for is a long-term solution, so that I can schedule my processes once and not have to worry about adjusting the schedule for several months. The above is not a long-term solution for the reason you mentioned (and for the fact that automatically planting a puppet in any new last-updating region is illegal).

[Sedgistan]

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.

Confirmed.

[Agadar]

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.

Confirmed.

That is what I feared. Thank you for confirming it.

[Drachmaland]

By the way, if I am to use script automation for changing something in a nation of mine, is it adequate that I'm logged in my main nation — or do I have to be each time logged in the respective nation being changed?

[Eluvatar]

By the way, if I am to use script automation for changing something in a nation of mine, is it adequate that I'm logged in my main nation — or do I have to be each time logged in the respective nation being changed?

To change a nation's settings one has to be logged in to that nation.

[Drachmaland]

By the way, if I am to use script automation for changing something in a nation of mine, is it adequate that I'm logged in my main nation — or do I have to be each time logged in the respective nation being changed?

To change a nation's settings one has to be logged in to that nation.

Thanks for the confirmation, Eluvatar!

[[violet]]

"delegateauth" should really report the authorities granted to an unfilled delegate seat.

Fixed this and 'founderauthor' to display authorities regardless of whether anyone currently holds the office.

Note that Delegate authorities can change suddenly if an executive Founder moves out of the region, since in that situation the Delegate is automatically granted executive authority.

[Trotterdam]

By the way, if I am to use script automation for changing something in a nation of mine, is it adequate that I'm logged in my main nation — or do I have to be each time logged in the respective nation being changed?

Define "logged in".

The web client your script uses to access the site can be entirely different from your normal browser, and so could have a different set of cookies. In principle, a well-made script could keep as many "logged in to this nation" cookie files as necessary side-by-side, and switch between them according to what nation it's working on now, without ever logging out from any of them.

Of course, the game does have to recognize you as logged in while you're actually doing stuff in the nation. I mean, duh.

[Caelapes]

"delegateauth" should really report the authorities granted to an unfilled delegate seat.

Fixed this and 'founderauthor' to display authorities regardless of whether anyone currently holds the office.

Note that Delegate authorities can change suddenly if an executive Founder moves out of the region, since in that situation the Delegate is automatically granted executive authority.

Eyyy, thanks for this.

[Drachmaland]

By the way, if I am to use script automation for changing something in a nation of mine, is it adequate that I'm logged in my main nation — or do I have to be each time logged in the respective nation being changed?

The web client your script uses to access the site can be entirely different from your normal browser, and so could have a different set of cookies. In principle, a well-made script could keep as many "logged in to this nation" cookie files as necessary side-by-side, and switch between them according to what nation it's working on now, without ever logging out from any of them.

This is what I was implying. Thanks, Trotterdam.

PS Thanks for the 'duh' also, whatever that is.

[Flanderlion]

This might have been mentioned before, but is there a way to see the nations my nation (or another nation) has endorsed? The work around to my knowledge is getting the region list, then getting each nation residing in the regions endorsed by list, which adds up to a lot of requests. I could be missing something obvious here though.

[Drachmaland]

This might have been mentioned before, but is there a way to see the nations my nation (or another nation) has endorsed? The work around to my knowledge is getting the region list, then getting each nation residing in the regions endorsed by list, which adds up to a lot of requests. I could be missing something obvious here though.

If you're using NS++, there's this: http://www.nationstates.net/nation=flan ... dorsements

[Flanderlion]

This might have been mentioned before, but is there a way to see the nations my nation (or another nation) has endorsed? The work around to my knowledge is getting the region list, then getting each nation residing in the regions endorsed by list, which adds up to a lot of requests. I could be missing something obvious here though.

If you're using NS++, there's this: http://www.nationstates.net/nation=flan ... dorsements

I've used that, and that's great for getting the vast majority of nations, but it doesn't always include all WA nations in the region (even when the nations in question have updated multiple times in the said region). I'm not 100% sure if it is an deliberate loophole left for the creators/maintainers sleepers, or an accident, nor have I figured out exactly what causes it, but NS++ isn't perfect in that regard. It's pretty good for most situations though.

[Eluvatar]

The problem is most likely to be caused by NS++ missing the endorsement event in a flood of other events. I would expect, in that case, for NS++ to eventually check the nation endorsed and see the endorsement, but it could take a long time.

I'm aware of how to correct at least one major aspect of the cause of this in theory, but implementing the solution in practice has been on the back burner for a while because it would involve techniques I haven't used in java before and am uncertain how long it would take. I will try to make it, and NS++ in general, a priority for this month.

In terms of using the NS API to get the list of nations in a region, the list of WA nations, and using that to check all eligible nations to see whether a nation has endorsed them, there is also a subtle problem with this approach. Specifically, the WA Members list is 99.5% accurate (roughly speaking) -- there will generally be a handful of nations which are improperly listed or omitted. This comes up pretty often with very large regions such as The North Pacific. If you wish perfect accuracy, I would advise double checking against the list of nations with WA status in the last nations.xml dump, either directly or using the json list file that I generate daily.

[Flanderlion]

The problem is most likely to be caused by NS++ missing the endorsement event in a flood of other events. I would expect, in that case, for NS++ to eventually check the nation endorsed and see the endorsement, but it could take a long time.

I'm aware of how to correct at least one major aspect of the cause of this in theory, but implementing the solution in practice has been on the back burner for a while because it would involve techniques I haven't used in java before and am uncertain how long it would take. I will try to make it, and NS++ in general, a priority for this month.

In terms of using the NS API to get the list of nations in a region, the list of WA nations, and using that to check all eligible nations to see whether a nation has endorsed them, there is also a subtle problem with this approach. Specifically, the WA Members list is 99.5% accurate (roughly speaking) -- there will generally be a handful of nations which are improperly listed or omitted. This comes up pretty often with very large regions such as The North Pacific. If you wish perfect accuracy, I would advise double checking against the list of nations with WA status in the last nations.xml dump, either directly or using the json list file that I generate daily.

Regarding NS++, the other 2 options of the WA tab are in need of a little more tweaking than the endorsements list, which eventually fix itself over time. The 0.5% is probably what has caused the issues in the past, but it isn't generally an issue.

I'd still prefer an nations endorsed by @nation@ type category in the NS API so less processing etc. on my end with my incredibly limited, basic script kiddie skill level.

[Eluvatar]

I'd still prefer an nations endorsed by @nation@ type category in the NS API so less processing etc. on my end with my incredibly limited, basic script kiddie skill level.

The way NationStates is implemented, that is not very likely to happen soon.

[The United Island Tribes]

I would like to make a request for the API.

Ratelimiting is not really a issue when you are making a script. However when writing a general api wrapper, it is very hard to cover all use cases and to protect from ratelimit breaches.

Currently my python api wrapper uses an internal request tracker to try to prevent api ratelimit bans. The problems with this are numerous. It is single threaded, so only one script can run at a time. Running multiple scripts will most likely result in a ban, and occasionally

This can be solved by having one of these 3 things in the headers

1. A response header where the period you track my ratelimiter begins (Least useful) - I doubt this is how the Rl system works
2. A response header where the period you track my ratelimiter ends (somewhat useful) - I doubt this is how the Rl system works
3. The current amount of requests in the last 30 seconds (extremely useful)

Hopefully 3 is possible. My library would be able to stay under the ratelimit at all times with it, even if mulitple scripts are running.

[Eluvatar]

I would like to make a request for the API.

Ratelimiting is not really a issue when you are making a script. However when writing a general api wrapper, it is very hard to cover all use cases and to protect from ratelimit breaches.

Currently my python api wrapper uses an internal request tracker to try to prevent api ratelimit bans. The problems with this are numerous. It is single threaded, so only one script can run at a time. Running multiple scripts will most likely result in a ban, and occasionally

This can be solved by having one of these 3 things in the headers

1. A response header where the period you track my ratelimiter begins (Least useful) - I doubt this is how the Rl system works
2. A response header where the period you track my ratelimiter ends (somewhat useful) - I doubt this is how the Rl system works
3. The current amount of requests in the last 30 seconds (extremely useful)

Hopefully 3 is possible. My library would be able to stay under the ratelimit at all times with it, even if mulitple scripts are running.

My throttling program handles all of this, and indeed a version of it I threw together in rust can even self-enforce the non-API rate limit in the rules (which isn't enforced by the game directly, but is a rule one should follow). I would recommend its use.

I'm sorry I haven't had time to try to get your library using my system, I may be able to find time this month.

Edit: I'm wondering how you'd use (3) and avoid one script 'hogging' the ratelimit at the expense of other scripts.

[The United Island Tribes]

I would like to make a request for the API.

Ratelimiting is not really a issue when you are making a script. However when writing a general api wrapper, it is very hard to cover all use cases and to protect from ratelimit breaches.

Currently my python api wrapper uses an internal request tracker to try to prevent api ratelimit bans. The problems with this are numerous. It is single threaded, so only one script can run at a time. Running multiple scripts will most likely result in a ban, and occasionally

This can be solved by having one of these 3 things in the headers

1. A response header where the period you track my ratelimiter begins (Least useful) - I doubt this is how the Rl system works
2. A response header where the period you track my ratelimiter ends (somewhat useful) - I doubt this is how the Rl system works
3. The current amount of requests in the last 30 seconds (extremely useful)

Hopefully 3 is possible. My library would be able to stay under the ratelimit at all times with it, even if mulitple scripts are running.

My throttling program handles all of this, and indeed a version of it I threw together in rust can even self-enforce the non-API rate limit in the rules (which isn't enforced by the game directly, but is a rule one should follow). I would recommend its use.

I'm sorry I haven't had time to try to get your library using my system, I may be able to find time this month.

Edit: I'm wondering how you'd use (3) and avoid one script 'hogging' the ratelimit at the expense of other scripts.

While its true that there are solutions to this, I rather not incorporate them into the api wrapper itself. Any solution would need to be purely written in python.

My plan with #3 is to use my current built-in rate-limiter along with the header data to give the api wrapper a better impression on how and when it needs to make requests. Currently my wrapper assumes that you have yet to make any requests to the api (in the last 30 seconds). This isn't always true.

The only real issue with this is where one script makes 50 requests, and another makes 1 request. Since the second script didn't know it would be the 51st request, it will be banned. This would only really be an issue if two scripts are spamming the api as fast as the rate-limit system would let them. The rate-limit system in place already makes it impossible to send more than 48 requests per 30 seconds. So this situation would be rare and easily avoided.

[Imperium Anglorum]

Is it possible to get a region's banlist off the API?

[The Silver Sentinel]

Is it possible to get a region's banlist off the API?

Why would you need it? Just go to that region and look at the ban list yourself.

[New Leppikania]

Is it possible to get a region's banlist off the API?

Why would you need it? Just go to that region and look at the ban list yourself.

You know, "Is it possible to get this off the API?" usually means "I need this information for a script."

[The United Dominion]

Hopefully quick question set that hopefully won't lead to more. I'm receiving this warning when trying to retrieve data within a PHP application:

Warning: file_get_contents(http://www.nationstates.net/cgi-bin/api.cgi?[API-CALL]): failed to open stream: HTTP request failed! HTTP/1.1 403 Forbidden

When I paste the url with the full set of items I want into a browser, I get the xml return with no problem. I just can't seem to get it within my php application. I'm reasonably certain that I could six months ago when I started the project, but since I dropped it for awhile, I don't actually know for sure.

Do I have to use curl rather than file_get_contents? Or is it perhaps that the server my application is hosted on is blocked? Did file_get_contents used to work but now it doesn't?

[Ambroscus Koth]

Hopefully quick question set that hopefully won't lead to more. I'm receiving this warning when trying to retrieve data within a PHP application:

Warning: file_get_contents(http://www.nationstates.net/cgi-bin/api.cgi?[API-CALL]): failed to open stream: HTTP request failed! HTTP/1.1 403 Forbidden

When I paste the url with the full set of items I want into a browser, I get the xml return with no problem. I just can't seem to get it within my php application. I'm reasonably certain that I could six months ago when I started the project, but since I dropped it for awhile, I don't actually know for sure.

Do I have to use curl rather than file_get_contents? Or is it perhaps that the server my application is hosted on is blocked? Did file_get_contents used to work but now it doesn't?

Confirming I have this error as well. I just sent a GHR about it a few minutes ago.

[Caelapes]

I'm assuming it has to do with this:

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.

If that's the case, you'll need to set a useragent: https://joshtronic.com/2013/06/04/speci ... _contents/