NationStates API (nationdata/regiondata)

[Poopsadon]

Does anyone know if there is a recommended way to make calls to answer issues. At the moment my understanding is the the API lets you access data but not modify anything but if I'm mistaken I'd be curious to know how.

My hope was to make a simple script to comb through a series of my puppets and randomly determine their daily fate

[Trotterdam]

I don't think there is currently an API call for that. A private API shard is expected at some point in the indefinite future, but currently even the private API shards are all read-only.

Unless [violet] is willing to take the time to add that, your best option is to write a non-API script that uses the same issue-answering URL human players do. Note that non-API scripts have different rules from API-using scripts, the most important one of which (for your application) is that the ratelimit is 10 per minute instead of 100 per minute.

Note that you can make things a little easier on both your script and the server by appending /template-overall=none to the URL, for example http://www.nationstates.net/page=dilemmas/template-overall=none. I'm not sure where I learned that, the linked script rules seem to make no mention of it.

Or more topically, http://www.nationstates.net/page=enact_dilemma/dilemma=X/choice-Y=1/template-overall=none (don't click on that!), where X is the number of the issue, and Y is the internal number of the option (usually one less than the displayed number, so 0 for the first option, 1 for the second option, etc., but can be different if some options don't appear due to option validities, and -1 for dismissal).

[Poopsadon]

I don't think there is currently an API call for that. A private API shard is expected at some point in the indefinite future, but currently even the private API shards are all read-only.

Unless [violet] is willing to take the time to add that, your best option is to write a non-API script that uses the same issue-answering URL human players do. Note that non-API scripts have different rules from API-using scripts, the most important one of which (for your application) is that the ratelimit is 10 per minute instead of 100 per minute.

Note that you can make things a little easier on both your script and the server by appending /template-overall=none to the URL, for example http://www.nationstates.net/page=dilemmas/template-overall=none. I'm not sure where I learned that, the linked script rules seem to make no mention of it.

Or more topically, http://www.nationstates.net/page=enact_dilemma/dilemma=X/choice-Y=1/template-overall=none (don't click on that!), where X is the number of the issue, and Y is the internal number of the option (usually one less than the displayed number, so 0 for the first option, 1 for the second option, etc., but can be different if some options don't appear due to option validities, and -1 for dismissal).

This is tremendously helpful; thank you! I was unaware of the template-overall=none trick but it definitely makes it easier to pick out the info I need.

[Imperium Anglorum]

A bug report. Currently, when calling this query:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?wa=1&id=257&q=resolution

For the /WA/RESOLUTION/OPTION/text() field, I get 0 instead of the actual Area of Effect/Strength, Automobile Manufacturing.

This is the same with most other categories as well. For Mild resolutions, it shows 0 instead of Mild.

[Imperium Anglorum]

Also, would it be possible to have an API query which tells us what kind of telegram is being sent? Something like:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?a=infoTG&tgid=(TGID)&key=(Secret Key)

Returning information on the telegram itself, like the delivery data, by whom the telegram was blocked, and what kind of telegram is being sent (recruitment, campaign, unmarked).

[HMS Unicorn]

Also, would it be possible to have an API query which tells us what kind of telegram is being sent? Something like:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?a=infoTG&tgid=(TGID)&key=(Secret Key)

Returning information on the telegram itself, like the delivery data, by whom the telegram was blocked, and what kind of telegram is being sent (recruitment, campaign, unmarked).

This would be tremendously useful.

[Agadar]

Also, would it be possible to have an API query which tells us what kind of telegram is being sent? Something like:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?a=infoTG&tgid=(TGID)&key=(Secret Key)

Returning information on the telegram itself, like the delivery data, by whom the telegram was blocked, and what kind of telegram is being sent (recruitment, campaign, unmarked).

I'd be glad with something as simple as an API call that requires a telegram id and returns the type of the corresponding telegram template (recruitment/campaign/unmarked). With something like that, us auto-telegrammer developers wouldn't have to rely any more on the users -possibly incorrectly- supplying the telegram type (which we need to know for the rate limits).

Never mind the above, I misread your feature request. I thought you meant for the telegram API to return that data, but you mean for an entirely new API call to do so. I would like something like that as well.

