API Documentation

pxlz.org provides a fairly basic API (Application Programming Interface) which can be used in order for other applications to harness our URL shortening service. This works by accessing a particular URL on the pxlz.org site which accepts the long URL you would like shortened as a parameter. The shortened URL (or various error conditions as appropriate) will then be returned in the HTTP response.

Submitting a URL to be shortened

Simply have your application access a URL similar to the following, via an HTTP GET request: http://pxlz.org/api.php?url=http://www.example.com

The "http://www.example.com" parameter in the example above may be replaced by whatever URL you wish to shorten. The http:// protocol specifier is optional (if you don't specify any protocol, HTTP will be assumed and added automatically).

Receiving the shortened URL

After submitting the URL you would like shortened as specified above, an HTTP response (web page) will be returned. The response header will be "HTTP/1.1 200 OK" if the URL was shortened as expected, or "HTTP/1.1 500 Internal Server Error" if there was any problem that prevented this.

Assuming the request was successful, the body of the response will contain only the new shortened URL, in plain text.

Possible errors

If the request was unsuccessful, the body of the response will contain a specific error message giving the reason, which may be any of the following:

• "Error: url parameter was not entered." - the API script was accessed but a URL to be shortened was not correctly supplied in the format given above
• "Error: The URL entered was not valid." - a blank or other obviously invalid URL was submitted
• "Error: The URL entered was too long." - a URL longer than the 2,000 character limit we have imposed was submitted
• "Error: The address making this request has been blacklisted by Spamhaus (SBL/XBL) or Spamcop." - the address of the machine/network making the request appears on a list of known spammers (may be compromised)
• "Error: The URL entered is a potential spam site and is listed on either the SURBL or URIBL blacklist." - self explanatory, we take all technical measures possible to ensure that pxlz.org is not used for SPAM purposes.
• "Error: The URL you entered is on our blacklist (links to URL shortening sites or pxlz.org itself are disabled to prevent misuse)" - also fairly self explanatory. We've begun to blacklist as many other URL shortening/redirection sites as possible, since spammers were using chains of them in an attempt to circumvent our filtering.
• "Error: The address making this request has been blocked by pxlz.org (normally the result of a violation of our terms of use)" - the machine making this request has been blacklisted by pxlz.org, most likely due to a violation of our terms of use.

Encoding

Many special characters in the URL you send (the url parameter) may not be stored in our database correctly unless they are URL encoded before you send them. Many languages have a function to do this. This specifically includes the hash sign (replace with %23), the semicolon sign (%3B) and the plus sign (%2B). We're currently considering other ways to access the pxlz.org API which should make this less cumbersome in future, so watch this space.

Getting an original URL from a shortened URL

If for some reason you want to retrieve the original long URL from a URL shortened with pxlz.org, the API doesn't directly provide a function for this. This is because it's generally as easy to do this just by visiting the URL itself. If you grab the HTTP header from visiting a valid pxlz.org shortened URL, you will get an HTTP 301 redirect header with the location parameter set to the original long URL. If you get any other kind of header, most likely that shortened URL doesn't exist.

Terms

Application authors should note that users of the pxlz.org API are expected to comply with the same terms of use as users of the website. E.g. regardless of how they are created, links to spam/illegal sites etc. will likely be deleted and offenders may be banned from the pxlz.org service. Having said that, we don't expect or require the authors of applications that use pxlz.org to be responsible for the actions of their users. Violations will be considered on a case by case basis.

Conditions on excessive usage still apply - the API is primarily intended for use in low volume applications and applications such as browser plugins, scripts etc. that run on the machine of an end user. There is now a hard limit of 1,000 shortened URL creations per day per IP address which we've had to introduce to keep things running smoothly for everyone due to a small number very heavy users. After this limit is reached, no further requests will be accepted that day (rolling 24 hour period).

Also note that if you're submitting large amounts of requests for any reason and hammering the server (e.g. if you have a bad script that submits the same URLs over and over again throughout the day) I will block your IP at my firewall without notice. Please email me if you encounter this or have any queries.