Some other API questions/requests:
Is there any circumstance in which a ping request will receive a PING response other than 1? If there's an error, it seems there would not be a reply (HTTP response code other than 200, no XML response content). Are there ever PINGs of 0 or anything else !=1?
About the 50 requests in 30 seconds (or .6 second delay) rate limit:
- Will the server implement this automatically?
- I assume it applies to public, private, and TG shards, and applies per request not per shard
- Does it apply to request times or responses? That is, if I make requests uniformly .6 seconds after the last (including delay waiting for a response), should I be safe?
- The documentation implies it's a per-IP rate limit, but that spreading requests across IPs and agents would be detected. I assume that third-party public shard requests wouldn't impact users' ability to request public and private shards, especially since users can't necessarily control public shard API calls for their nations, even from tools they might use (e.g. Google Sheets)
- Some of these answers and details would do well in the API documentation
There should be samples or details of private shard contents in the API documentation. Just clicking the link works for the public shards, but obviously not the private. It's not hard to figure out what each does and how they respond, but that would be good to include in documentation for clarity. A brief explanation of what some things are (like DBID) could be useful for those not intimately familiar with all the functions; in fact, such brief description could be produced and offered (in spoiler tags, on a details page, however) for all available calls. I'd be happy to contribute to a documentation enhancement. It's already helpfully offered for census and banners shards.
Could it be possible to join nation requests as it currently is shard requests? (i.e. nation=testlandia+maxtopia&q=gdp+population) It's already fairly trivial to request data for multiple nations and merge them (e.g. into one XML list with multiple NATION items), but being able to consolidate them would reduce the number of necessary requests, which should somewhat reduce bandwidth load (though I don't know how it would impact the server overall).
Sorry to be such a bother and toss so many questions/thoughts out at once. Just passing along what I encounter while developing/playing with the API.