NationStates API (nationdata/regiondata)

[Trotterdam]

I agree that caching is reasonable (census score descriptions aren't something that changes often), although it would be nice to retrieve all of the census scores in one request, rather than needing to spend around a minute retrieving them one by one. (86 census scores at the maximum rate of 50 requests per 30 seconds would take 51.6 seconds to complete. Since I prefer not to push to the very limit of what's allowed, it'll take longer in practice. It's also more tedious to write code for scheduling and processing multiple requests rather than just one.)

Regarding the site staff, something similar actually applies there. Given that the vast majority of nations are not staff, I think that a world shard which reports a list of all staff members would be more useful than needing to check each nation individually to see if it is one, though there's certainly room for both features.

[August]

1. I am building a Discord bot, and one of its functions displays information about nations. I would like it to indicate if a nation is site staff. Another of the bot's functions automatically grants roles and permissions based on things like residency, and some servers have special roles and permissions for staff.
2. I could do that, yes. Sometimes they change or new ones are added, but I admit that both of these events are rare. I think the last addition was Disposable Income six months ago, and while that is not a frequent occurrence, I will not be around forever to maintain this system, so this is partially a future-proofing request. Mostly, having all the data for a particular census at once would streamline things on my end. After all, there are 87 census categories, each with their own descriptions/titles/names/units, which means 348 data points I would have to request and store locally. I have no idea what the API's backend looks like or if is easy to modify existing shards, but the data is already available through a different shard, so I figured I would ask.

Semi-edit: Trotterdam's post was made while I was writing this one. In response to that, I would be fine with a world shard containing a list of staff. It would require an extra step in my application, which only checks individual nations at the moment, but it would certainly be better than nothing. I could have the bot make that request on startup and cache the list for the duration of the session.

[Trotterdam]

On the subject of including name info with census scores, I'll note that there's already a precedent of being inclusive with information elsewhere. The q=policies shard will always include a full description of each policy, whether you're actually interested in that information or not (policy descriptions change almost as rarely as census descriptions do).

[The Northern Light]

Personally I'd like to see the SPDR census included [edit: in the daily nation dump]. The reason for this is that I often have to process region-wide SPDR rankings in large regions (TNP, other GCRs, Europeia). Doing so currently requires a very large number of API calls to fetch all of the regional census=65 rankings and values. Having this information available in the nation dumps would make this process much easier and less bandwidth-intensive.

Would it be possible to revisit this suggestion?

It was brought up here, and several players mentioned they would benefit from the addition. But the discussion soon digressed to including LASTUPDATE in the dumps.

It'd save me a few dozens of thousands of API calls per day, and I imagine it's the same for many other players.

I'd like to bump this request. Adding the SPDR metric in the national dumps would be enormously useful for a large swath of (at least) gameplayers, who frequently need to comb through influence statistics for various purposes (regional security, R/D, WA and endotarting promotion, etc.).

Given that compiling influence statistics often requires fetching the SPDR of entire region populations one nation at a time, it would save both the players and the server a considerable amount of API bandwidth.

