NationStates API (nationdata/regiondata)

[The United Island Tribes]

I would not recommend having automatic caching. After all, results can change over time, and sometimes "how much has this value changed in the last ten seconds?" is exactly the information you want to know. If you want to avoid redundant API calls on a value that isn't likely to change, you should explicitly store the value yourself somewhere.

This all really depends on the meaning of cache? Since my ties requests to a object, This object that has data can both be refreshed, accessed, are do both. Its more "what the last request was since this object has a previous request" than a True cache.

[[violet]]

Anyhow, the documentation speaks of a 'Retry-After' header that is supposedly returned when one violated the rate limit, but this header isn't actually returned.

Sorry about that. It is now back as "X-Retry-After." Docs updated.

[Agadar]

Discovery of the day: when using the 'from' and/or 'to' option for the census shard, the history is returned without having to explicitly declare the 'history' mode.

The more you know.

[Agadar]

When using something akin to the following query:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?v=8&q=DISPATCH+DISPATCHLIST&dispatchauthor=agadar&dispatchid=1

The dispatchauthor option is ignored: it just returns the 20 newest dispatches and the dispatch with id 1. Is this the default behavior for options, or is this a bug?

[Agadar]

Three posts in a row. Must be a new record.

Anyhow, for those interested: I've released the first version of my Java Wrapper for the NationStates API. The official on-site thread can be found here.

I invite the NationStates admins to take a look. I hope that if they approve of it, it might be added to the official API documentation.

[[violet]]

The dispatchauthor option is ignored: it just returns the 20 newest dispatches and the dispatch with id 1. Is this the default behavior for options, or is this a bug?

Bug! Now fixed, thanks.

I invite the NationStates admins to take a look. I hope that if they approve of it, it might be added to the official API documentation.

Very good! I'll give it a look.

[British Accia]

So, I've finally got my python API wrapper to work, but I'd like to know how to get a user_agent, since that seems to be required.

[The United Island Tribes]

So, I've finally got my python API wrapper to work, but I'd like to know how to get a user_agent, since that seems to be required.

Are you referring to my wrapper?

If so there are multiple ways.

For all requests, just set it for the api object

Code: Select all

import nationstates

api = nationstates.Api("The United Island Tribes UserAgent")



If you want it to be different for a particular request (will become the main one if you have not set one beforehand)

Code: Select all

import nationstates

api = nationstates.Api("The United Island Tribes UserAgent")

api.get_nation("The United Island Tribes", user_agent="NEW USER-AGENT")



If you using the module for something more than simple scripting, you may use load method. Load can also be supplied a user_agent per request.

Code: Select all

import nationstates

api = nationstates.Api("The United Island Tribes UserAgent")

#auto_load=false means this request will not request the API until told to. Since we are using load, we should not request the API twice for no reason.
nation = api.get_nation("The United Island Tribes", user_agent="NEW USER-AGENT", auto_load=False)

nation.load("New New Useragent")


My module users a default user_agent so testing is possible, but as you said it is required by the TOS.

[Agadar]

The dispatchauthor option is ignored: it just returns the 20 newest dispatches and the dispatch with id 1. Is this the default behavior for options, or is this a bug?

Bug! Now fixed, thanks.

I invite the NationStates admins to take a look. I hope that if they approve of it, it might be added to the official API documentation.

Very good! I'll give it a look.

Awesome, thanks for fixing the bug and for taking a look at my wrapper.

If I might pose a question to you (and to other programmers): is there an easier and more efficient way of checking a region's founding timestamp than retrieving its history and checking its first entry, which says something along the lines of "Region founded by @@nation@@"? This is quite an inefficient way of doing it, as the ENTIRE history must be retrieved in order to get just the timestamp in that one entry.

If there is no easier and more efficient way, I'd like to suggest for a shard for the region resource to be added that returns a timestamp of when the region was founded.

[British Accia]

So, I've finally got my python API wrapper to work, but I'd like to know how to get a user_agent, since that seems to be required.

Are you referring to my wrapper?

If so there are multiple ways.

For all requests, just set it for the api object

Code: Select all

import nationstates

api = nationstates.Api("The United Island Tribes UserAgent")



If you want it to be different for a particular request (will become the main one if you have not set one beforehand)

Code: Select all

import nationstates

api = nationstates.Api("The United Island Tribes UserAgent")

api.get_nation("The United Island Tribes", user_agent="NEW USER-AGENT")



If you using the module for something more than simple scripting, you may use load method. Load can also be supplied a user_agent per request.

Code: Select all

import nationstates

api = nationstates.Api("The United Island Tribes UserAgent")

#auto_load=false means this request will not request the API until told to. Since we are using load, we should not request the API twice for no reason.
nation = api.get_nation("The United Island Tribes", user_agent="NEW USER-AGENT", auto_load=False)

nation.load("New New Useragent")


My module users a default user_agent so testing is possible, but as you said it is required by the TOS.

Right, so it's not a fancy ID or something. Just an honesty system of 'Hey this is me'?

[Trotterdam]

Right, so it's not a fancy ID or something. Just an honesty system of 'Hey this is me'?

The intent is that you put contact information (such as an email address, or at least your nation name for telegrams), so that admins can contact you in case there is any problem with your script. If your script is causing trouble without providing valid contact information, they may have to permanently ban your IP address without right of appeal.

[[violet]]

