NationStates API (nationdata/regiondata)

[Flanderlion]

The latter is definitely not allowed.

Says where? There is a list of restricted actions that may not be scripted using the HTML site, and creating or editing a dispatch is not among them (since it only affects your own nation and not anything else in the game world).

Editing was fine, creating was not pre rewrite of that. I'd stick with the prior interpretation until an admin says otherwise.

[Ferranghia]

Well then, manual posting it is until an API pops up!

[[violet]]

Are there any plans of making an endpoint to create dispatches via the API, or do I have to go the HTML script way in order to do that?

There is an (undocumented) API Nation Private Command for dispatches, which I have now released for testing.

You can add, edit, and remove dispatches by following the same process as currently exists for gifting Trading Cards; namely, you have to:

1. Issue a request and stick "&mode=prepare" on the end
2. Repeat but this time with "&mode=execute&token=TOKEN_GOES_HERE", where TOKEN_GOES_HERE is the value you received back from the server from Step 1.

When creating or editing a dispatch, you have to supply these parameters: title, text, category, subcategory.

When editing or removing a dispatch, you have to supply: dispatchid.

Examples!

Prepare to add a new dispatch:

Code: Select all

curl -H "X-Password: hunter2" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=add&title=Test%20Dispatch&text=Hello%20there.&category=1&subcategory=105&mode=prepare"

Now do it for real, using the supplied token:

Code: Select all

curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=add&title=Test%20Dispatch&text=Hello%20there.&category=1&subcategory=105&mode=execute&token=TOKEN_GOES_HERE"

Edit that dispatch:

Code: Select all

curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatchid=DISPATCH_ID_GOES_HERE&dispatch=edit&title=Test%20Dispatch%20Edited&text=I%20Was%20Edited.&category=1&subcategory=105&mode=prepare"

curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatchid=DISPATCH_ID_GOES_HERE&dispatch=edit&title=Test%20Dispatch%20Edited&text=I%20Was%20Edited.&category=1&subcategory=105&mode=execute&token=TOKEN_GOES_HERE"

Remove that dispatch:

Code: Select all

curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=remove&dispatchid=DISPATCH_ID_GOES_HERE&mode=prepare"

curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=remove&dispatchid=DISPATCH_ID_GOES_HERE&mode=execute&token=TOKEN_GOES_HERE"

Please test and let me know how you go!

[[violet]]

Gifting cards is now supported via API! Documentation is under Nation Private Commands.

Please note a change in the function of this Private Command: Previously, a successful "prepare" would return a token wrapped in <TOKEN> tags, like this:

Code: Select all

<NATION id="testlandia">
<SUCCESS><TOKEN>1p1ELXkPJ5tq14GA8vduNwNFDEpAA2UxA8A03OavAOo<TOKEN></SUCCESS>
</NATION>

... but now it doesn't, so it looks like this:

Code: Select all

<NATION id="testlandia">
<SUCCESS>1p1ELXkPJ5tq14GA8vduNwNFDEpAA2UxA8A03OavAOo</SUCCESS>
</NATION>

Generally the API doesn't do breaking changes like this, but the Trading Cards API is still in public beta, and can change without warning.

[Ferranghia]

Are there any plans of making an endpoint to create dispatches via the API, or do I have to go the HTML script way in order to do that?

There is an (undocumented) API Nation Private Command for dispatches, which I have now released for testing.

Please test and let me know how you go!

Woohoo! I'll let you know as soon as I can

[9003]

Any word yet on setting up the API to do
https://www.nationstates.net/cgi-bin/ap ... a;season=1
rather then searching by card ID?

if it seems to be presenting challenges that's okay too I just didn't want to have it get forgotten about if its an easy implantation

[Trotterdam]

Any word yet on setting up the API to do
https://www.nationstates.net/cgi-bin/ap ... a;season=1
rather then searching by card ID?

if it seems to be presenting challenges that's okay too I just didn't want to have it get forgotten about if its an easy implantation

This was answered here:

Loving the card API so far, thank you for implementing it and letting devs play around with the beta.
Probably the most major request from me would be to be able to ask for a card by a specified nation name rather than card ID. For instance, rather than querying for "?q=card+info;cardid=1;season=1", I'd like it if there were an option to query via "?q=card+info;cardname=testlandia;season=1" or similar.

Unfortunately this isn't possible to add without slowing down the Cards API, since it would require loading a nation.

[August]

-dispatch snip-

