Script rules?

[Kandarin]

The One Stop Rules Shop says:

Script Rules are covered in this post by SalusaSecondus. If you don't know what scripts are or how to write them, then these rules are almost certainly unnecessary for you.

Is there a link that's supposed to be there?

[[violet]]

Yes there is. It looks as though it didn't make it over in the great migration though...

Edit: Here it is: viewtopic.php?p=16394966#p16394966

[Ardchoille]

Er, ah, um ... yes. The link should take you to a post that says this:

Ok, these are now binding (though still up for discussion)

1. No script may send unsolicited telegrams. (1 reply message is permitted to a received telegram)
2. No script may post regional messages without permission of founder (or delegate if no founder exists). Edited
3. No script may access the forums (ie, any page with a URL starting with http://forums.jolt.co.uk) (http://forum.nationstates.net)
4. No script may kick or ban nations (unless controlled by the region's founder).
5. Scripts may not be used to endorse or unendorse other nations.
6. Scripts may not access the server excessively.
7. No script may create a nation. Edited
8. No script may create a region. Edited
9. Any Game Moderator, Admin, or Tech Modling may judge a script to be legal or illegal, separate from the above guidelines.

So now I will fix it to take you to this post instead.

[[violet]]

I'm looking at rewriting the script rules. Please provide feedback!

There are two aims here: firstly, to clarify what is legal (because the current terminology sometimes misleads people into thinking any tool is okay so long as it's not a script, and any script can never be okay), and secondly, to permit scripts to send TGs within a clearly defined limit.

The new rule would be:

---

Script Rules

This rule describes how you may use automated tools, such as scripts, macros, and browser plug-ins, that interact with NationStates.

It is acceptable to use a tool that merely modifies how pages look to you. For example, a script that adds particular buttons in your browser when viewing other people's nation pages is fine. Similarly, any kind of information-gathering script is acceptable, provided that it sends no more than 10 requests per minute, or uses the official API.

It is illegal to use a tool to automatically execute actions. "Executing an action" means sending a request to the NationStates server that causes something in the gameworld to change. Examples include: moving regions, sending a telegram to another nation, banning a nation from a region, creating a nation, and endorsing another nation.

A tool is "automatically" executing an action if it sends the request on its own, without requiring a human to click at least once to initiate each action. For example, a tool that requires a few clicks to set up and thereafter sends ban requests to the server at five-second intervals is executing actions automatically, and is illegal. A tool that makes ban buttons appear in your browser where they aren't normally present, however, without actually initiating any bans, is legal.

Exception: Sending Telegrams

In recognition of the fact that NS has a very crude messaging interface, and that an improved one is in the works, which will hopefully allow some form of mass telegrams:

There is an exception to the above rule: A script or automated tool may send telegrams, providing that it does so at a rate of no more than 3 telegrams per minute.

The rate limit is adjudged per region/group/cause. That is, a group of people may not work together to send more than this rate of telegrams to promote the same region, WA resolution, or other cause.

Please note: This does not overrule any of the broader site rules regarding spam! You are required to stay within those rules, too.

[TBone Steaks]

Call me crazy, but the API doesn't have all the data required to defend one's region in this game.
Due to this, interaction with the html version is mandatory to retrieve the data.
Without access to said data, how do you play the game???

UNFORTUNATELY, the API does not hold all relevant Endorsement data.
The only way to see Endorsements is to download the full HTML version of the NS players page.

I have seen players open over 40 screens on a computer to view their regional nations and monitor those endorsements 2x daily, prior to updates. This is the only mechanism to deal with Raiders/Defenders in live time. This means that individuals ROUTINELY break the 10 requests per minute guideline associated with the proposed rule change MANUALLY!!!

If the script rules are tighter than what one can do manually, the systems to monitor activity will routinely flag false positives.

My question is this:
If one resides in a region with 800 WA members, how should the delegate maintain regional security?
Should it take them 90 minutes to view each of the nations?
If so, how should they maintain regional security over time?
When an individual downloads 20 pages in a minute, are they now classified as a script???
I can currently get timeouts on my browsers....without scripting acceleration.
So do we really want to tighten that further????

I understand this is a resources/cost/time discussion.
My only questions is this: Will this lead to more game play or less?
Will making the system less interactive lead to less security in the game?
And if that happens, will it lead to disenfranchisement of it's players?

Bottom line:
Either way we gather info (manually or with script), we have to go to the NS game to get the info.
There is no other place where it resides!

[Ballotonia]

First off, excellent simplification of the rules! A few comments though:

Similarly, any kind of information-gathering script is acceptable, provided that it sends no more than 10 requests per minute, or uses the official API.

Since the API allows 50 requests per 30 seconds I wrote all my scripts to throttle at a simple 1 request per second. That way I can use NS at the same time in my regular browser and still stay within the limit overall. This proposal limits the rate to one fetch per 6 seconds, which I think is horribly slow when compared to manual use of the site.

A typical script use would be to run an endorsement checker on a region to obtain a ranked overview of how many endorsements each nation has, and who has been handing out endorsements the most. Very handy in the middle of a fight, with nations cross-endorsing and where it might be unclear who is gunning for the delegacy. Information in such a situation is time-sensitive. It's also used for security purposes in large regions, like the feeders.

In a battle situation, say we're talking about a region with 150 nations, of which 50 are WA nations. There's an invasion, and we need to ensure that the nation we think is the lead invader actually is. And we need to have information about the natives, their last update time, longest residency, region update time, etc... so we know whom to contact, whether to endorse a native or have a defender lead, etc... My script runs while I'm checking their forums myself, and read their RMB, send TMs, talk on IRC with fellow defenders, whatever is needed. The script requires checking all WAs in the region. At 1 fetch per second my current script will present the results after one minute. Surely not as fast as we'd like, but still very useful. It taking 6 minutes means the information is dated by the time tabulation is completed and I'd have to manually go through the top rankers again to update. It also increases the odds that the region will have updated by the time we're done collecting data. Note all this only applies for an invasion where the invaders go in stealthily at a sufficient early time, and we discover that, like the invasions in Rohan or Ireland yesterday.

As an aside, note that when invaders perform a timed jump there's typically no time to do anything anyway, and the invaders are then really playing against the game server (can they correctly determine the jump time within two seconds? If so, they win!) instead of us. Those are also small regions, and none of the scripting considerations matter in those situations.

For very large regions: right now pulling all nation pages in a 6000 nation region (Lazarus) takes 100 minutes. With this proposal that would become 10 hours, which means such a script run won't even fit between two updates. If one is solely interested in endorsements (typical use, IMHO) then it's of course possible to limit the list to WA nations first using either the daily nation data xml dump, or if one needs an update since that moment then one could pull 6000 XML pages first at a higher rate. Or one could pull all regionlist pages first which has a WA icon for all WA members (which is what my own endochecker script does), meaning roughly 6000/15 = 400 calls first (in your proposal this will take 40 minutes), followed by a larger number of calls depending on how many WA's there actually are in the region. Say 800, requiring another 80 minutes, so two hours in total.

Right now, every day after an update has completed I run a script which checks/updates all my nations. This takes half an hour at the aforementioned 1 second per call throttle. This proposal would make that 3 hours, which is a tad much.

Overall, I'm suggesting to sticking to the current API speed limit for all fetches of data from NS.

It is illegal to use a tool to automatically execute actions. "Executing an action" means sending a request to the NationStates server that causes something in the gameworld to change. Examples include: moving regions, sending a telegram to another nation, banning a nation from a region, creating a nation, and endorsing another nation.

One thing I use my scripts for is answer issues. Part of me maintaining the Spoiler List of Issues is that I want my collection of 200+ nations to diverge in policies so I'm more likely to get rare issues in at least some nation. This is an insane workload when having to do so manually, and frankly if I had to do it manually I wouldn't do it at all. I'd of course still update the spoiler list, but my plan to have a collection of nations with a 'spread out' set of policies would become unworkable.

Hence, I'm requesting an exception is made for the action of answering/dismissing issues.

Ballotonia

[TBone Steaks]

GROUP 1 These file types css, jpg, png, and gif are all for the human eye exclusively.
These convey layout, color, style, and look.
GROUP 2 These file types are for both human and computer consumtion; html, xml.
These files convey information, and all the references to group 1.
GROUP 3 Actions, scripts, and things that change the game play itself would be a third type of interaction with the server.

Limiting groups 1 and 3 to actual human interaction seems fair and reasonable.
You have to have rules. But how do you do that???

By limiting group 2 information? The very essence of the game?
Without the data to make decisions, the game player has to wait on it or attack the servers.
I postulate that the latter is the unintended consequence...

Unfortunately, the system, as set, will not allow users to isolate group 2 information from groups 1 and 3.
I feel that this is the opportunity for improvement, data dissemination, and load elimination.

At this point, the system is set up to use sub domains to put different graphical templates on the data.
(conservative, normal, etc) This proves that we already are dealing with load balancing, and could isolate one (add another).

Typical traffic breakdown for most servers I see...
80% < GIF, JPG, PNG, CSS
20% > html, xml,
I bet these are similar after analyzing these pages.

Should a subdomain be altered to streamline the data, rather than the photos, we may eliminate the bottleneck with current infrastructure.
For each altered subdomain could serve 5x the data requests if the photos were removed...and if the folks only want the data...

Part of the solution, not the problem --> How to do it:
I propose a text only, html or xml version, of the individual Nations pages populate one of those subdomains.
If this system has a limit of 1 call per second, it would facilitate the info gathering for players.

The next question, and then separate question: is any automation allowed on the action scripts? (TG, Endo, issues)

A good example is how close the xml version for each page is...this could easily be modified from a code perspective.
To create rules on the remainder of the system, these scripts are migrated to an existing or new subdomain, isolating them.
Next, rules are created to limit the graphical side (the remainder), without touching the TXT only version for scripts/powerusers

Should this group of pages be published, API rules now direct powerusers and their scripts to the new group of pages.
As the traffic shifts, it will alleviate server load from photos, css, etc. associated with those queries.

This would attain the majority of the goals set forth above, but let's users maintain access to the data/systems to continue game play.

In addition, by separating the TXT ONLY version from the PRETTY version, you could enforce the 10 request/minute ideas on the graphical content side (current nation pages with all features) lots of different ways. The number of monitors that would work increase dramatically.

By doing both of these, giving the scripts a place to go, and limiting the existing infrastructure, you would be reducing the bandwidth, network load, and server requirements without limiting game play. In fact, you might find that as folks actually have the info they need, they hit the servers less often...

Just a humble outsiders opinion...

[New South Hell]

What Ballotonia said. Either illegalizing issue-answering scripts or restricting them to 6 seconds between requests (where I interpret the word "request" as meaning performing the same action as a manual click that causes a new page to be displayed) would make what I do completely impossible. This would make me very sad. If 6 seconds is really necessary to keep me (and others like me) from knocking over the server, then so be it. But at the very least, using scripts to answer issues does not affect any of the competitive game areas where restricting scripts makes sense for fairness. It is of no use for raiding, defending, or region/resolution promotion.

[Bears Armed]

There is an exception to the above rule: A script or automated tool may send telegrams, providing that it does so at a rate of no more than 3 telegrams per minute.

So a regional recruiter who has access to such a script would be able to set things up to continue the recruiting process while they themselves went and did something else (such as, for example, sleeping)? How would removing the need for personal action by them in this away actually improve the game for the players in general, rather than just for those regions that have active recruiters with access to such scripts?
(Speaking as a player who creates new nations moderately often, I do not see the fact that those new nations would probably receive a few more recruiting TGs each before I could move them to their intended destinations as a plus...)

(I would have no objection to letting scripts answer issues, although that isn't something that I'd use myself, though.)

[[violet]]

Ah! I should explain some of the thinking here. Because I have no intention of restricting what you guys are doing.

So there are basically two kinds of scripts: information-gathering scripts and better-than-human scripts. We like information-gathering scripts. They provide the raw data for some most excellent applications. Better-Than-Human Scripts, on the other hand, we don't like, because these execute game actions faster than a regular person can, and basically make the game unfair. They are tools that auto-detect and ban nations entering a particular region while the human player is having a nap. We want to eliminate or at least regulate Better-Than-Human scripts without interfering with information-gathering-scripts.

I tried to draw a line between these with the definition of "automatically executes game actions," but I see now that this puts scripts that only answer issues on the wrong line: they are really information-gathering scripts. So I will refine that definition to exclude actions that only affect your own nation: answering issues, changing your own custom fields, etc. We have no problem with any of that, because that doesn't make the game unfair for other people.

So! The question is: if we don't have a problem with information-gathering scripts, why am I proposing to limit them to 10 requests per minute? The answer is that I want them to use the API. Obviously the API doesn't offer as much info as the regular site, today, but I'm ready and willing to add to it. I have been for a while, but I suspect there's not much incentive for scripters to bother: they think they might as well just scrape the HTML.

Now, although we don't have a problem with information-gathering scripts, life would be better if they used the API. The API can be assured that everything accessing it is a script, and enforce speed limits without risking cutting off a real player who accidentally pressed F5 too many times. (When scripts go haywire, they go REALLY haywire, so it is good to manage them.) It can let us know clearly who's doing what, without having to try to sift that traffic out from the mountain of player traffic. And it can be many, many, MANY times more efficient. Serving up a region page is relatively taxing on the server. If someone's hitting that over and over and all they really want is the national happenings, or if they're constantly refreshing a nation page when all they want is the endorsements, probably 95% of the generated load is completely wasted. It's the server calculating the nation's tax rate and their freedoms and so on when nobody cares. Our game server is not under heavy load, but it's silly to be so wasteful.

If we limit scripts to 10 requests per minute when they scrape HTML, but 100 requests per minute when they use the API, I hope to get people asking for exactly the data they want, and add that in there. For example, if you want an endorsement checker, let's have an API call that just returns a nation's endorsements. I could raise the rate limit even higher for something that light. But the point is to encourage scripters to use the API.

[New South Hell]

OK, let me make a formal request. I want an API that will allow me to fetch all of a nation's pending issues (with an indication for each whether it had already been answered), and to answer them. It would be nice to also have an API I could use to change settings, specifically, number of issues wanted per day and vacation mode. (I don't have scripts doing this now, because I believed it was forbidden, but I sure would like to have it.) I would like to have this API before the rule of 10 per minute goes into effect - I cannot see any way to get what I do under 24 seconds per nation (assuming only one issue to answer) via the existing HTML interface; at that rate, the cost becomes prohibitive, and I will have to do some ruthless pruning of my empire. I might have to kill the Ulthar bots. (Do what I say, or this cute little bot gets it! )

Thanks for listening.

[Glen-Rhodes]

First, thank you for the telegram exception! The 3 telegrams per minute actually means I can reduce the interval between telegrams to 20 seconds from 30, for my auto-TG user-script. Though, I need to figure out the flood limit again, since that might impact the required interval...

I do have one question, though. My World Assembly vote analysis tool operates via scraping, since there is no API tools for the World Assembly. I can't really limit the scraping to 10 requests per minute, since the tool isn't automated: it scrapes whenever somebody requests the page. This can easily go over the request limit. If I do somehow limit the scraping to 10 requests per minute, that has the potential to make the tool essentially useless.

So, would it be possible to either get World Assembly vote info in the API, or to create an exception for this tool in particular? Having the API information would be the preferable option, since the information I want isn't organized very well for scraping. If you do think about adding it to the API, I would like to see at least each delegate's vote and voting power and the delegate voting history. It would be great if each nation's vote was recorded in the API, but not necessary for the functioning of my tool.

[Echolilia]

any kind of information-gathering script is acceptable, provided that it sends no more than 10 requests per minute, or uses the official API

As has been pointed out, the api (as far as I am aware - is there a single post that lists all the api functionality?) is lacking the data to monitor endorsements in a region. This has two parts: getting a list of WA nations in a region and checking endorsements for each nation. Right now, this requires 1 + (total nations/15) + (WA nations) requests; at 10/min this becomes impossible in large regions.

There is an exception to the above rule: A script or automated tool may send telegrams, providing that it does so at a rate of no more than 3 telegrams per minute.

The rate limit is adjudged per region/group/cause. That is, a group of people may not work together to send more than this rate of telegrams to promote the same region, WA resolution, or other cause.

Please note: This does not overrule any of the broader site rules regarding spam! You are required to stay within those rules, too.

It's not clear to me if you mean to include or exclude recruiting.

[Zybodia]

I have a script I use to track World Census results in my region. (Or occasionally other regions/groups of nations.) I use the API to get the list of nations, but I still have 200-300 individual nation pages I have to scrape to get the information I want. Is this something that an API could be created for?

I also, like others who have posted, use a script to log on and check for new issues/telegrams. I am fairly certain I could do 15-20 requests per minute manually. Is there a reason scripts have to be slower than a keyboard and mouse? (The main reason I do it with a script at the moment is so I can have a little better password security, and not the same two-letter password for every nation. )

I might have to kill the Ulthar bots. (Do what I say, or this cute little bot gets it! )

Don't kill my bot!

[Aurora-Nova]

For those of us unfamiliar with the API, and how to script using APIs, I'd have to say I dislike the 10 actions per minute rule. I've been in the process of building a script to deal with my issues; there's a definite drawback when it can only do ~three issues per minute and then has to pause. I realize there may be a more efficient way to script what I'm doing, but not everyone has the technical know-how to be able to.

-snip-

Oh hey, I found the nation whose flag looks awesome alongside TGs :3

[TBone Steaks]

Violet, thank you for the clarity regarding info vs action scripting.
Concise, clear, Great.
All I wish to do is gather data, so I am going to be happy when these APIs take shape.

However, I think all these posts prove the point as to the disparity of our needs.
In the end, which is easier?

1. Stipping down a Graphic rich HTML version to a Txt only version of the HTML for us to scrape, automate, and run light.
Each of us is using different pieces. No matter what this covers them all in one shot.

OR

2. Building the API to the same level as the HTML versions.
To satisfy each of the disparate needs, each part will have to be added, tested, and deployed to the API.

(I'm all for building stuff up, but it takes more time. --> Trying to make it easy on you Violet.)

[Echolilia]

1. Stipping down a Graphic rich HTML version to a Txt only version of the HTML for us to scrape, automate, and run light.
Each of us is using different pieces. No matter what this covers them all in one shot.

But...HTML is text.

[Augustus Este]

I would much prefer a recruitment re-haul that makes it easier for everyone to recruit than a rule that puts most UCR members at a disadvantage for not having the programming skills that a select few have.

[Ballotonia]

Can the API perform logins at all? Cause that's what it would require to do in order to fetch telegrams ans answer issues...

As for the endorsement-checking API, I would be thinking of something along the line of:

Code: Select all

<REGION>
<NAME>nederland</NAME>
<ENDOS NATION="leepaidamba">carlswald</ENDOS>
<ENDOS NATION="xamery">dangertk:carlwald</ENDOS>
<ENDOS NATION="dangertk">leepaidamba:carlswald:xamery:ballotonia</ENDOS>
<ENDOS NATION="carlswald"></ENDOS>
</REGION>

So listing only the WA nations, and the endorsements they carry. Wouldn't have to be excluding the ones they still carry by nations no longer in the region or the ones no longer in the WA (note the "ballotonia" I added in there). That's all easily enough handled in post-processing.

Thing is, that combines information from many nations at once. While ideal, I can imagine that being too difficult to handle for the server. Another option would be to have a list of WA nations in the region (so one wouldn't have to either individually check ALL nations, or go back to the HTML side and fetch the nation list there), and then one could request the endorsement list for each nation individually. Then again, at that point one could make the endorsement list part of the regular nation XML feed, perhaps. Not sure how either option would work out server-strain wise, but it can't be worse than us pulling all the HTML each time

Ballotonia

[New South Hell]

Given, Lady [violet], that you are now in the mood to make API changes, I would like to request the following additions to the nationdata. If these additional items require extra server work to compute, I suggest making them optional, and further suggest moving the DEATH statistics to the optional information, as I imagine that most users of the XML find them uninteresting. I would like to be able to get the following, all of which are available in some form from the HTML, but not from the XML:

1. Crime rate, either in words (as in the nation page) or as a number.
2. National animal status (e.g., frolicking, stable, endangered, dinner), or as a number.
3. The adjectives describing the population (e.g., "hard-nosed, hard-working, intelligent".)
4. The adjectives describing the government (e.g., "omnipresent, corrupt, moralistic".)

Being greedy, I'd like to see these in the daily data dump as well.

Items 1 and 2 are the game's primary visible indicators of public safety and of the environment. If the feed will give us our freedom scores and our rates of death and taxes, why not these? As for items 3 and 4, I have long intended to do some serious research to try to figure out what these adjectives actually indicate, and this would help me do so. I understand that it might be considered an undesirable spoiling for people to actually understand this aspect of their nation page - but I'm afraid I crossed into that sort of spoiling category years ago, and you have been willing to feed my habit thus far.

Thanks for your consideration.

- nsh -

[[violet]]

I would like to have this API before the rule of 10 per minute goes into effect

I won't require anyone to abide by that if they've asked for an API and I haven't provided it yet. So if you're currently scraping data from the HTML at a rate of more than 10 requests per minute, just post here exactly what data you want, and you're fine.

I'm thinking that in some cases, it might be easier for all concerned if the API returns plain text, rather than XML. For example, if you just want a nation's endorsements, perhaps we have an API call like "api.cgi?nation=testlandia&q=endos" that simply returns a one-liner like "new_south_hell,ballotonia,echolilia". That is probably easier for beginning scripters to figure out.

So, would it be possible to either get World Assembly vote info in the API

Yes, absolutely. I can add an API for just about anything.

is there a single post that lists all the api functionality?

The API itself has documentation. Let me know if anything in there isn't clear.

It's not clear to me if you mean to include or exclude recruiting.

The script rule doesn't care about the content of telegrams. There are other rules covering that. The script rule only regulates how quickly you may send TGs when you use an automated tool to do it.

I have a script I use to track World Census results in my region. (Or occasionally other regions/groups of nations.) I use the API to get the list of nations, but I still have 200-300 individual nation pages I have to scrape to get the information I want. Is this something that an API could be created for?

Yes, absolutely. I especially want to create APIs for data that currently requires hundreds of separate page loads.

I also, like others who have posted, use a script to log on and check for new issues/telegrams.

Do you use a subscription for this? That lets you check for new issues and TGs without having to log in.

Is there a reason scripts have to be slower than a keyboard and mouse?

Yes, the reason is we're attacking Better-Than-Human scripts. I don't want those to be faster than a person. Information-gathering scripts I am happy to be much faster, and the best way to support that is to route them through an API.

For those of us unfamiliar with the API, and how to script using APIs

The API is supposed to be easier for scripters to use than the HTML site. If it's not, please post in the Technical forum and you'll get help.

One advantage of the API is that it doesn't change. Currently, if you're scraping HTML, you're probably making a few assumptions about the layout of various pages: e.g. that the data you want is enclosed within a particular set of tags. But if/when we tweak the layout, and the tags change, your script breaks.

In the end, which is easier?

1. Stipping down a Graphic rich HTML version to a Txt only version of the HTML for us to scrape, automate, and run light.

Scripts almost never load graphics and other elements; they just read the HTML. So this is essentially what they are already doing. Not that it makes a huge difference, since it's computationally cheap to serve up static elements like image files; what takes time is generating dynamic pages. And it's pretty wasteful if someone has to send 200 requests to browse a region's complete World Census results, and each of those 200 requests the server is performing a bunch of calculations that nobody cares about.

I would much prefer a recruitment re-haul that makes it easier for everyone to recruit than a rule that puts most UCR members at a disadvantage for not having the programming skills that a select few have.

So would I! But until we get that, I think it would be a shame to ban outright scripts like G-R's, which don't really provide any unfair gameplay advantages, but do make life a little less tedious.

Can the API perform logins at all? Cause that's what it would require to do in order to fetch telegrams ans answer issues...

Right. I'll have to look into this. Today, the API has the ability to maintain logins, so if you're already logged in, it can understand that you're authenticated and should be permitted to, say, view that nation's current issues. But it can't do anything that changes game state.

Given, Lady [violet], that you are now in the mood to make API changes, I would like to request the following additions to the nationdata.

Okay, I can probably do this. I should explain that in the past, the reason I have been reluctant to add too much stuff to the nationdata and regiondata APIs is to avoid the situation where a script only cares about, say, endorsements, and hits us at a frenetic rate because it wants to keep refreshing them, and every time the API is calculating tax rates and crime rates and freedom rankings and a whole bunch of other stuff that's totally unneeded.

So at this point I am leaning towards "sharding" the data, where your script could ask for exactly what it wants (e.g. "api.cgi?nation=testlandia&q=region+endos+wa"), and that would be permitted to run hotter than a script that wants everything. I would then feel more comfortable about adding a bunch of extra data into the "full" API, knowing it wasn't going to get smashed at 100/requests per minute by someone who doesn't even want it.

[Christian Democrats]

The new rule would be:

---

Script Rules

Exception: Sending Telegrams

In recognition of the fact that NS has a very crude messaging interface, and that an improved one is in the works, which will hopefully allow some form of mass telegrams:

There is an exception to the above rule: A script or automated tool may send telegrams, providing that it does so at a rate of no more than 3 telegrams per minute.

The rate limit is adjudged per region/group/cause. That is, a group of people may not work together to send more than this rate of telegrams to promote the same region, WA resolution, or other cause.

I really dislike this. I don't know how to write a script and don't have access to a telegramming script. For World Assembly campaigning and regional recruiting, I manually send telegrams at a rate of about 3-4 telegrams/minute. This rule would put me and other manual telegrammers at a great disadvantage (especially in recruiting). Doing minimal work, scripters would be able to send many more telegrams.

[[violet]]

G-R's script is public, isn't it?

[Aurora-Nova]

Alright, a few thoughts on these...

I would like to have this API before the rule of 10 per minute goes into effect

I won't require anyone to abide by that if they've asked for an API and I haven't provided it yet. So if you're currently scraping data from the HTML at a rate of more than 10 requests per minute, just post here exactly what data you want, and you're fine.

I guess then I'll post that it would be nice to have the API serve up issues. But what I'm less sure about, being unfamiliar with the setup, is whether it would be possible for the API to allow us to actually deal with issues; that is to say, from what I've seen of the API, it merely serves information, it doesn't in and of itself give us anything to work with. Now sure, I could build a form around the issues code it gives me and have my script submit that issue... but then, I'd no longer be using the API: I'd be submitting requests directly to the server through a form like http://www.nationstates.net/page=show_dilemma/dilemma=212. That places me right back where I started in the 10-actions-per-minute rule, does it not?

I also, like others who have posted, use a script to log on and check for new issues/telegrams.

Do you use a subscription for this? That lets you check for new issues and TGs without having to log in.

Now that you mention it, subscriptions may help what I'm doing, but I'd still be outside of the API and subject to the action limit.

Is there a reason scripts have to be slower than a keyboard and mouse?

Yes, the reason is we're attacking Better-Than-Human scripts. I don't want those to be faster than a person. Information-gathering scripts I am happy to be much faster, and the best way to support that is to route them through an API.

Forgive me if I misunderstood you, Zybodia, but I'm pretty sure he wasn't asking, "Why can't it be faster than humans?" I think he was asking, and what I'd like to know the answer to, is, "Why can't it be on par with humans?" Because that's, by very definition, not better-than-human. It's the same as human.

For those of us unfamiliar with the API, and how to script using APIs

The API is supposed to be easier for scripters to use than the HTML site. If it's not, please post in the Technical forum and you'll get help.

One advantage of the API is that it doesn't change. Currently, if you're scraping HTML, you're probably making a few assumptions about the layout of various pages: e.g. that the data you want is enclosed within a particular set of tags. But if/when we tweak the layout, and the tags change, your script breaks.

Well, so far there is no API for issues, so the point is moot at the moment, I think. All the same, I'm not averse to tweaking my script if the layout changes.

[Cerberion]

I'm pretty concerned about the ability to script telegram sending. When we talk about a script acting like a super human, being able to send telegrams at a rate of three a minute, 24 hours a day, 7 days a week would certainly qualify in my opinion.

The best part about the current system is that, particularly in the case of recruitment, there should be someone on the other end of that TG to respond to enquiries from the recipient.

As for moving anything we scrape into the API, I applaud the concept. For example having the regional and recent WA happenings accessible via an API would be great.