NationStates API (nationdata/regiondata)

[[violet]]

Would it be possible to add functionality so that we could do a Login Verification check and pull nationdata from shards in a single API call? something like:

Code: Select all

api.cgi?a=verify&nation=testlandia&checksum=abcdefgh1234567890&q=region+name

which would spit out:

Code: Select all

<NATION id="testlandia">
   <VERIFY>0</VERIFY>
   <NAME>Testlandia</NAME>
   <REGION>Testregionia</REGION>
</NATION>

This now supported. Documentation here.

[[violet]]

I don't personally want daily dumps that include all 70-some census scores - just 65 and 66. But like I said, that's because I have a special application that could use it. I can have it run normal API calls for each nation in a given region to get that data from the live API no problem - it'd just be easier on my end (although probably not yours) to work from data dumps.

I chimed in because you said "I wasn't sure there was a good usage case" - I offered the way I'm using nationdata as an example, not necessarily as a suggestion.

Yes, understood. The idea with Daily Dumps is to include a limited set of the most commonly used data, with stuff that not everyone will use coming from the live API.

[Misley]

Would it be possible to add functionality so that we could do a Login Verification check and pull nationdata from shards in a single API call? something like:

Code: Select all

api.cgi?a=verify&nation=testlandia&checksum=abcdefgh1234567890&q=region+name

which would spit out:

Code: Select all

<NATION id="testlandia">
   <VERIFY>0</VERIFY>
   <NAME>Testlandia</NAME>
   <REGION>Testregionia</REGION>
</NATION>

This now supported. Documentation here.

Awesome, thank you! New member registration for The Internationale's forum now automatically sorts members either into our "Comrade Member" group (for people in TI) or a "foreign visitor" group for those outside TI, all at signup. Using the API to completely automate the oldschool "citizenship" application process makes things so much easier!

I don't personally want daily dumps that include all 70-some census scores - just 65 and 66. But like I said, that's because I have a special application that could use it. I can have it run normal API calls for each nation in a given region to get that data from the live API no problem - it'd just be easier on my end (although probably not yours) to work from data dumps.

I chimed in because you said "I wasn't sure there was a good usage case" - I offered the way I'm using nationdata as an example, not necessarily as a suggestion.

Yes, understood. The idea with Daily Dumps is to include a limited set of the most commonly used data, with stuff that not everyone will use coming from the live API.

Right, I understand. I'll keep doing it the way I have been, then!

[The United Island Tribes]

lets me give more examples (Here are some url generated by my program) (this is the world api)

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

Notice how the dispatchlist shard doesnt show up despite it being requested (with or without the ; after 4). While I could just switch them, it is still a problem because in the world api, more than 1 shard can have parameters. If there isnt a solution, I will have to send more than one request to get a shards with parameters attached

The way to write that is to first write all the shards, then all the additional options. Like:
https://www.nationstates.net/cgi-bin/ap ... -minuscule

The ";a=b" addition is not a shard. It's an extra option one adds after listing all the shards. Since options do not overlap, NS knows which option belongs to which shard.

Ballotonia

Thanks this shouldn't require much of changes.

[Imperium Anglorum]

How does the newnations shard work? Is it updated every [x] minutes or just a list of the [y] new nations?

[Ballotonia]

How does the newnations shard work? Is it updated every [x] minutes or just a list of the [y] new nations?

The shard is up-to-date at the moment it is sent to you in response to your API query. If you want to know a minute later what the newest nations are at that moment, you'll have to perform another query.

Keep in mind the rate at which new nations are found is limited (roughly 500 per day on average), so should not be a real need to query every second.

Ballotonia

[Almonaster Nuevo]

Would it be feasible to add a WAnations shard to the region API?

As far as I can see, at present if you want to do endorsement analysis you have to retrieve the full list of nations, then make a separate call for each nation to get the WA status + endos. Most of these are non-WA, so are unnecessary server load. Getting a list of WA nations to start with should strip out a significant number of API calls.

[Ballotonia]

Would it be feasible to add a WAnations shard to the region API?

As far as I can see, at present if you want to do endorsement analysis you have to retrieve the full list of nations, then make a separate call for each nation to get the WA status + endos. Most of these are non-WA, so are unnecessary server load. Getting a list of WA nations to start with should strip out a significant number of API calls.

Already exists: https://www.nationstates.net/cgi-bin/ap ... &q=members

