NationStates API (nationdata/regiondata)

[Imperium Anglorum]

reset the CTE-by-inactivity timer?

I too would like to know this.

[Trotterdam]

If it updates the "Most Recent Government Activity" timer then it probably prevents CTEs.

What's the time limit for non-PIN logins? Currently it just says "within a few seconds".

[[violet]]

using this to view the data, then using the nation pages to actually execute the operations wouldn't be more efficient timewise for me yet, despite the higher rate limits for API.

The next step after filling out the private shards will be to add an API that lets you make changes to nations, like answering issues, rather than just gathering information about them. Long-term, I aim to migrate all script/bot activity to the API, which would provide several advantages for us and legal scripters.

Also for just clicking the link (in browser) from my logged in nation, would it be able to appear authenticated so you can view what you'd get for yourself.

Unfortunately no, as this would make the API vulnerable to XSS attacks using your cookies. You need to use headers.

Does accessing a private shard reset the CTE-by-inactivity timer?

Yes.

What's the time limit for non-PIN logins? Currently it just says "within a few seconds".

Currently you get a 409 Conflict error from the API if you attempt to authenticate via Password or Autologin within 6 seconds of a previous successful login. The exact time period will change, though. It will never be higher than 30 seconds.

[Flanderlion]

using this to view the data, then using the nation pages to actually execute the operations wouldn't be more efficient timewise for me yet, despite the higher rate limits for API.

The next step after filling out the private shards will be to add an API that lets you make changes to nations, like answering issues, rather than just gathering information about them. Long-term, I aim to migrate all script/bot activity to the API, which would provide several advantages for us and legal scripters.

Also for just clicking the link (in browser) from my logged in nation, would it be able to appear authenticated so you can view what you'd get for yourself.

Unfortunately no, as this would make the API vulnerable to XSS attacks using your cookies. You need to use headers.

Does accessing a private shard reset the CTE-by-inactivity timer?

Yes.

This sounds very useful. We will get a grace period to move things over to the new action API right when it comes out?

So accessing the private shard is just like logging in, there isn't any cons to it (except for atm. you can't do any actions with it, just collect info that a normal autologin script can do).

Also, had no clue about XSS attacks before this (bar a vague idea).

[[violet]]

Long-term, I aim to migrate all script/bot activity to the API, which would provide several advantages for us and legal scripters.

We will get a grace period to move things over to the new action API right when it comes out?

Yes, it will be long slow move, if it happens at all.

[Caelapes]

We will get a grace period to move things over to the new action API right when it comes out?

Yes, it will be long slow move, if it happens at all.

I assume that since this will eventually allow users to make changes to their nations through the API (and also apparently counts as a log-in -- does it show that it's an API login and not a front-end login in the moderator panel/however you check nations' IP addresses?), that there is a recommendation against sharing PINs and especially autologins for the purposes of allowing other users to run puppet-maintaining scripts?

[The United Island Tribes]

I believe PIN for private shards is not working as described.

When I was implementing authentication for my library, I noticed the PIN seemed to have wrongly behaved the same way as Password and AutoLogin in some cases.

I noticed this when I was looking at my issues (Being logged in at the same time does work, howevver) in my browser at the same time the test script was running. While I might understand why this would cause a forbidden error (Viewing issues may require login verification that would reset the Pin), it actually returns a conflict error (409).
The documentation implies that Pins should not get conflict errors (Only 403 forbidden errors when the PIN is reset), so I am not sure if this an error or intended behavior.

[[violet]]

The documentation implies that Pins should not get conflict errors

This is correct: You can't get a 409 Conflict error from a valid Pin. You can, however, get a 409 if you send an expired Pin along with a Password or Autologin header, since that will fallback to a new login attempt, as per the flowchart diagram in the API doc.

[[violet]]

I assume [...] there is a recommendation against sharing PINs and especially autologins for the purposes of allowing other users to run puppet-maintaining scripts?

Yes, from a moderation point of view, you are responsible for your account, even if you give someone else your login credentials and they misuse them.

[Nationstates API Test Nation]

The documentation implies that Pins should not get conflict errors

This is correct: You can't get a 409 Conflict error from a valid Pin. You can, however, get a 409 if you send an expired Pin along with a Password or Autologin header, since that will fallback to a new login attempt, as per the flowchart diagram in the API doc.

I will look into this, however I do not believe my script the password with the PIN. It instead catches a 403 error and sends a request with the password/autologin

EDIT: This nation is a test nation The United Island Tribes

[Atagait Denral]

I found an incredibly handy work-around for getting delegate information via the API. It turns out polling all 19,131 regions isn't necessary. You can cut out all founderless regions, password regions, and class regions. Rather than taking 10 hours of requesting region data every 2 seconds, it neatly cuts it in half where you only have to spend about 5 hours.