This is great--I imagine a lot of people have been waiting for this, so thank you for implementing it! However, the whole problem I had with automatically publishing dispatches via the HTML site was that I could only do so with GET requests, which were limited to something like 6000 characters. (I know POST requests should be used to send larger payloads, but those gave me security checks no matter what I tried). Publishing dispatches via the API is giving me the same problem: low character limits, and 414 URI Too Long errors if I go over. Is there any way this limit could be removed, or is this endpoint intended just for short dispatches? Disregard. Finally got it to work.

As a minor note, the code block for edits is missing this snippet.

Code: Select all

&dispatchid=DISPATCH_ID_GOES_HERE

[Trotterdam]

You can use POST requests on the API? I do.

[August]

You can use POST requests on the API? I do.

I tried it earlier and it failed, and as mentioned before, it failed many times while interacting with the HTML site. Naturally, I just tried it again and it worked for the first time ever, so thank you for prompting me to give it one more shot.

[Ferranghia]

You can use POST requests on the API? I do.

I tried it earlier and it failed, and as mentioned before, it failed many times while interacting with the HTML site. Naturally, I just tried it again and it worked for the first time ever, so thank you for prompting me to give it one more shot.

I figured out my POSTs were being turned into GETs by C#'s http client because I was posting all my requests to https://nationstates... instead of https://www.nationstates, my requests were then being redirected and for some reason the client dropped the post.

All's good now.

[[violet]]

You can use POST requests on the API? I do.

Do you ever!

Gloomhaven is by far our most prolific bot.

[[violet]]

Updated API doc to cover Nation Private Command "dispatch".

[Minoa]

Hello, is there a API shard for determining whether a nation is on vacation mode or not? This could benefit those who wish to improve the efficiency of the pings (to prevent the nation from ceasing to exist due to inactivity), and also benefit those who see vacation mode indicators as a way to improve the efficiency of telegrams. [EDIT: that was stupid, Minoa] For me, it would tell me which nations are not in vacation mode, so I can change them to use vacation mode.

[Trotterdam]

Telling whether a nation that isn't yours is in vacation mode is something you can't do on the normal site, so I don't see why you should be able to do it in the API.

[Minoa]

Telling whether a nation that isn't yours is in vacation mode is something you can't do on the normal site, so I don't see why you should be able to do it in the API.

I am sorry if I slipped up there.

Maybe I should revise my idea to be a private shard where users can check if one of their nations is in vacation mode or not.

[The World Capitalist Confederation]

How do I make an api to send out campaign telegrams to 8 people at a time from a selected list?

What I'm trying to do is have a list of every delegate sorted by region size, and then have the api send out the same campaign telegram to 8 of them at a time.

I'm surprised that these stamp-free campaign tools don't exist already, as, whilst slow, they are free and would offer some level of equity to the WA campaigning field.

[Frisbeeteria]

How do I make an api to send out campaign telegrams to 8 people at a time from a selected list?

You don't. API telegrams go out one at a time and have a throttle. Manual telegrams may be sent to 8 recipients at once with no throttle. Stamped telegrams can be sent to thousands of recipients at once with no throttle.

I'm surprised that these stamp-free campaign tools don't exist already, as, whilst slow,

They do, and the speed choice is deliberate. You can work hard manually, pay for stamps, or accept the limits of the API to do set-it-and-forget-it campaigning. We have no intention of making free mass mailing (aka spamming) any easier.

[The World Capitalist Confederation]

How do I make an api to send out campaign telegrams to 8 people at a time from a selected list?

You don't. API telegrams go out one at a time and have a throttle. Manual telegrams may be sent to 8 recipients at once with no throttle. Stamped telegrams can be sent to thousands of recipients at once with no throttle.

I'm surprised that these stamp-free campaign tools don't exist already, as, whilst slow,

They do, and the speed choice is deliberate. You can work hard manually, pay for stamps, or accept the limits of the API to do set-it-and-forget-it campaigning. We have no intention of making free mass mailing (aka spamming) any easier.

I'm willing to take the limits of the API. How do I get the API to start sending my campaign telegram template?

[Frisbeeteria]

How do I get the API to start sending my campaign telegram template?

Uhh, that's not how it works. You need a script. Look at the first post in this thread, and maybe at some of the other posts in Technical for suggestions.

[The Northern Light]

Updated API doc to cover Nation Private Command "dispatch".

Thank you very much for implementing this! I finally got a chance to port all of my dispatch maintenance script to the API and it works great .

---------

I had a couple of questions:

1) Do the "mode=prepare" and "mode=execute" count as two separate API requests as far as rate limit is concerned?

2) Is it necessary to provide the full dispatch title and text for the "mode=prepare", or can we have placeholders for those and only provide the final version for "mode=execute"? I am asking because the dispatch text can be very large in size, and sending it over twice when it is only being used once seems like a huge waste of bandwidth for both the NS server and the person making the API request.