[Imperium Anglorum]

With something like that, us auto-telegrammer developers wouldn't have to rely any more on the users -possibly incorrectly- supplying the telegram type (which we need to know for the rate limits).

I too trust my code more than the users.

[Panther Ausf G]

Granted, this is likely a one-off thing, but is there a chance that we can get some API shards for the nuclear war, if possible?

[[violet]]

Unfortunately it's not feasible to create API support for one-off events.

[TKS 20mm]

Figured as much, but might as well ask anyway!
Thanks for the response ^^

[Drachmaland]

Would it be possible that NS API incorporates a new public shard to query a nation's id number?
I'm referring to the number that is currently used to resolve WA census ties in the ranking system.

[HMS Unicorn]

Request

Would it be possible to add a shard providing the most recent date a nation joined the WA (or, say, 0 if the nation is not a member)?

This would be very helpful for various regional surveys we conduct in TNP and Europeia, to try to improve our WA membership rates.

I understand that the utility of this is relatively limited, but if this is something the game already tracks and can be easily added to the API, it would be very convenient. Otherwise, I can get this information from elsewhere.

Thanks!

[Roavin]

Request

Is there a way to make the happenings shard easier to parse and store? At the moment, only the <TEXT> tag is included, and script authors relying on happenings must manually parse that text. While parsing out nations/regions are easy due to the use of tags with their canonical name (so we can just regex-match), other things are not so easy. Useful tags may be:

• <REGION> - self-explanatory, optional
• <NATION> - self-explanatory, optional
• <TYPE> - This could be one of the filter types (law, cte, etc., or "other" for custom happenings)
• <ISSUE_ID> - If this is a law happening, the ID of the issue that was answered
• <ISSUE_ANSWER> - If this is a law happening, which answer was given for that issue
• <INFLUENCE> - for Influence rank changes, from and to
• ...etc...

I store happenings in a database, currently with a TEXT column plus pre-parsed region1, region2, nation1, nation2 columns for search. I intend to expand that to include at least the type, and possibly modify it so that when it's unambiguous, the text column is just NULLed to save space in the database. Besides, it just makes it easier to search in the DB in general - I can build indices, do funky joins, what have you.

[Eluvatar]

Would it be possible that NS API incorporates a new public shard to query a nation's id number?
I'm referring to the number that is currently used to resolve WA census ties in the ranking system.

It would certainly be possible. As [v] and I don't see a problem with doing it, it'll probably be done soon.

Request

Would it be possible to add a shard providing the most recent date a nation joined the WA (or, say, 0 if the nation is not a member)?

This would be very helpful for various regional surveys we conduct in TNP and Europeia, to try to improve our WA membership rates.

I understand that the utility of this is relatively limited, but if this is something the game already tracks and can be easily added to the API, it would be very convenient. Otherwise, I can get this information from elsewhere.

Thanks!

The feature you request cannot easily be done.

Request

Is there a way to make the happenings shard easier to parse and store? At the moment, only the <TEXT> tag is included, and script authors relying on happenings must manually parse that text. While parsing out nations/regions are easy due to the use of tags with their canonical name (so we can just regex-match), other things are not so easy. Useful tags may be:

• <REGION> - self-explanatory, optional
• <NATION> - self-explanatory, optional
• <TYPE> - This could be one of the filter types (law, cte, etc., or "other" for custom happenings)
• <ISSUE_ID> - If this is a law happening, the ID of the issue that was answered
• <ISSUE_ANSWER> - If this is a law happening, which answer was given for that issue
• <INFLUENCE> - for Influence rank changes, from and to
• ...etc...

I store happenings in a database, currently with a TEXT column plus pre-parsed region1, region2, nation1, nation2 columns for search. I intend to expand that to include at least the type, and possibly modify it so that when it's unambiguous, the text column is just NULLed to save space in the database. Besides, it just makes it easier to search in the DB in general - I can build indices, do funky joins, what have you.

A concern is that such a form for the happening would be considerably longer. Anyone saving the raw XML would not be pleased by the replacement of <TEXT>...</TEXT> with all of this info, presumably in addition to the TEXT.

This would also not be fun to implement. It's not happening in the foreseeable future.

[Caelapes]