If I might pose a question to you (and to other programmers): is there an easier and more efficient way of checking a region's founding timestamp than retrieving its history and checking its first entry, which says something along the lines of "Region founded by @@nation@@"? This is quite an inefficient way of doing it, as the ENTIRE history must be retrieved in order to get just the timestamp in that one entry.

Added "founded" for Regions API. I kept the same format as the Nation API, though, which is a text string like "2 years 192 days ago" rather than a timestamp. I will add new shards for both that return timestamps, if that's what you need (e.g. "foundedtime").

[Agadar]

If I might pose a question to you (and to other programmers): is there an easier and more efficient way of checking a region's founding timestamp than retrieving its history and checking its first entry, which says something along the lines of "Region founded by @@nation@@"? This is quite an inefficient way of doing it, as the ENTIRE history must be retrieved in order to get just the timestamp in that one entry.

Added "founded" for Regions API. I kept the same format as the Nation API, though, which is a text string like "2 years 192 days ago" rather than a timestamp. I will add new shards for both that return timestamps, if that's what you need (e.g. "foundedtime").

Thank you for pursuing my suggestion.

To answer your post: I do indeed need the timestamp (for regions) as I need to compare it to the current date in my EmbassyChecker program. Getting a timestamp and comparing it to the current date (like I am doing now, though I have to retrieve it from the first entry in a region's history list) is easier (and less 'dirty') than having to parse a string such as '2 years 192 days ago', I imagine.

[[violet]]

Added.

[Agadar]

Added.

That's great, thanks!

[Agadar]

This is probably a bug: when attempting to request the census title of the census with id 66 (world assembly endorsements) like so:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?v=8&q=CENSUSTITLE&scale=66

The title is not actually returned. All we get is this:

Code: Select all

<WORLD>
<CENSUSTITLE id="66"/>
</WORLD>

[[violet]]

Fixed, thanks for the report.

[[violet]]

The "happenings" part of the World API allows combining multiple "filter"-type parameters, e.g.,

Code: Select all

http://www.nationstates.net/cgi-bin/api.cgi?q=happenings;view=region.the_north_pacific;filter=founding+move+cte;limit=5

Would it be possible to allow also combining multiple "view"-type parameters?

Now kind-of implemented via new "regions" and "nations" views, which allow you to specify a list of regions or nations. E.g.:

http://www.nationstates.net/cgi-bin/api ... g+move+cte

[[violet]]

Also the "messages" shard in the Region API now supports the "fromid" parameter, for when you want to list RMB messages starting from a particular post ID. See the API doc for more.

[Imperium Anglorum]

Would it be possible to get a query which shows whether the nation accepts recruitment telegrams?

[HMS Unicorn]

Would it be possible to get a query which shows whether the nation accepts recruitment telegrams?

I may be misunderstanding your request, but it sounds a lot like the following call (the "from" argument is optional):

Code: Select all

http://www.nationstates.net/cgi-bin/api.cgi?nation=testlandia&q=tgcanrecruit;from=europeia

[HMS Unicorn]

The "happenings" part of the World API allows combining multiple "filter"-type parameters, e.g.,

Code: Select all

http://www.nationstates.net/cgi-bin/api.cgi?q=happenings;view=region.the_north_pacific;filter=founding+move+cte;limit=5

Would it be possible to allow also combining multiple "view"-type parameters?

Now kind-of implemented via new "regions" and "nations" views, which allow you to specify a list of regions or nations. E.g.:

http://www.nationstates.net/cgi-bin/api ... g+move+cte

Amazing, thanks a lot! I will test it over the weekend and report any issues.

[Agadar]

Will it ever be possible to retrieve more than 10 RMB messages at a time? For a script I'm currently developing, I need to retrieve ALL of a region's RMB messages. Retrieving my current region's relatively low number of about 12 thousand RMB pages took 6 hours of non-stop running the script due to the severe limitation of only being able to retrieve 10 RMB messages at a time.

[Caelapes]

Will it ever be possible to retrieve more than 10 RMB messages at a time? For a script I'm currently developing, I need to retrieve ALL of a region's RMB messages. Retrieving my current region's relatively low number of about 12 thousand RMB pages took 6 hours of non-stop running the script due to the severe limitation of only being able to retrieve 10 RMB messages at a time.

Is this for an RMB archival script? I have some working database insertion and front-end display code (in PHP) for that, if so, and I'd happily share.

And I can confirm that this would be very useful. Even just 25 per call, similar to the number displayed per page, would be very helpful and would reduce the time on your example by a third.

[Agadar]

Will it ever be possible to retrieve more than 10 RMB messages at a time? For a script I'm currently developing, I need to retrieve ALL of a region's RMB messages. Retrieving my current region's relatively low number of about 12 thousand RMB pages took 6 hours of non-stop running the script due to the severe limitation of only being able to retrieve 10 RMB messages at a time.

Is this for an RMB archival script? I have some working database insertion and front-end display code (in PHP) for that, if so, and I'd happily share.

And I can confirm that this would be very useful. Even just 25 per call, similar to the number displayed per page, would be very helpful and would reduce the time on your example by a third.

Though the script I'm developing could function as an RMB archive (it doesn't remove the retrieved RMB messages and thus they remain saved on the hard drive even after finishing working with them), its primary function is to calculate statistics such as can be found in this dispatch, which contains the (neatly-formatted) results of the last time I ran the script on my region's RMB.