NationStates API (nationdata/regiondata)

[Frisbeeteria]

sometimes mods DEAT nations during update

Don't know if it makes a difference, but it's extremely rare for us to delete a nation while its region is updating. It's going to be minutes or more on either side of the rest of the regional CTEs. It's not intentional - it's just that it's an extremely hard target to hit, assuming we tried. Which we don't.

[Caelapes]

sometimes mods DEAT nations during update

Don't know if it makes a difference, but it's extremely rare for us to delete a nation while its region is updating. It's going to be minutes or more on either side of the rest of the regional CTEs. It's not intentional - it's just that it's an extremely hard target to hit, assuming we tried. Which we don't.

Right - I'm not suggesting that moderators are trying to throw people off by deleting nations while their region updates.

There are a few problems at play here, though.

1) We don't know when update begins and ends. We can roughly estimate the start to be 12 midnight/noon US Eastern time, but we know it doesn't always start right on time. We can only tell the end of major update by checking against the daily dump to see if it's new, and what time it was generated. There is no sure way to determine with certainty the end of minor update. If this were an API shard, as has been requested previously, that would help.

2) Even if we knew when update was occurring, it can in some cases be impossible to tell if a CTE is "natural" or not. We don't know for sure when a region is updating, especially if it's a smaller region that doesn't have many update-signifying events connected to it. We can get an estimate and a window of uncertainty, sure, but that estimate can be off by several minutes. When a nation CTEs during update, sometimes it's obvious - a nation being DEATed in Balder at the beginning of update is a fairly safe "DEAT" call, but it's not always so clear - what if a nation is DEATed in Balder close to the end of update?

3) We could check against a nation's last activity, but that's only certain as of the last daily dump. Suppose a DOS player has a puppet that hasn't been logged into for 28 days that is missed during a puppetsweep, or which is granted to them by another player after being swept and so was not caught by moderation in the initial sweep. They log into it after major update but before the minor update at which it would naturally CTE, and do something obnoxious that catches the attention of moderators, who then DEAT the nation during minor update. Let's suppose that happens within our window of uncertainty for the nation's region of residence. If we check against the last activity, it looks natural. Only by scraping the Boneyard would we find out that it was, in fact, a DEAT.

There are times when it's useful to know whether or not a nation has been DEATed. Take a region whose founder ceases to exist. We can get a list of these regions through the API with the "Founderless" tag. These are tricky Gameplay targets, because the founder can always return and undo Gameplay actions taken in the region. However, if the founder has been DEATed, it's a far safer target - we only have to watch out for other Gameplay forces. It can be nice to know safer targets vs. riskier targets. Could we do this manually? Yeah. Could we scrape the Boneyard to do it automatically? Sure. Would it be easier for us to have it from the API? Definitely.

[Agadar]

Is it safe to assume from the lack of a reply that there is no publicly available changelog for the API, nor will there be?

EDIT: This question was already answered.

[Phydios]

Is it safe to assume from the lack of a reply that there is no publicly available changelog for the API, nor will there be?

You were given a response way back on the 8th.

Is there something of a changelog of the NS API available to us? As maintainer of one of the client libraries for the NS API, I find myself having to scour this thread for all the changes.

Not at this time. If someone were to make a record of API changes so far, however, I'm surmise that could be kept up going forward.

[Agadar]

Is it safe to assume from the lack of a reply that there is no publicly available changelog for the API, nor will there be?

You were given a response way back on the 8th.

Not at this time. If someone were to make a record of API changes so far, however, I'm surmise that could be kept up going forward.

I completely missed that. My apologies.

[Kethania]

The API is just dumping out what our internal system already provides, which is simpler than building a separate signaling system. I think that's fine.

Understandable, thanks for the clarification.


