NationStates API (nationdata/regiondata)

[Shadow Afforess]

Fixed bug causing percentage signs to display when requesting a nation API with no shards and explicitly specifying a version number of 5 or higher, and a separate bug causing incorrect formatting in API version 5 when looking up nations with a public sector of 100% or 0%.

Thanks. Hopefully I caught all the places in my tooling where these changes occur. Will have to skim the error logs tomorrow I guess...

[The Shadow Assassin]

Question, is it legal for a script to send telegrams no more than once every 30 seconds, but more than once every 180 seconds, if the main purpose of the telegram is to welcome new nations and show them how things work, but on the side also advertise a region?

So it will be something like:

"Welcome to NationStates.

This is how game issues work: . . . . . . .
There's something called the world assembly; this is it's function: . . . . . . .
There is something called Raiding and Defending. Here's a summary and guide for it: . . . . . . .
Some regions also do role-playing. Here's a summary and guide for that: . . . . . . .
This how the NationStates forum works and here are it's main rules: . . . . . . .

By the way, you are welcome to join us in region [XYZ] and we will be happy help you explore more aspects of NationStates"

Does a telegram styled as such, so that guiding new players into NS is the first and main thing, counts as a general telegram and can be sent once every second 30? Or is any slight advertisement to a region makes the telegram recruitment and it must be sent no more than once per 180 seconds?

Thanks.

[Sedgistan]

That's a recruiting TG. It needs to follow the regular limits - i.e. 1 per 180 seconds.

[Jeckland]

That's a recruiting TG. It needs to follow the regular limits - i.e. 1 per 180 seconds.

You're only allowed 1 TG per 180 seconds?

is that something new? Cos if it isn't, I admit I'm a serial offender here.

[Ballotonia]

That's a recruiting TG. It needs to follow the regular limits - i.e. 1 per 180 seconds.

You're only allowed 1 TG per 180 seconds?

is that something new? Cos if it isn't, I admit I'm a serial offender here.

That's the scripted speed limit. When someone lets a computer program send telegrams. The speed limit for manually sending telegrams is whatever speed the site lets you send them.

Ballotonia

[Reeveton]

I recently received an API code, and want to use it for recruitment purposes, but am unsure of how to proceed. Help anyone?

[Jeckland]

You're only allowed 1 TG per 180 seconds?

is that something new? Cos if it isn't, I admit I'm a serial offender here.

That's the scripted speed limit. When someone lets a computer program send telegrams. The speed limit for manually sending telegrams is whatever speed the site lets you send them.

Ballotonia

Oh good. I'm not a criminal. Yay.

[Tlik]

Would it be possible to have a boneyard API? I don't think there's currently a way to get at the information on the boneyard page without scraping the page itself, which is obviously subject to the slower rate limits.

[Ballotonia]

Would it be possible to have a boneyard API? I don't think there's currently a way to get at the information on the boneyard page without scraping the page itself, which is obviously subject to the slower rate limits.

What information are you looking for?

Dead nations aren't actually in the game, and since their files are pulled from the archive I actually don't want to make that access high-speed.

Ballotonia

[Shadow Afforess]

Would it be possible to have a boneyard API? I don't think there's currently a way to get at the information on the boneyard page without scraping the page itself, which is obviously subject to the slower rate limits.

What information are you looking for?

Dead nations aren't actually in the game, and since their files are pulled from the archive I actually don't want to make that access high-speed.

Ballotonia

A list of all nation names ever used, and CTE timestamp would be cool.

[Ballotonia]

A list of all nation names ever used, and CTE timestamp would be cool.

The Boneyard doesn't actually provide that...

Ballotonia

[Wuufu]

I would also be interested in getting a boneyard API. From my perspective, I would like a similar API to that of the nation API to be able to pull specific information on a nation from the boneyard, similar to the data that gets displayed when you view that nation in the boneyard (example).

So this would be things like nation name(s), what date they were founded, what date they CTE'd, last known population, etc for all nations with that particular matching name. I'm not so interested in the full list of nations rather than being able to pull out the API the same information that the boneyard seems to already possess, without having to scrape the boneyard page to get it.