It's still an absolutely absurd amount of time... but gotta get those non-exec founders somehow, amiright?

[HMS Unicorn]

I've added "Private Shards," for when you want to access information that's only available to a logged-in nation.

For now the only shard is "unread", which will tell you how many new TGs, Issues, etc, you have. But I aim to expand it in the future to cover telegrams, issues, and more. So please give this a test and let me know what you think.

For details see "Private Shards" in the API doc!

Late to the show, but I just got the chance to play with this.

Thanks for making this, very interesting change. I've been considering requesting some kind of "private" API calls for a while now, but I always thought it'd be very unlikely they'd be implemented, given how the API has always been strictly limited to public information.

I've moved my puppet management script to the API.

Since you've also asked for ideas about things to add to the private API, here are some suggestions. These correspond to tasks I currently have to do by making game-side calls to log into the nation and perform actions from there:

1) Getting a list of IDs for all the telegrams a nation has in their Sent folder.
2) Using the above IDs, getting details for each such telegram (text, creation date, recruitment/campaign/regionwide/welcoming classification, template or API classification, list of recipients or delivery reports).
3) Creating new telegram templates or API templates for that nation (obviously *not* sending them, unless it is through the telegram API).
4) Editing pre-existing factbooks and dispatches owned by that nation (note that this is not the same as creating new dispatches with that nation).

I currently use 1-2 to automatically monitor the success rates of recruitment telegrams and periodically produce reports, graphs etc.

I do not do 3, but it would be helpful for automatically updating telegram templates that reference, say, region officials etc. that tend to change frequently.

Finally, I use 4 to automatically maintain dispatches that need to be updated frequently. Examples would be TNP's WADP (updating regional officials), and daily endotarting census.

Thanks again for making this!

[HMS Unicorn]

Bug report

I came across this nation: the_will_of_christ. Even though the nation is present in region Europeia, it is not listed in the following API call:

http://www.nationstates.net/cgi-bin/api.cgi?region=europeia&q=nations

It is also not mentioned in either the region or nation dumps.

On the other hand, it does seem to be present in the nation API, e.g.,

http://www.nationstates.net/cgi-bin/api.cgi?nation=the_will_of_christ&q=region

The nation moved from The West Pacific to Europeia during the major update of July 20th. It moved into Europeia after it had finished updating, and it moved out of The West Pacific while it was updating. I do not know whether the nation itself had updated in TWP by the time it moved.

The fact that it seemingly missed an update may be the cause of the bug, though it has been quite a while since then.

Regarding this bug report, the nation in question has now CTEed, so the issue is no longer pertinent.

I don't know whether the bug was fixed by admins before the nation died. I thought it'd be worth posting a reminder about this, in case the admins still intend to look into this.

[Atagait Denral]

similar to unread TGs, having a shard for unanswered issues would be helpful
And the private shard would also be helpful for altering nation cosmetics such as flags, mottos, etc
Having the ability to manage your entire puppet fleet with one script would be incredibly handy.

Edit:
Just started to play around with it,
Being able to retrieve your unread TGs.

[Eluvatar]

3) Creating new telegram templates or API templates for that nation (obviously *not* sending them, unless it is through the telegram API).

That is, at least currently, against the rules, within or without the API.

The reason, basically, is to make sure scripters can't make individualized messages the way manual message-senders can (i.e. remarks about the nation's motto or the like). It is not legal to create templates without user action. I realize that the use-case you have in mind is for clerical changes to telegrams that would still be sent to many nations without 'customization', but the technical rule has been written to have a clear, technical, line.

[HMS Unicorn]

That is, at least currently, against the rules, within or without the API.

The reason, basically, is to make sure scripters can't make individualized messages the way manual message-senders can (i.e. remarks about the nation's motto or the like). It is not legal to create templates without user action. I realize that the use-case you have in mind is for clerical changes to telegrams that would still be sent to many nations without 'customization', but the technical rule has been written to have a clear, technical, line.

Makes sense. Given what the reasoning for the illegality is, I imagine that this is unlikely to change with expansions to the private API.

In any event, I hope applications 1-2 and 4 from my post, which are completely independent from this one, will be considered.

[Maplou]

Is there anyone who has an example of private shards with curl for php or any other method to get it over the web?

[HMS Unicorn]

Is there anyone who has an example of private shards with curl for php or any other method to get it over the web?

The API shows an example, which needs to be modified a little bit for a legal API call. If you want to get the unread data, here is how you should edit it¹:

Code: Select all