Would it be possible that NS API incorporates a new public shard to query a nation's id number?
I'm referring to the number that is currently used to resolve WA census ties in the ranking system.

It would certainly be possible. As [v] and I don't see a problem with doing it, it'll probably be done soon.

is there any significant use for the ID number beyond breaking ties in the census?

[Eluvatar]

It would certainly be possible. As [v] and I don't see a problem with doing it, it'll probably be done soon.

is there any significant use for the ID number beyond breaking ties in the census?

Where's the fun in answering that?

[Caelapes]

is there any significant use for the ID number beyond breaking ties in the census?

Where's the fun in answering that?

It was worth a shot.

[[violet]]

The API doc has been updated with instructions on how to answer issues via API. This is the first "Private Command" where you can actually make your nation do stuff via the API, not just gather information about it.

Feedback welcome!

[Roavin]

A concern is that such a form for the happening would be considerably longer. Anyone saving the raw XML would not be pleased by the replacement of <TEXT>...</TEXT> with all of this info, presumably in addition to the TEXT.

This would also not be fun to implement. It's not happening in the foreseeable future.

Ah, fair enough. As a workaround (though this may not be strictly API-related), is there a chance to have some sort of table of the happenings texts available? Principally, I was looking for the ones for the answered issues; the Got Issues forum only seems to have the issues themselves, not the generated happenings.

The API doc has been updated with instructions on how to answer issues via API. This is the first "Private Command" where you can actually make your nation do stuff via the API, not just gather information about it.

Feedback welcome!

Nice! An example for the different generated responses may be nice, since the "live" example obviously won't work with just a click.

Does one-click-one-action apply here, or would it be permissible to create an "automated issue answering" tool? (just for the sake of argument here, not saying I see a point in that )

[Greater Tern]

The API doc has been updated with instructions on how to answer issues via API. This is the first "Private Command" where you can actually make your nation do stuff via the API, not just gather information about it.

Feedback welcome!

Thanks [v], this looks really great! The only issue I'd like to point out is that this should probably be a POST command, rather than just GET.

EDIT: Out of curiosity, what does the RECLASSIFICATIONS schema look like? I don't want to force a reclassification on my nations at the moment.

[[violet]]

Nice! An example for the different generated responses may be nice, since the "live" example obviously won't work with just a click.

I know more documentation on all Private Shards and Private Commands would be helpful, but it's a fairly low priority and I know script authors are smart people who can figure it out, so I'm not sure if it will get done.

Does one-click-one-action apply here, or would it be permissible to create an "automated issue answering" tool?

There is no "one-click-one-action" rule on the API, and issue answering isn't a restricted action even on the regular HTML site. It's always been permissible to answer issues via script.

The only issue I'd like to point out is that this should probably be a POST command, rather than just GET.

Ah yes, updated doc, thanks.

Out of curiosity, what does the RECLASSIFICATIONS schema look like?

Like this:

Code: Select all

<RECLASSIFICATIONS>
  <RECLASSIFY type="govt">
    <FROM>Inoffensive Centrist Democracy</FROM>
    <TO>Iron Fist Consumerists</TO>
  </RECLASSIFY>
  <RECLASSIFY type="0">
    <FROM>Some</FROM>
    <TO>Few</TO>
  </RECLASSIFY>
  <RECLASSIFY type="2">
    <FROM>Some</FROM>
    <TO>Few</TO>
  </RECLASSIFY>
</RECLASSIFICATIONS>

The "type" is 0 for Civil Rights, 1 for Economy, and 2 for Political Freedom.

[Greater Tern]

Thanks [violet]. I have a few more requests, sorry:

- For the <UNLOCKS> tag, could we also get the name of that particular banner?
- Could we get a tag for the newspaper headlines/images on the issue results?

Both of those are currently parsed by Stately out of HTML, so having these in the API results would be great.

[[violet]]

Headlines are now included in the output of the "issue" Private Command.

You can look up banner details via the new World API Shard "banner".

[Flanderlion]

The API doc has been updated with instructions on how to answer issues via API. This is the first "Private Command" where you can actually make your nation do stuff via the API, not just gather information about it.

Feedback welcome!

You're awesome. Will play around with it properly in a week or so, but thanks.