NationStates API (nationdata/regiondata)

[Ballotonia]

Request

Would it be possible to expand the cards API and include options to retrieve a nation's asks and bids?

Bids in particular would be useful for collectors, who may want to check what cards from a large set they have placed bids on, or to check for bids on cards they already own, etc.

Thank you in advance!

Quick turn-around on this one!

Implemented. Example: https://www.nationstates.net/cgi-bin/ap ... me=carinov
See the API page (Section Cards.4) for the details: https://www.nationstates.net/pages/api.html#cards

Ballotonia

[Ballotonia]

Would it be possible to alter the "CATEGORY" field on the cards API to "CARDCATEGORY", and "CARDID" to "ID"?
In it's present form, the output from the API is incongruent with the data dumps.

EDIT: I'm referring specifically to the decklist provided by "cards+deck;nationname="

While I do enjoy consistency, this would break the scripts of all current users. I think this is manageable on user-side.

Hi all, I am a compete beginner to the API so my apologies in advance if what I am asking is overly simple.

The specific stat I’d like to know about is total number of issues answered (I looked up in the documentation but couldn’t find a relevant shard); I would presume this is kept track of somewhere since there exist banners for reaching specific milestones. Thanks for any help!

Added to the Nation API: ISSUES_ANSWERED. See for example: https://www.nationstates.net/cgi-bin/ap ... testlandia

Note that this only keeps track of all issues answered since back when this counter was added. Especially older nations will find a lower value than what really happened. It's been quite some years already though, so by far most nations will have the right value.

Ballotonia

[Ballotonia]

Feature request:

Would it be possible to add an option to the cards API to list the IDs and names of all current collections in a nation's deck?

For example, it could be:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?q=cards+collections;nationname=testlandia

Ideally it could be combined with deck and info:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?q=cards+info+deck+collections;nationname=testlandia

One downside of my example proposal that you may want to take into account is that the syntax is very similar to the "+collection" option for listing the contents of a specific collection. Feel free to use some other syntax.

Thanks in advance!

Implemented as suggested. I know the singular/plural is similar, but this is not the first time we've had that. Since I don't see these two being used within the same call, it's OK.

Example: https://www.nationstates.net/cgi-bin/ap ... ationid=38

Ballotonia

[The Northern Light]

Thanks for all these new features!

[HN67]