There are a couple of issues I have with the World dispatchlist shard. Specifically, the way the dispatchcategory parameter is treated, which is rather unintuitive.
The categories are case-sensitive, which, although out of coherence with the rest of the API (region tags are case-insensitive, for example), would not have been nearly as much of an issue had it not been for the way this shard behaves when the supplied category is not recognised. Currently, it simply ignores the dispatchcategory parameter if it can't make sense of it, and yields the same result as it would had the category been not supplied at all. I regard it as incorrect and unexpected behaviour; it should return an empty DISPATCHLIST element, the way it does when the dispatchauthor parameter isn't recognised.


A way to request the pinned dispatches in a region would also be rather welcome. I believe such an addition was proposed here once already, way back in 2014, but, for some reason, got ignored by the admins.


I'm really liking the new World banner shard. Would it be possible to get the same sort of arrangement for the World Census scale data?
Specifically, at the moment I lack the ability to request information on several scales at once. I would love to see the World shards censusdesc, censusname, censustitle, and censusscale joined into a single one, with the ability to list several scales in the scale parameter, basically exactly how the banner shard functions right now.


Thanks!

[Werreales]

Good morning. A short question: would webhooks be implemented in NationStates on day. It would allow developpers to run specific scripts when certain events are triggered, instead of constantly watch for changes. Would it be difficult to implement? Thank you for your attention.

[Eluvatar]

Hey! There we go. That's precisely why I want it.

Of course.

This will probably be added fairly soon.

This has been done.

Good morning. A short question: would webhooks be implemented in NationStates on day. It would allow developpers to run specific scripts when certain events are triggered, instead of constantly watch for changes. Would it be difficult to implement? Thank you for your attention.

For a variety of reasons this is unlikely to happen anytime soon.

[Werreales]

Of course.

This will probably be added fairly soon.

This has been done.

Good morning. A short question: would webhooks be implemented in NationStates on day. It would allow developpers to run specific scripts when certain events are triggered, instead of constantly watch for changes. Would it be difficult to implement? Thank you for your attention.

For a variety of reasons this is unlikely to happen anytime soon.

Thank you for this fast response. Have a nice day!

[Eluvatar]

A way to request the pinned dispatches in a region would also be rather welcome. I believe such an addition was proposed here once already, way back in 2014, but, for some reason, got ignored by the admins.

This should be available soon.

[HMS Unicorn]

Request

Is it possible to expand the API so that we can retrieve information about the rankings of regions in the various world censuses? I am talking about the rankings shown here (using WA endorsements as an example): https://www.nationstates.net/page=list_ ... ensusid=66

In particular, it would be great if we could query 1) an individual region's world rank and raw score; 2) world rankings of regions (similar to the CENSUSRANKS shard of the World API for nations).

As far as I can tell, this is not currently possible in the API, so the only way to get this information is through HTML scraping.

EDIT: Used to say scrapping.

[HMS Unicorn]

API typo

In the World API documentation, in footnote 3, there is a typo: "censuranks" -> "censusranks".

[Eluvatar]

API typo

In the World API documentation, in footnote 3, there is a typo: "censuranks" -> "censusranks".

Fixed.

[Eluvatar]

Request

Is it possible to expand the API so that we can retrieve information about the rankings of regions in the various world censuses? I am talking about the rankings shown here (using WA endorsements as an example): https://www.nationstates.net/page=list_ ... ensusid=66

In particular, it would be great if we could query 1) an individual region's world rank and raw score; 2) world rankings of regions (similar to the CENSUSRANKS shard of the World API for nations).

As far as I can tell, this is not currently possible in the API, so the only way to get this information is through HTML scrapping.

By all means we don't want you getting into a nasty fight with HTML. This will probably be added soon.

[Werreales]

Would it be possible to add a type to each <HAPPENING> tag returned by the API Region that would match the event? For example, an "arrival" type for the nations that integrate the region, a "departure" type for those leaving it, and so on. Until now, the only way to filter the result is to use regular expressions or do it by hand. Thank you.

[Eluvatar]