The nation dumps already include a few other censuses in various forms, namely CENSUSIDs 0, 1, 2, 3, and 49 (there is also a "PUBLICSECTOR" field for which I could not determine whether it corresponds to a CENSUSID). I understand that at least the first four are "special" censuses (respectively: the three censuses that determine a nation's category, and population). I'd argue that SPDR is also special, given its role in determining the feasibility/outcome of many gameplay actions. Therefore, it should be included in the nation dumps, just as CENSUSIDs 0-3 are.

[Jack Dredd]

Not sure if this is the right thread, but would it be within the NS TOS to create multiple regions and use their API's to recruit, and then send those nations to one central region?

[Trotterdam]

Not sure if this is the right thread, but would it be within the NS TOS to create multiple regions and use their API's to recruit, and then send those nations to one central region?

I'm pretty sure the telegram ratelimit is per player, not per region, so I don't see how that would help.

[Frisbeeteria]

Not sure if this is the right thread, but would it be within the NS TOS to create multiple regions and use their API's to recruit, and then send those nations to one central region?

I'm pretty sure the telegram ratelimit is per player, not per region, so I don't see how that would help.

Nope, the ratelimit is per region specifically to prevent this sort of abuse.

As for using "gateway" regions, it's a gray area that can't really be coded. We certainly don't condone it, as anything that is specifically designed to subvert the intent of the rules is unethical at best. Don't do it.

[Jadis and Marthburg]

How can i know that my API is being sended?

[Frisbeeteria]

How can i know that my API is being sended?

At the bottom of your Sent recruitment telegram is a link to Recruitment & Delivery Reports. (Note that the link in this post is generic and won't work - click it in the body of the telegram.)

Your new Recruitment telegram hasn't gone to anyone yet. The one from two days ago has hit 14 nations, though I hope you stopped it because it's not a very good mass telegram. Since I have no idea what sort of script you're using (not that mods can debug scripts), that's all I can tell you.

[Jadis and Marthburg]

How can i know that my API is being sended?

At the bottom of your Sent recruitment telegram is a link to Recruitment & Delivery Reports. (Note that the link in this post is generic and won't work - click it in the body of the telegram.)

Your new Recruitment telegram hasn't gone to anyone yet. The one from two days ago has hit 14 nations, though I hope you stopped it because it's not a very good mass telegram. Since I have no idea what sort of script you're using (not that mods can debug scripts), that's all I can tell you.

I'm using nstg-web, are there any problems?

[Frisbeeteria]

I'm using nstg-web, are there any problems?

I have no idea. Mods don't do script problems. I've never sent an API telegram. Maybe other players can help you.

[Pax Cybertronian]

Hi, I'm trying to set my UserAgent so I can start up a recruitment campaign for my region, but I don't know how to create one. How do you set up a UserAgent? I've checked the API's website but I don't know how to edit a UserAgent and change it to, for example, my email address. Also, would I have to cancel my recruitment campaign if I wanted to change my UserAgent in the future? Any help would be appreciated.

Thank you.

[Trotterdam]

Hi, I'm trying to set my UserAgent so I can start up a recruitment campaign for my region, but I don't know how to create one. How do you set up a UserAgent?

It rather depends on which software you're using to access the URL. Without knowing more about what programming environment you're using, we can't really give a useful answer to this. And for that matter, the documentation for whatever tool you're using will probably be more helpful than this forum.

Also, would I have to cancel my recruitment campaign if I wanted to change my UserAgent in the future? Any help would be appreciated.

User agents are separate from API keys, so that probably won't be a problem. The important thing is that the user agent needs to be something that can be used to contact you, so if your contact information changes, it makes sense to change your user agent with it.

[Frisbeeteria]

I'm trying to set my UserAgent so I can start up a recruitment campaign for my region, but I don't know how to create one.

Most of the telegram apps include a line for adding a UserAgent. If you're writing your own script, some of them are probably open source, so you could look at the code to see how to add one. On the other hand, if you don't know scripting and you aren't using someone's app, you probably shouldn't be doing API recruiting.

Have you tried Googling "how do I set my useragent?" Probably a good starting point.

[Imperium Anglorum]

*** tgcanrecruit / tgcancampaign: Returns 1 if the nation will receive a telegram of this type, and 0 if not (because it has blocked recruitment TGs, for example, or is a Class nation). You may optionally supply from=(region_name) which allows the check to also examine whether nations will deny a telegram from that region in particular due to having received one too recently.

https://www.nationstates.net/pages/api.html#nationapi

Returns 1 for class nations when querying tgcancampaign. Is this in error? And if not, is there another way to determine whether a nation is a class nation?

[The Northern Light]

I've added the below. These are experimental and undocumented at the moment; please don't smash them with requests, and please provide feedback.

Additions to Region API:

"mostposts" for most frequent posters
"mostliked" for most liked
"mostlikes" for most likes given to other posts

These all take the following optional parameters:

"limit" to specify a maximum number of results
"from" to specify a starting time (in epoch format)
"to" to specify an ending time (in epoch format)

Example: Most liked posts in Testregionia since the start of this month PDT:

https://www.nationstates.net/cgi-bin/ap ... 0;limit=25

Hi,

I am using these API calls. However, the information I am getting for the "mostliked" category doesn't seem to be correct. For instance, this is a call for "mostliked", between August 22nd andSeptember 22nd 2018, in The North Pacific's RMB:

https://www.nationstates.net/cgi-bin/ap ... 537588800;

This reports that RMB posts by The Northern Light received only 3 likes. But if I look at my nation's notices, in the past 12 days only I already see at least 23 likes.

Is it possible that the descriptions of "mostliked" and "mostlikes" should be reversed? "Mostlikes" for my nation in the same period as above is 116, which seems more plausible.

EDIT - Update:

I did some testing of my own, and it looks like what I suggested above is indeed the case. The correct description for the results of these API calls should be:

"mostliked" for most likes given by this nation to other nations' posts
"mostlikes" for most likes received by this nation's posts

[Flanderlion]

I've added the below. These are experimental and undocumented at the moment; please don't smash them with requests, and please provide feedback.

Additions to Region API:

"mostposts" for most frequent posters
"mostliked" for most liked
"mostlikes" for most likes given to other posts

These all take the following optional parameters:

"limit" to specify a maximum number of results
"from" to specify a starting time (in epoch format)
"to" to specify an ending time (in epoch format)

Example: Most liked posts in Testregionia since the start of this month PDT:

https://www.nationstates.net/cgi-bin/ap ... 0;limit=25

Hi,

I am using these API calls. However, the information I am getting for the "mostliked" category doesn't seem to be correct. For instance, this is a call for "mostliked", between August 22nd andSeptember 22nd 2018, in The North Pacific's RMB:

https://www.nationstates.net/cgi-bin/ap ... 537588800;

This reports that RMB posts by The Northern Light received only 3 likes. But if I look at my nation's notices, in the past 12 days only I already see at least 23 likes.

Is it possible that the descriptions of "mostliked" and "mostlikes" should be reversed? "Mostlikes" for my nation in the same period as above is 116, which seems more plausible.

EDIT - Update:

I did some testing of my own, and it looks like what I suggested above is indeed the case. The correct description for the results of these API calls should be:

"mostliked" for most likes given by this nation to other nations' posts
"mostlikes" for most likes received by this nation's posts

I've linked the API urls on the RMB every few months, the likes and liked always confuse me and other RMBers. Ideally it'd actually just have a different word meaning the same thing to make it easier to differentiate. Or just mostlikesgiven/mostlikesreceived.

[Fecaw]

Is there a way of ranking nations by how many dispatches they have made?

[The Northern Light]

Hi,

Would it be possible to add an API call for getting the most liked RMB posts in a region during some period of time? I understand if it's not possible/practical to do that over arbitrarily old or long periods, but even if it could be done for some fixed period (e.g., during the last 30 days), that would be great.

If this is already possible and I have missed it, a pointer to how it can be done would also be appreciated.

Thanks in advance!

[August]

I'm pretty sure the telegram ratelimit is per player, not per region, so I don't see how that would help.

Nope, the ratelimit is per region specifically to prevent this sort of abuse.

As for using "gateway" regions, it's a gray area that can't really be coded. We certainly don't condone it, as anything that is specifically designed to subvert the intent of the rules is unethical at best. Don't do it.

I was under the impression that the ratelimit for API recruitment was per player and per region (ie, no more than one telegram every three minutes from a particular sender for all regions combined and for a particular region from all senders combined). If it is only the latter, I am happy to be wrong.

To clarify, is it legal for a single player to concurrently run three API telegram scripts for three regions (with no intent to ever merge said regions or use them as gateways)? This scenario would be functionally equivalent to three distinct players using their own distinct scripts to recruit for their own distinct regions, but from the same device.

[Eluvatar]

It is illegal for a player to evade rate limits through the use of multiple IP addresses.

I believe that at least the recruitment telegram ratelimits apply to both keys and IPs now, with a change made after Afforess did what you described. I didn't review any records or anything before saying this, though, so don't trust my memory too much.

[The Northern Light]

Possible bug?

I was pulling some upvote data for dispatches posted in TNP.

I've run into quite a few dispatches that, even though they exist and are shown as having 1 upvote, the API reports their score to be 0.

Example:
https://www.nationstates.net/page=dispatch/id=1101026
https://www.nationstates.net/cgi-bin/ap ... id=1101026

1100489
1101781
1093693
1107157
1107164
1097547
1105322
1099398
1099509
1100147
1097002
1097540
1105566
1107059
1107072
1101923
1100174
1100205
1100372
1100382
1107342
1107356
1101026
1100586
1095667
1099222
1099448
1099454
1107047

I've also run into a few dispatches that, while having 1 upvote on the gameside, have a score of -1 on the API.

Example:
https://www.nationstates.net/page=dispatch/id=1099857
https://www.nationstates.net/cgi-bin/ap ... id=1099857

1096566
1096200
1104958

My guess is that these are dispatches which have received more downvotes than upvotes. Gameside doesn't allow the upvote score to go below 1, but maybe that's still recorded in the API. I thought I should report it nonetheless, in case it's indeed a bug.

[Eluvatar]

During this Z-day, there will be a new field in the zombies shard: some nations will have a ZACTIONINTENDED field, which will reflect the ZACTION they had before a horde forcibly changed their ZACTION to export. (If they had no ZACTION, ZACTIONINTENDED will be "none").

[Trotterdam]

During this Z-day, there will be a new field in the zombies shard: some nations will have a ZACTIONINTENDED field, which will reflect the ZACTION they had before a horde forcibly changed their ZACTION to export. (If they had no ZACTION, ZACTIONINTENDED will be "none").

Are you sure? For ZACTION, inactive nations have the empty string rather than "none".

I just tried testing it, and ZACTIONINTENDED appears to not appear on current nations. Does it only show up when a nation is actually infected? I think it'd be better easier to work with if it were always reported, being identical to ZACTION if a nation hasn't been forcibly changed. Right now I can't see it in action to see how I should parse it.

[Eluvatar]

During this Z-day, there will be a new field in the zombies shard: some nations will have a ZACTIONINTENDED field, which will reflect the ZACTION they had before a horde forcibly changed their ZACTION to export. (If they had no ZACTION, ZACTIONINTENDED will be "none").

Are you sure? For ZACTION, inactive nations have the empty string rather than "none".

I just tried testing it, and ZACTIONINTENDED appears to not appear on current nations. Does it only show up when a nation is actually infected? I think it'd be better easier to work with if it were always reported, being identical to ZACTION if a nation hasn't been forcibly changed. Right now I can't see it in action to see how I should parse it.

Done.

I've made it always appear, but it has a different set of states than ZACTION, at this time:

Blank: The nation's ZACTION is their intended action, ignore this.
"none": The nation's ZACTION has been overridden, and would otherwise be blank.
"exterminate", "research": The nation's ZACTION has been overriden, and would otherwise be this

(It should never be "export" for reasons I hope to be obvious).

You can look at https://www.nationstates.net/cgi-bin/ap ... t/q=zombie for an example of what a nation hit by a horde superweapon and converted to exporter would look like. (Also here)

I'm inclined to do what you ask in full, but that is more work to accomplish (because it'd involve either filtering the output or changing the mechanics) and I'm trying to get something else done. Let me know if this is sufficient.