Just cross-check that list with the list of region members, and you know all WA nations in your region.

Ballotonia

[Misley]

How does the newnations shard work? Is it updated every [x] minutes or just a list of the [y] new nations?

The shard is up-to-date at the moment it is sent to you in response to your API query. If you want to know a minute later what the newest nations are at that moment, you'll have to perform another query.

Keep in mind the rate at which new nations are found is limited (roughly 500 per day on average), so should not be a real need to query every second.

Ballotonia

Is there a reason to use the "newnations" shard from the World API instead of filtering out refounded nations from the "founding" shard from the Happenings side of the API? There are only 50 listed in newnations, while Happenings shards give 100 results, and also allows to page through results with the beforeid/afterid options.

[Almonaster Nuevo]

Would it be feasible to add a WAnations shard to the region API?

As far as I can see, at present if you want to do endorsement analysis you have to retrieve the full list of nations, then make a separate call for each nation to get the WA status + endos. Most of these are non-WA, so are unnecessary server load. Getting a list of WA nations to start with should strip out a significant number of API calls.

Already exists: https://www.nationstates.net/cgi-bin/ap ... &q=members

Just cross-check that list with the list of region members, and you know all WA nations in your region.

Ballotonia

I take slight exception to "already exists", since it is not what I was specifically asking for.

On the other hand, your alternative does allow me to do what I want with just a little extra work; and all of it at my end. So that's good.

Thanks.

[Rich and Corporations]

http://codetheory.in/javascript-copy-to ... eccommand/

http://www.nationstates.net/page=verify_login

An improvement to the login API would be a javascript command that would copy the lengthy verification code to the clipboard.
Honestly, the verification code only needs 56 bits of entropy, no one can successfully bruteforce anything over the internet with more than 32 bits of entropy.

[[violet]]

Is there a reason to use the "newnations" shard from the World API instead of filtering out refounded nations from the "founding" shard from the Happenings side of the API? There are only 50 listed in newnations, while Happenings shards give 100 results, and also allows to page through results with the beforeid/afterid options.

"newnations" is older, so the shard may well be better in all respects.

[The Vines]

I notice that for regions with no delegate or no founder, the API returns "0".

For example, https://www.nationstates.net/cgi-bin/ap ... &q=founder yields:

Code: Select all

<REGION id="the_rejected_realms">
  <FOUNDER>0</FOUNDER>
</REGION>


when you'd expect it to say

Code: Select all

<REGION id="the_rejected_realms">
  <FOUNDER />
</REGION>


instead.

Is it feasible to have the API return the latter? An empty tag would make more sense than "0" here.

[Misley]

I notice that for regions with no delegate or no founder, the API returns "0".

For example, https://www.nationstates.net/cgi-bin/ap ... &q=founder yields:

Code: Select all

<REGION id="the_rejected_realms">
  <FOUNDER>0</FOUNDER>
</REGION>


when you'd expect it to say

Code: Select all

<REGION id="the_rejected_realms">
  <FOUNDER />
</REGION>


instead.

Is it feasible to have the API return the latter? An empty tag would make more sense than "0" here.