Would it be possible to add a type to each <HAPPENING> tag returned by the API Region that would match the event? For example, an "arrival" type for the nations that integrate the region, a "departure" type for those leaving it, and so on. Until now, the only way to filter the result is to use regular expressions or do it by hand. Thank you.

That level of granularity for all happenings would require rewriting all the code that generates happenings. (Not likely anytime soon).

What's more practical is tagging happenings tags with the filter(s) they match. (law, change, dispatch, ...)

A utility function from my transmission library you might find helpful in the meanwhile:

Code: Select all

def regexify(event_text):
    """ Turns strings of the form
            "@@(nation)@@ founded the region %%(region)%%."
        into
            r'@@([a-z0-9\_\-]+)@@ founded the region %%([a-z0-9\_])%%\.'
        does not currently cover any replacements besides nation and region
        identifiers. (I.E. resolution names, nation titles, nation classes...)
    """
    # TODO support more substitutions
    replaced = event_text
    filters = [("@@(nation)@@","@@([a-z0-9\_\-]+)@@"),
    ("@@nation@@","@@[a-z0-9\_\-]+@@"),
    ("%%(region)%%","%%([a-z0-9\_]+)%%"),
    ("%%region%%","%%[a-z0-9\_]+%%")]
    for (from_str, to_str) in filters:
        replaced = replaced.replace(from_str, to_str)
    replaced = re.sub(r'\.$', '\.', replaced)
return re.compile("^{0}$".format(replaced))

This allows one to specify patterns as e.g. "@@(nation)@@ relocated from %%(region)%% to %%the_region_i_care_about%%."

[Werreales]

Would it be possible to add a type to each <HAPPENING> tag returned by the API Region that would match the event? For example, an "arrival" type for the nations that integrate the region, a "departure" type for those leaving it, and so on. Until now, the only way to filter the result is to use regular expressions or do it by hand. Thank you.

That level of granularity for all happenings would require rewriting all the code that generates happenings. (Not likely anytime soon).

What's more practical is tagging happenings tags with the filter(s) they match. (law, change, dispatch, ...)

A utility function from my transmission library you might find helpful in the meanwhile:

Code: Select all

def regexify(event_text):
    """ Turns strings of the form
            "@@(nation)@@ founded the region %%(region)%%."
        into
            r'@@([a-z0-9\_\-]+)@@ founded the region %%([a-z0-9\_])%%\.'
        does not currently cover any replacements besides nation and region
        identifiers. (I.E. resolution names, nation titles, nation classes...)
    """
    # TODO support more substitutions
    replaced = event_text
    filters = [("@@(nation)@@","@@([a-z0-9\_\-]+)@@"),
    ("@@nation@@","@@[a-z0-9\_\-]+@@"),
    ("%%(region)%%","%%([a-z0-9\_]+)%%"),
    ("%%region%%","%%[a-z0-9\_]+%%")]
    for (from_str, to_str) in filters:
        replaced = replaced.replace(from_str, to_str)
    replaced = re.sub(r'\.$', '\.', replaced)
return re.compile("^{0}$".format(replaced))

This allows one to specify patterns as e.g. "@@(nation)@@ relocated from %%(region)%% to %%the_region_i_care_about%%."

Thank you for the code you provided. Even if I am not an expert in Python or Ruby I will try to understand the system to translate it into JS or PHP.

I find the filters quite useful for providing curated regional happenings' data. Is it possible to use it within the NS API, or is it just a backend feature?

[Trotterdam]

I find the filters quite useful for providing curated regional happenings' data. Is it possible to use it within the NS API, or is it just a backend feature?

Filters? You mean http://www.nationstates.net/cgi-bin/api.cgi?q=happenings&filter=law? Yeah, those work the same in the API as they do on the activity page. The FAQ gives a full list of the available ones and says you can also combine multiple filters into a single request using + signs.

[RantSpot]

Is there any way to request nation CTE data from the boneyard?

