API Documentation

Open URL Shortener 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 Open URL Shortener 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.

Since September 2012 under the excessive abuse from some users (most from .ru) the API is only available for registered users, check the API URL in your profile.

Submitting a URL to be shortened

Simply have your application access a URL similar to the following, via an HTTP GET request:


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, if the request was unsuccessful, the body of the response will contain a specific error message giving the reason. These always begin with "Error: " followed by a message describing why the error occured, these should be fairly self explanatory and include things like the URL being on our blacklist or being too long (over 2000 characters).


Many special characters in the URL you send (the longurl 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). The easiest way to accomplish this if it's available to you is to run URLs through the Javascript function encodeURIComponent() before submitting. This should avoid any of these issues since this is the same method the Open URL Shortener bookmarklet uses, so should be 100% compatible.


Application authors should note that users of the Open URL Shortener API are expected to comply with the same Terms of Usage 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 Open URL Shortener service. Having said that, we don't expect or require the authors of applications that use Open URL Shortener 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. As such if you're submitting extreme 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) we may block your IP at our firewall without notice. The same applies if you're opening multiple concurrent connections. Please email via the contact section if you have any queries.