"0" is not a valid nation (navigating to nation=0 always brings up your nation, if you're logged in), so it's not too difficult to simply add a check for it with special handling.

An empty tag is not valid XML.

[Phydios]

An empty tag is not valid XML.

Wrong. Empty elements are perfectly valid. In fact, XML even allows you to combine the start and end tags into one. So <tag></tag> becomes <tag />

[The United Island Tribes]

You may or may not already know, but I am working on a Api Wrapper for python http://github.com/Dolphman/pynationstates

I am getting pretty close to releasing my module to pypi for public use, however I want some more testing done. I also still have to write a crapload of tests for the module. Since I think this module is somewhat useful for people who want to use the API with a simple interface, I decided to have public testing of the module.

If you're interested, you can use pip to install the module via pip install git+https://github.com/Dolphman/pynationstates (note: GIT must be installed and the terminal your using must be able to access git [No windows cmd, use git bash for windows]).

Once your done with playing around with it, I recommend doing pip uninstall nationstates. As this installation may break future versions.

The Github page has some documentation, but its mostly just the advanced stuff I needed to write down. I'll put a version of this on github

Lets start with a simple script, Number of nations overtime (print to screen):

Code: Select all

import time
import nationstates

mycall = nationstates.Api("world", shard=["numnations"])

while True:
    mycall.load("My awesome user_agent")
    if mycall.has_data:
        print(mycall.numnations)
    time.sleep(10)


My Module supports both standard api call and calls with shards.

To make a api call with shards

Code: Select all

important nationstates

nationcall = nationstates.Api("nation", "The United Island Tribes", shards=["name", "fullname"])
regioncall = nationstates.Api("region", "the rejected realms", shards=["nations", "flag"])
worldcall = nationstates.Api("world", shards=["numnations"])
wacall = nationstates.Api("wa", value="1", shard=["numnations"])



To make an Standard Api call

Code: Select all

import nationstates

nationcall = nationstates.Api("nation", "The United Island Tribes",)
regioncall = nationstates.Api("region", "the rejected realms")


Once I release the module, I will create a new thread so I don't have to spam this one.

EDIT:

The Module has been released to pypi. It can now be installed via pip install nationstates

[Zemnaya Svoboda]

What happens if you call:

Code: Select all

import nationstates

wacall = nationstates.Api("wa", value=1, shard=["numnations"])


(BTW I assume that "important" in the original should be "import")

The way my example is different from yours is that I've given the value 1 as a integer instead of a string.

I wonder also how your module handles API versioning:

Can the user specify an API version?

Is there a default API version the script uses?

-- With my scripts, I tend to set the current version explicitly when I write them, and update them when I make changes (and test that it works with the new version).

[Phydios]

I wonder also how your module handles API versioning:

Can the user specify an API version?

Is there a default API version the script uses?

-- With my scripts, I tend to set the current version explicitly when I write them, and update them when I make changes (and test that it works with the new version).

The API documentation page explains API versions in this section. It looks like you're handling versioning in the best way.

[The United Island Tribes]

What happens if you call:

Code: Select all

import nationstates

wacall = nationstates.Api("wa", value=1, shard=["numnations"])


(BTW I assume that "important" in the original should be "import")

The way my example is different from yours is that I've given the value 1 as a integer instead of a string.

I wonder also how your module handles API versioning:

Can the user specify an API version?

Is there a default API version the script uses?

-- With my scripts, I tend to set the current version explicitly when I write them, and update them when I make changes (and test that it works with the new version).

Your code is correct, It will handle an integer (it just converts in to a str) dont use an interger, use a string (For the nation/region api value is always str, stay consistant). The reason I use a str is that I use that data when generating the request url

My module will work regardless of the version (as long as nationstates uses xml, as the module uses a dynamic parser). Since their seems to be a greater need for specifying a api version I will add it and update the package soon. The default will be the current version.

I will edit this once I add version selection.

[Zemnaya Svoboda]

My module will work regardless of the version (as long as nationstates uses xml, as the module uses a dynamic parser).

How can you be sure of that?

[The United Island Tribes]

My module will work regardless of the version (as long as nationstates uses xml, as the module uses a dynamic parser).

How can you be sure of that?

Its an Dynamic Parser. A 3rd party library converts the XML to a mid-stage parsing OrderedDict, and then I do extended parsing on that. This will not break unless nationstates stops using xml or some obscure error occurs.

[HMS Unicorn]

Would it be possible to add an option for the Happenings shard in the World API that allows restricting results to before or after a timestamp?

This would be similar to the "sinceid" and "beforeid" optional parameters, but instead of specifying event IDs we would specify a timestamp.

Currently, if I want to fetch happenings of some sort that happened during, say, the last 6 hours, I need to make multiple API calls using the sinceid option, decrementing the event ID until I encounter an event with a timestamp more than 6 hours old. With my suggested addition, I would be able to do the same with one API call.

Thanks in advance.

[The United Island Tribes]

I have created an official thread for my nationstates api for python project, could I be added to list of examples on the Nationstates Documentation?

Official Thread - http://forum.nationstates.net/viewtopic ... 5&t=356362

[[violet]]

I have created an official thread for my nationstates api for python project, could I be added to list of examples on the Nationstates Documentation?

Excellent, done!

[The United Island Tribes]

This may seem a stupid request, but I need a way to ban myself from the api to test and fix how my python module handles api temp bans. While being able to trigger this (while choosing the ban time) would be best (As I could check the headers for Retry/After). At the very least could I have the HTML/XML that is returned when you are banned. I don't think triggering a ban whenever by spamming the api is the best way to go about this, So I will holdout.