Idea 1: passed in the data or a header of a 404 response to an API call for a non-existent nation
Idea 2: requested as a special public API shard (boneyard, cte, bones) that can't be used in conjunction with others (boneyard, cte, bones)

It would be helpful to be able to differentiate between nations which never existed, CTEd and can be revived, and CTEd and can't be revived. For those that CTEd, even the time it CTEd could be useful. Something like:

Code: Select all

<NATION id="abandonedforever">
    <BONEYARD>
        <EXISTED>1</EXISTED>
        <RESTORABLE>0</RESTORABLE>
        <CTE>1263465300</CTE>
    </BONEYARD>
</NATION>

Obviously if it's a unique shard, it would have to have a response for nations which do exist.

Perhaps an even more detailed boneyard shard could provide a history of all past iterations of a nation just as the boneyard does. Population, founding, factbooks, etc. That's less essential but I expect some developers might use it if available.

[Eluvatar]

What use do you intend for this api?

Edit: I see:

Is there any way to differentiate between nations which CTEd and can be restored, nations which CTEd and can't be restored, and nations that don't exist?

Not at the moment, but feel free to request it in the API thread stickied in this forum. It wouldn't be too hard to send a different signal for CTE nations vs never-been-any-such nations.

This is very possible.

[RantSpot]

Yeah, I want to be able to tell if a login is failing because the nation never existed (so a user should check spelling etc), the nation CTEd and can be revived (so a user can revive it on the site), or the nation CTEd and can't be restored (either refound or the name was sullied).

But beyond that, a nation name history could be useful in all manners of NS tools. Querying past instances of one's own nation, seeing historical stats (if such tools archive that data), etc. I'm not currently writing something like that, but the data that NS already has publicly available via the boneyard could be very interesting to play with via the API.

[Thyerata]

Yeah, I want to be able to tell if a login is failing because the nation never existed (so a user should check spelling etc), the nation CTEd and can be revived (so a user can revive it on the site), or the nation CTEd and can't be restored (either refound or the name was sullied).

But beyond that, a nation name history could be useful [for example] [q]uerying past instances of one's own nation.

Wouldn't that example (checking for previous instances of one's nation) have to be Selective, in that it would only work with tiny nations that CTEd or went DEAT? So far as I understand things, The game code won't allow the reuse of nation names where that nation reached a certain population threshold before CTE, so you couldn't search for previous incarnations since the name couldn't be reused in the first place.

[RantSpot]

Wouldn't that example (checking for previous instances of one's nation) have to be Selective, in that it would only work with tiny nations that CTEd or went DEAT? So far as I understand things, The game code won't allow the reuse of nation names where that nation reached a certain population threshold before CTE, so you couldn't search for previous incarnations since the name couldn't be reused in the first place.

I'm not sure what you mean.

For previous incarnations, yes, all previous incarnations would be DEAT nations with <500 m pop, no historical WA issues authored, no mod deletion, not site supporters, etc (i.e. names that could be reused). But for reused names, the old data (founding and CTE dates, population, etc) exists in the Boneyard already. It's already public-facing.

For other uses, i.e. telling if a nation can be revived or founded for whatever purpose, such a shard/call could provide information on large CTEd nations which can be revived, small nations which can be revived or went DEAT, names that were mod deleted, names that were never used. This could provide options to alert users to names which could be refounded, founded anew, or can't be used at all.

[Catlander]

Dear friends

I'm trying to put some public APIs links from my NS nation into a google sheet cell (exactly with the shards gdp, income, population) to get its values, like this:

Code: Select all

=HYPERLINK(https://www.nationstates.net/cgi-bin/api.cgi?nation=catlander&q=gdp)


But Google Sheet shows an #ERROR after

Can you help me to solve the problem?. Thanks in advance.

[RantSpot]

This is a Google Sheets issue, not a NationStates issue, but... the URL needs to be in quotes.

Code: Select all

=HYPERLINK("https://www.nationstates.net/cgi-bin/api.cgi?nation=catlander&q=gdp")