curl -A "YOUR_USER_AGENT" -H "Password: YOUR_PASSWORD" "https://www.nationstates.net/cgi-bin/api.cgi?nation=YOUR_NATION&q=unread"

Note that https is necessary, simply http won't work. You can replace "Password" with the autologin code or pin if that's what you want to use.

If you want to see the headers containing the pin or autologin code, you should use this:

Code: Select all

curl -A "YOUR_USER_AGENT" -H "Password: YOUR_PASSWORD" -I "https://www.nationstates.net/cgi-bin/api.cgi?nation=YOUR_NATION&q=unread"

Then in the response, search for the line "X-pin" or "X-autologin" as appropriate.

Finally, if you want to see both the headers and the actual unread data, you should use this:

Code: Select all

curl -A "YOUR_USER_AGENT" -H "Password: YOUR_PASSWORD" -D - "https://www.nationstates.net/cgi-bin/api.cgi?nation=YOUR_NATION&q=unread"

Note the dash, -, after -D, it is not a typo.

¹It is possible to include the user-agent as part of the request headers passed with -H, but I prefer to set it separately using the -A flag.

[HMS Unicorn]

I've added "Private Shards," for when you want to access information that's only available to a logged-in nation.

For now the only shard is "unread", which will tell you how many new TGs, Issues, etc, you have. But I aim to expand it in the future to cover telegrams, issues, and more. So please give this a test and let me know what you think.

For details see "Private Shards" in the API doc!

I think it would be better to edit the example curl call shown in the API, to include a user agent (see my post immediately above for code if necessary). Users may be inclined to copy/paste it as it is now, resulting in curl calls without a user agent, and therefore unwittingly breaking the API terms of use.

Sorry for the double post, but I didn't want this to be lost among the instructions in my previous post.

[Maplou]

Is there anyone who has an example of private shards with curl for php or any other method to get it over the web?

The API shows an example, which needs to be modified a little bit for a legal API call. If you want to get the unread data, here is how you should edit it¹:

Code: Select all

curl -A "YOUR_USER_AGENT" -H "Password: YOUR_PASSWORD" "https://www.nationstates.net/cgi-bin/api.cgi?nation=YOUR_NATION&q=unread"

Note that https is necessary, simply http won't work. You can replace "Password" with the autologin code or pin if that's what you want to use.

If you want to see the headers containing the pin or autologin code, you should use this:

Code: Select all

curl -A "YOUR_USER_AGENT" -H "Password: YOUR_PASSWORD" -I "https://www.nationstates.net/cgi-bin/api.cgi?nation=YOUR_NATION&q=unread"

Then in the response, search for the line "X-pin" or "X-autologin" as appropriate.

Finally, if you want to see both the headers and the actual unread data, you should use this:

Code: Select all

curl -A "YOUR_USER_AGENT" -H "Password: YOUR_PASSWORD" -D - "https://www.nationstates.net/cgi-bin/api.cgi?nation=YOUR_NATION&q=unread"

Note the dash, -, after -D, it is not a typo.

¹It is possible to include the user-agent as part of the request headers passed with -H, but I prefer to set it separately using the -A flag.

I was looking for some way to I guess, use it on the web. For Example in javascript, php or html

[[violet]]

I think it would be better to edit the example curl call shown in the API, to include a user agent

Yes, indeed! Done, thanks.

[[violet]]

Added a new private Nation shard: "notices."

[Scilla]

So I am making a discord chatbot using discord.js and I want to have a command where you type !nationname: (and then the name of the nation), and it would reply with a link to the nation you just named. One of my regionmates did the same, only in another language. How would I do this? Do I need NS Api?

[Flanderlion]

So I am making a discord chatbot using discord.js and I want to have a command where you type !nationname: (and then the name of the nation), and it would reply with a link to the nation you just named. One of my regionmates did the same, only in another language. How would I do this? Do I need NS Api?

Wrong thread, probably better to split it out. But what you need to do is receive a string from the user (whatever they type, e.g. Flanderlion) and turn it into http://www.nationstates.net/nation=flanderlion. It doesn't need an API, or in fact need to interact at all with the NS site, only if the bot is pulling data from the site like population, influence, endorsements etc.

So in pseudo code:
User input = String Nation_Input
URL = http://www.nationstates.net/nation=
Output = (URL + Nation_Input);
Print Output;

On topic though - is there any way to get just the new notifications rather than the last X notifications with the new shard?

[[violet]]

On topic though - is there any way to get just the new notifications rather than the last X notifications with the new shard?

By default it works the same way as the regular site, where it returns new notifications plus any from the last 48 hours. The new ones have a tag like: <NEW>1</NEW>. I could add a "newonly" parameter or something.