Would it be possible to add shards to the cards API that shows the sales/buys of a nation, (i.e. https://www.nationstates.net/page=deck/ ... ades=sales and https://www.nationstates.net/page=deck/show_trades=buys)? similar to the existing askbids shard (e.g. https://www.nationstates.net/cgi-bin/ap ... testlandia), although ideally separate shards. It could use the XML syntax similar to the other trades shards (e.g. https://www.nationstates.net/cgi-bin/ap ... 1;season=1).

This would be useful for summarizing the activity of puppets.

Thanks,
HN67

[Imperium Anglorum]

The NS API doesn't have NSUN resolutions, I think. I tried with the following links:

https://www.nationstates.net/cgi-bin/ap ... resolution
https://www.nationstates.net/cgi-bin/ap ... resolution

Could it be added (or the specific location be added to the documentation, if already present)?

[Valentine Z]

API / Shard Request:

Hello there! Will it be possible to have "Issues Answered" as a separate shard that I can add together along with the other shards?

For my data-collecting purposes, I use this single line / API call to get all the data that I need: https://www.nationstates.net/cgi-bin/api.cgi?nation=valentine_z&q=policies+category+flag+region+census+sectors+deaths+govt+hdi;scale=all&cards+info. I unfortunately can't get the Issues Answered data this way, because it is only available in an API call without shards (https://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia), and I don't really want to do 2 separate API calls for one nation.

Thank you in advance! ^^

[SherpDaWerp]

A couple additions to the basic nation query, please. Namely, I would like the plural forms of currency and animal to be made available.

I know the game has a system for custom pluralisations of different currencies, this thread specifies as much. I'm pretty sure a system for custom pluralisations of animals exists too: this thread certainly appears that way.

Could these fields be added to the basic nation query (https://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia), similarly to Demonym2 and Demonym2Plural?

If this is unfeasible, then perhaps other queries could be added:
https://www.nationstates.net/cgi-bin/api.cgi?q=animalplurals
https://www.nationstates.net/cgi-bin/api.cgi?q=currencyplurals
that would return a list of singular fields and their plural variants, as tracked by the game. Format could be something like

Code: Select all

<DATA>
<CURRENCY>
<SINGULAR>denarius</SINGULAR>
<PLURAL>denarii</PLURAL>
</CURRENCY>
<CURRENCY>
<SINGULAR>yen</SINGULAR>
<PLURAL>yen</PLURAL>
</CURRENCY>
</DATA>

If it helps; my end goal here is to get an automatically-updating "spoiler list" of issues. Correctly categorising macros is going to be difficult (especially randomnames); I'm currently creating a list of all known fields from a nation so it's possible to do a "find-and-replace" search. That includes categorising plurals - if someone's currency is the "denarius" then my script won't pick up "denarii" as a @@CURRENCYPLURAL@@, it'll assume it's just a regular word. So, I want information about what the plurals are for a nation, so I can accurately categorise @@CURRENCYPLURAL@@ and @@ANIMALPLURAL@@ macros. Of course, currencies like the yen will be more annoying, but having plural information for such a currency will at least let me know that it could be a plural instead of assuming it's definitely a singular.

---

Also, bumping my request:

Can the "total amount bid" (as viewable on the bottom of this page) be added to the Deck Owner Info shard? It's publicly viewable information anyway, and it would make it possible to calculate the amount of bank a nation has "free" to use.

[Trotterdam]

I have another case of the "improperly initialized census scores" bug.

The zombie census scores are reported as blank on New Docistan. This is not true of all nations founded after the zombie apocalypse was over, as I verified by picking a random newly-made nation.

Wow, it's been that long since I reported this? (Well, this was slightly more recent.)

So since this is still happening (on a bunch of nations), I finally went and updated my own code to be a little more robust to bugged API results. Doesn't seem like they're ever going to get fixed properly.

[Imperium Anglorum]

Can we get past poll results from the API? Never mind, I'm blind.

https://www.nationstates.net/cgi-bin/ap ... lid=161894

https://www.nationstates.net/page=poll/p=161894

[Evrigenis]

A few rules clarifications, please:
1. “Using a script or tool to send telegrams from the regular Telegrams page is a violation of our Script Rules“. But since using the standard HTML form is (as far as I know) the only way to draft API telegrams, it is allowed to submit drafts via HTML (with the slower rate limit) since drafting does not fall under any of the restricted actions categories. Is this understanding correct?
2. To me, there seems to be a grey area between sending requests to the API and sending requests to the user-facing site. For example, I’ve noticed that the build_nation endpoint seems to have its own rate limit. Is there documentation about that?
3. Technically not part of the API, but still in that grey area: Is changing a nation’s flag considered a restricted action? I’d think it would be similar custom fields settings changes, but I’d rather be safe.

[Trotterdam]

So since this is still happening (on a bunch of nations), I finally went and updated my own code to be a little more robust to bugged API results. Doesn't seem like they're ever going to get fixed properly.

...Which, of course, is how I discover that we're still also suffering blank census scores on issue-relevant scores. It does seem to have been fixed rather quickly (if you look now, the non-issue-relevant scores on The Most Holy E are blank, but the issue-relevant scores are not), but when my program looked two hours ago, the issue-relevant scores were too (or at least score 0, Civil Rights, was, at which point my program threw up and error and choked).

1. “Using a script or tool to send telegrams from the regular Telegrams page is a violation of our Script Rules“. But since using the standard HTML form is (as far as I know) the only way to draft API telegrams, it is allowed to submit drafts via HTML (with the slower rate limit) since drafting does not fall under any of the restricted actions categories. Is this understanding correct?

Why would you want to do that? Writing drafts is generally not something you want to do en masse, so it doesn't benefit from automation.

2. To me, there seems to be a grey area between sending requests to the API and sending requests to the user-facing site. For example, I’ve noticed that the build_nation endpoint seems to have its own rate limit. Is there documentation about that?

I'm not 100% sure what you're trying to ask here, but I've been kinda curious about a similar-sounding question, so I guess I'll ask.

The API ratelimit is (effectively) 100 requests per minute, while the non-API ratelimit is 10 requests per minute. How do these interact if you're using both? Could you do both at maximum throttle to send a total of 110 requests per minute, or should you apply an "exchange rate" where you get 100 points per minute, API requests cost 1 point, and non-API requests cost 10 points? Or just make no more than 100 total requests per minute, of which at most 10 may be non-API (leaving 90 for the API)?

It's not something I actually want to do (the API is a lot more convenient than site-scraping, and even when it doesn't cover something I might want to automate it's easier to ask for a new API feature than to scrape HTML that's meant to be human-readable), but I've been wondering.

3. Technically not part of the API, but still in that grey area: Is changing a nation’s flag considered a restricted action? I’d think it would be similar custom fields settings changes, but I’d rather be safe.

Hmm. My first guess was that it would be allowed by a literal reading of the current rules since it isn't changing anything except your own nation. Then I realized that since your flag is also displayed on the regional and world nation lists (and in, say, the happenings of another nation that you interacted with, such as by endorsing), it technically does affect something other than your own nation. Then again, the same also applies to pretitles, and I really thought you were allowed to change those. And then I took a closer look at the current rules and saw that the exact wording is "anything that generates a Happenings event line in a region, the World Assembly, or a nation other than your own", which means that it would be okay, since changing your flag definitely doesn't do that.

Regardless of the current words-as-written, though, the unusually large data transfer involved in uploading a new flag image means that it isn't something you should spam. So even if the current rules don't technically forbid it, I think that's an oversight, and it probably should be.

[United Calanworie]

Can we get a shard for factions that returns the number of nations in that faction? It'd be exceptionally useful for a variety of things, including history tracking of factions, and analyzing the growth of factions over the event.

[[violet]]

Can we get a shard for factions that returns the number of nations in that faction? It'd be exceptionally useful for a variety of things, including history tracking of factions, and analyzing the growth of factions over the event.

Added as <NATIONS> in the "factions" shard. Example.

[United Calanworie]

Can we get a shard for factions that returns the number of nations in that faction? It'd be exceptionally useful for a variety of things, including history tracking of factions, and analyzing the growth of factions over the event.

Added as <NATIONS> in the "factions" shard. Example.

Thanks [v]!

[Valentine Z]

API / Shard Request:

Hello there! Will it be possible to have "Issues Answered" as a separate shard that I can add together along with the other shards?

For my data-collecting purposes, I use this single line / API call to get all the data that I need: https://www.nationstates.net/cgi-bin/api.cgi?nation=valentine_z&q=policies+category+flag+region+census+sectors+deaths+govt+hdi;scale=all&cards+info. I unfortunately can't get the Issues Answered data this way, because it is only available in an API call without shards (https://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia), and I don't really want to do 2 separate API calls for one nation.

(Image)

Thank you in advance! ^^

I hope you don't mind me bumping it, and pardon the impatience I might have hinted, but I would still like this for my next data trawl. ^^

In short, I would like Issues_Answered as a public shard that I can add into here the URL/API call.

[The Python]

How do you automatically found nations using the API?

[Merni]

How do you automatically found nations using the API?

Not possible.

[[violet]]

API / Shard Request:

Hello there! Will it be possible to have "Issues Answered" as a separate shard that I can add together along with the other shards?

For my data-collecting purposes, I use this single line / API call to get all the data that I need: https://www.nationstates.net/cgi-bin/api.cgi?nation=valentine_z&q=policies+category+flag+region+census+sectors+deaths+govt+hdi;scale=all&cards+info. I unfortunately can't get the Issues Answered data this way, because it is only available in an API call without shards (https://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia), and I don't really want to do 2 separate API calls for one nation.

Added! There is now an "answered" shard.

[Valentine Z]

API / Shard Request:

Hello there! Will it be possible to have "Issues Answered" as a separate shard that I can add together along with the other shards?

For my data-collecting purposes, I use this single line / API call to get all the data that I need: https://www.nationstates.net/cgi-bin/api.cgi?nation=valentine_z&q=policies+category+flag+region+census+sectors+deaths+govt+hdi;scale=all&cards+info. I unfortunately can't get the Issues Answered data this way, because it is only available in an API call without shards (https://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia), and I don't really want to do 2 separate API calls for one nation.

Added! There is now an "answered" shard.

Woo hoo, thanks, Violet! ^^

[Leppikania]

Any chance we might be able to get N-Day data on individual nations?

(Also, should the private API really be accessible using CORS? That seems ripe for a phishing attack.)

[Racoda]

I would love to request a collection management function in the API.

Even if it has to be a slower rate anything that allows it to be automatic would be amazing for people who do large collections for example
Every TNP card or every TWP or every common card

Request:

Would it be possible to revisit this idea? A "batch submit to/remove from collection" (where one could just submit ID,SEASON pairs to be added to a collection) would be ideal for those with a large amount of cards to add, but even adding/removing each card individually would be a massive help. The OSRS currently forbid scripts from doing that automatically through the normal HTML site – adding cards manually is the only option.

My particular use case would be adding CTE cards to a semi-dynamic collection — manually updating this kind of collection if/when a nation refounds is impossible.
Seeing as (probably) S3 is coming up, this would save a lot of effort for those creating new regional S3 collections – it is very tiresome to add 500+ cards to a regional/CTE collection manually.

Edit: So, I've managed to add 64 precisely selected cards, at once, to a collection, through crafting a special request (by editing the form created by NS). This should be just part of the API at this point.

[The Unified Missourtama States]

Feature request:

Would it be possible to add an option to the cards API to list the timestamps of finds of certain cards.

For example, it could be:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?q=card+finds;cardid=1;season=1

I'd like to use this to track possible organic pull patterns as well as get a better sense of the effectiveness of TCALS in different market conditions.

Thanks in advance!

[The Python]

I have a feature request:

Can there please be an option to the "issue" private command so that it opens any cards received when the issue is answered?

Thanks!

[SherpDaWerp]

I have a feature request:

Can there please be an option to the "issue" private command so that it opens any cards received when the issue is answered?

Thanks!

Issues answered by the API never generate cards (see here and here); this is a design feature rather than a bug. It's designed to prevent large-scale automatic card farming by requiring farmers to use the HTML site instead of running an API script in the background 24/7.

edit: added links