[Tlik]

Would it be possible to have a boneyard API? I don't think there's currently a way to get at the information on the boneyard page without scraping the page itself, which is obviously subject to the slower rate limits.

What information are you looking for?

Dead nations aren't actually in the game, and since their files are pulled from the archive I actually don't want to make that access high-speed.

Ballotonia

Basically the information that I can currently get from the page, for information's sake. I mean, if it's particularly more difficult or taxing on the servers to get it, it doesn't matter too much, but it would be nice to have that information in a more accessible format.

[The Black Angel Of Death]

Hi I would like how to change the recruitment telegram for my region using the API.

[Moon Eclipse]

Warning: simplexml_load_file(): http://www.nationstates.net/cgi-bin/api ... er=law:398: parser error : Input is not proper UTF-8, indicate encoding ! Bytes: 0xED 0x6E 0x20 0x61 in /home/u46966662/public_html/dumpydumpdump.php on line 61

My script was working so beautifully and nice just a few days ago!

Any advice on what happened in the last few days?

According to stackoverflow (and the error message ) this means the data is not properly formatted. Anyone else having this problem? The utf8_encode() workaround doesn't work either.

[Ballotonia]

The content of that API call is:

Code: Select all

<WORLD><HAPPENINGS></HAPPENINGS></WORLD>

... which looks OK to me.

Ballotonia

[Andacantra]

I'll just drop in here to say that a mistake I often make is forgetting to put handling in for when the result of the api call is no information - that could be what caused that error.

[Moon Eclipse]

Well, it works now. I think my code was just a little too hacky, fixed the problem on my end and it is all swell.

[Eluvatar]

New API Version: 5

Changes:

1. Outputs as UTF-8. This will also affect all Daily Dumps from now on.
2. Values under <PUBLICSECTOR>, <GOVT>, and <DEATHS> are displayed in the format "%.1f" (e.g. "21.1"), rather than "%d%%" (e.g. "21%"). Notice that's two differences: an extra decimal place, and no more percentage sign.

Examples: v4, v5.

API documentation

Note that going forward I will only be maintaining the three most recent API versions. If you depend on API version 1 or 2, it may stop working without notice.

Some concerns that have come up for me:

1. Not quite everything is UTF-8 (Indeed, asking for the currency separately still gets you windows-1252 characters, even though getting the default shards results in UTF-8 in the currency field).

Code: Select all

$ curl -i 'http://www.nationstates.net/cgi-bin/api.cgi?q=currency&nation=jolteonia'
HTTP/1.1 200 OK
Date: Mon, 23 Jun 2014 16:20:48 GMT
Server: Apache
Vary: Accept-Encoding
Transfer-Encoding: chunked
Content-Type: text/xml; charset=ISO-8859-1

<NATION id="jolteonia"><CURRENCY>Pok�dollar</CURRENCY></NATION>


2. Thankfully (?) the Content-Type header still says charset=ISO-8859-1 (meaning windows-1252).
3. ... It still says ISO-8859-1 for outputs which are actually UTF-8. (And not valid windows-1252). Edit: This can cause problems, see spoilered image:

Details (in utf-8 terminal):

Code: Select all

$ curl -i 'http://www.nationstates.net/cgi-bin/api.cgi?nation=jolteonia'
HTTP/1.1 200 OK
Date: Mon, 23 Jun 2014 16:21:34 GMT
Server: Apache
Vary: Accept-Encoding
Transfer-Encoding: chunked
Content-Type: text/xml; charset=ISO-8859-1

<NATION>
<NAME>Jolteonia</NAME>
<TYPE>Principality</TYPE>
<FULLNAME>The Principality of Jolteonia</FULLNAME>
<MOTTO>言えるかな？</MOTTO>
<CATEGORY>Liberal Democratic Socialists</CATEGORY>
<UNSTATUS>Non-member</UNSTATUS>
<FREEDOM>
 <CIVILRIGHTS>Excellent</CIVILRIGHTS>
 <ECONOMY>Frightening</ECONOMY>
 <POLITICALFREEDOM>World Benchmark</POLITICALFREEDOM>