---------

I also had a suggestion: Would it be possible to remove the "category" part of the request? It seems redundant, given that we already specify a "subcategory", and the "category" is nothing else but the first digit of the "subcategory".

I imagine the reason why we have to specify both is that the gameside POST request for editing dispatches requires both. So, if that's hard to change, that's understandable, but I thought I should bring up this small suggestion anyway.

[The Northern Light]

Request 1

Would it be possible to have all private API requests that successfully authenticate return the currently valid pin, regardless of how authentication was done (password, autologin, or pin)?

Short explanation: It makes management of private API login sessions across multiple scripts that run in random order easier.

Long explanation: After a fair amount of experimentation, I've concluded that the most robust way to handle API authentications when multiple scripts are accessing the same nation in random order is to implement a makeshift "cookie" system.

Here is how I thought this would work: Let's say that "cookie.txt" is a pre-specified file somewhere in the system that all scripts can access. Using this file, I make sure that every private API call follows the same pattern shown below (I'll use a mix of curl and pseudocode for demonstration, and I skip the use of "autologin" just to keep the example simple):

Code: Select all

your_pin = readPinFromCookie("cookie.txt")

curl -A "${your_user_agent}" -H "X-pin: ${your_pin}" -H "X-password: ${your_password}" -D "cookie.txt" "https://www.nationstates.net/cgi-bin/api.cgi?nation=${your_nation}&q=ping"


This way, before I make any private call, I'd check the "cookie" for the latest available pin. Then, I'd make a private API call providing both the pin and password. If the pin is still valid, the request will go through. If it's not, authentication will work through the password. In both cases, the returned headers will be written in the "cookie", to be used by future requests.

Unfortunately, the above does not work. The reason is that, when authentication with pin is successful, the returned headers do not include the X-pin header. Therefore, the updated cookie will no longer have the pin, and future private requests will end up always falling back to the password. In turn, this means that, when many calls in quick succession are made, half of them will run into 409 conflicts.

This problem can be circumvented by modifying the above call pattern as follows:

Code: Select all

your_pin = readFirstPinFromCookie("cookie.txt")

curl -A "${your_user_agent}" -H "X-pin: ${your_pin}" -H "X-password: ${your_password}" -D "cookie.txt" "https://www.nationstates.net/cgi-bin/api.cgi?nation=${your_nation}&q=ping"

appendLatestPinToCookie("cookie.txt", "${your_pin}")


This solution works, and I've already adjusted all of my code to use it. But it just seems unnecessarily complicated, and prone to result in bugs and confusion. Changing the private API responses so that the returned headers always include the currently valid pin, regardless of how authentication was performed, will help streamline the above pipeline, by making it possible to use the simpler first version.

---

Request 2

Would it be possible to make private API requests compatible with cookies, including cookies from gameside sessions? By "compatible" I mean that: 1) the authentication information from a successful private API call can be returned through a cookie instead of headers; and 2) a cookie available from a previous gameside session or successful private API call can be used for authentication on a subsequent private API call.

Explanation: This request is for three reasons. The first reason is that it makes the pipeline I described above even simpler (and, arguably, closer to standard practice for persistent sessions, which tend to rely on cookies rather than header info). I can make all private API calls follow a pattern like:

Code: Select all

curl -A "${your_user_agent}" -H "X-password: ${your_password}" -b "cookie.txt" -c "cookie.txt" "https://www.nationstates.net/cgi-bin/api.cgi?nation=${your_nation}&q=ping"


There's no longer need for manual processing of returned headers.

The second reason is that it'd help reduce conflicts between gameside sessions and private API sessions. To give an example: I often find myself setting a script to perform several automated tasks on my nation through the private API (backup notifications, update a whole bunch of dispatches, send a round of card gifts, etc.). These tasks can run for several minutes.

If during that time I forget that the script is running and log into my nation, I end up making many of the private API calls fail to authenticate. Sometimes I don't even need to intentionally do a new gameside login; if I so much as have the nation page open on a tab, and I navigate to that tab, I can end up interrupting the API script that is running at the same time. Allowing the private API calls to interface with the cookies used by the gameside would help greatly reduce this type of issues.

---

None of the above two requests are absolutely critical as far as I am concerned, as at this point my codebase works robustly enough without them. But I think they would be quality-of-life improvements for both myself, and potentially other users having similar use cases. Especially request 1 should be straightforward.

Thanks for the consideration!

[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

[Phydios]

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 not Nation ID either...odd. I expected that to be the answer.

[9003]

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.