</FREEDOM>
<REGION>Balder</REGION>
<POPULATION>7187</POPULATION>
<TAX>100</TAX>
<ANIMAL>Jolteon</ANIMAL>
<CURRENCY>Pokédollar</CURRENCY>
<FLAG>http://www.nationstates.net/images/flags/uploads/jolteonia__455639.png</FLAG>
<MAJORINDUSTRY>Book Publishing</MAJORINDUSTRY>
<GOVTPRIORITY>Education</GOVTPRIORITY>
<GOVT>
 <ENVIRONMENT>18.9</ENVIRONMENT>
 <SOCIALEQUALITY>18.8</SOCIALEQUALITY>
 <EDUCATION>32.7</EDUCATION>
 <LAWANDORDER>0.0</LAWANDORDER>
 <ADMINISTRATION>3.7</ADMINISTRATION>
 <WELFARE>8.4</WELFARE>
 <SPIRITUALITY>0.0</SPIRITUALITY>
 <DEFENCE>0.0</DEFENCE>
 <PUBLICTRANSPORT>3.5</PUBLICTRANSPORT>
 <HEALTHCARE>5.6</HEALTHCARE>
 <COMMERCE>8.4</COMMERCE>
</GOVT>
<FOUNDED>3 years 123 days ago</FOUNDED>
<FIRSTLOGIN>1298284145</FIRSTLOGIN>
<LASTLOGIN>1403434735</LASTLOGIN>
<LASTACTIVITY>1 day 5 hours ago</LASTACTIVITY>
<INFLUENCE>Minnow</INFLUENCE>
<FREEDOMSCORES>
 <CIVILRIGHTS>72</CIVILRIGHTS>
 <ECONOMY>100</ECONOMY>
 <POLITICALFREEDOM>82</POLITICALFREEDOM>
</FREEDOMSCORES>
<PUBLICSECTOR>62.4</PUBLICSECTOR>
<DEATHS>
 <CAUSE type="Lost in Wilderness">32.4</CAUSE>
 <CAUSE type="Animal Attack">3.1</CAUSE>
 <CAUSE type="Old Age">64.4</CAUSE>
</DEATHS>
<LEADER>Jolteon</LEADER>
<CAPITAL>Viridian Forest</CAPITAL>
<RELIGION>a major religion</RELIGION>
</NATION>


4. This is probably fine but the regions API (and xml dump) XML-encodes non-ascii characters instead of giving them out as UTF-8, which is slightly inconsistent (but generally fine).

I've been able to fiddle with my projects to live with this, but the quoted post is at least slightly misleading.

[[violet]]

Thanks for the above; I will check it out.

[Ghondra]

What the hell is a secret key? Could somebody tell me?

[Ballotonia]

What the hell is a secret key? Could somebody tell me?

For NS++ questions, ask in the NS++ thread: viewtopic.php?p=20795519#p20795519
(NB: I'm linking to the specific post where this is addressed)

Ballotonia

[Leutria]

What the hell is a secret key? Could somebody tell me?

You get a secret key when you send a telegram to tag:api (in order to create an API template).

What the hell is a secret key? Could somebody tell me?

For NS++ questions, ask in the NS++ thread: https://forum.nationstates.net/viewtopi ... #p20795519
(NB: I'm linking to the specific post where this is addressed)

Ballotonia

Is that really a NS++ specific question? Have I got something wrong?

[Shadow Afforess]

Possible improvement: Region API for RMB posts should include post id with each entry. Discussion ->

viewtopic.php?f=15&t=303608&p=20845258#p20845258

[Eluvatar]

Possible improvement: Region API for RMB posts should include post id with each entry. Discussion ->

viewtopic.php?f=15&t=303608&p=20845258#p20845258

I would like to suggest that happenings also get their event IDs in the nation, region, and WA APIs, if possible. It would help scripts ensure they don't confuse two simultaneous events for the same event, and would help sequence events that happen the same second.