API Documentation

Want to unshorten URLs in your own application? Well, now you can with ease by using our free public API (Application Programming Interface).

In order to use our API you are required to register for a free API key. This allows us to monitor usage of the API and allows us to contact you in the event of any changes to the API. Registration is free and your key will not expire.

To register for a free API key, click here.

Our API can return the results in the following formats:

Plain Text
XML
JSON

Our API can return either the full URL that the shortened URL points to e.g. http://example.com/folder/page.html or just the domain name e.g. http://example.com

To use our API you must send parameters via a regular GET request in the URL. Below is a list of parameters that are accepted by our API:

shortURL - Required

This is the URL that you would like to unshorten

responseFormat - Optional

This defines which format the data is returned in and has three options:

text returns a plain text response
xml returns an XML response
json returns a JSON encoded response.

If this parameter is not used, the response will default to plain text.

return - Optional

This defines whether the full URL that the short URL points to (including files/directories) is returned or just the domain name. There are three options:

fullurl returns the entire URL e.g. example.com/foo/bar.html
domainonly returns the domain name that the short URL points to e.g. example.com
both returns both the full URL and the domain only.

If this is not specified it will default to returning the full URL.

Requests should be made to our API at the following URL http://api.unshorten.it

Sample Requests

Simplest form of request that returns the full URL in plain text

This request only sends one parameter, shortURL, both the responseFormat and return parameters are not supplied and thus default to text and fullurl respectivly.

Request:

http://api.unshorten.it?shortURL=http://bit.ly/mhCHiI&apiKey=YOUR_API_KEY

Response:

http://www.iana.org/domains/example/

Request that returns the full URL in JSON format

This request sends two parameters, shortURL and responseFormat, thereturn parameter is not supplied and thus defaults to fullurl.

Request:

http://api.unshorten.it?shortURL=http://bit.ly/mhCHiI&responseFormat=json&apiKey=YOUR_API_KEY

Response:

{"fullurl":"http:\/\/www.iana.org\/domains\/example\/"}

Request that returns the full URL in XML format

This request sends two parameters, shortURL and responseFormat, thereturn parameter is not supplied and thus defaults to fullurl.

Request:

http://api.unshorten.it?shortURL=http://bit.ly/mhCHiI&responseFormat=xml&apiKey=YOUR_API_KEY

Response:

<?xml version="1.0" encoding="UTF-8" ?>

		<response>

		     <fullurl>http://www.iana.org/domains/example/</fullurl>

		</response>

Request that returns only the domain name in XML format

This request sends all three parameters, shortURL, responseFormat and return.

Request:

http://api.unshorten.it?shortURL=http://bit.ly/mhCHiI&responseFormat=xml&return=domainonly&apiKey=YOUR_API_KEY

Response:

<?xml version="1.0" encoding="UTF-8" ?>

		<response>

		     <domain>www.iana.org</domain>

		</response>

Request that returns both the full URL and the domain name in XML format

This request sends all three parameters, shortURL, responseFormat and return.

Request:

http://api.unshorten.it?shortURL=http://bit.ly/mhCHiI&responseFormat=xml&return=both&apiKey=YOUR_API_KEY

Response:

<?xml version="1.0" encoding="UTF-8" ?>

		<response>

		     <fullurl>http://www.iana.org/domains/example/</fullurl>

		     <domain>www.iana.org</domain>

		</response>

Request that returns both the full URL and the domain name in plain text format

This request sends all three parameters, shortURL, responseFormat and return.

Request:

http://api.unshorten.it?shortURL=http://bit.ly/mhCHiI&responseFormat=text&return=both&apiKey=YOUR_API_KEY

Response:

http://www.iana.org/domains/example/|www.iana.org

Note that the full URL and domain are separated by the | character, if you are using PHP you can use the explode function to split this up into an array.

Error Codes

Our API will return an error code if the request is invalid or the URL cannot be unshortened. Below is a list of the error numbers and what they mean:

0 - No URL was specified, please check your request, It is crucial to handle this error in your application
1 - Invalid response format, the responseFormat parameter is invalid, please check your request is only using one of the following parameters (text, xml, json)
2 - Invalid return parameter, the return parameter is invalid, please check your request is only using one of the following parameters (fullurl, domainonly, both)
3 - Could not unshorten, the URL was not unshortened successfully, it is either not a shortened URL or the shortening service is incompatible with our system, It is crucial to handle this error in your application
4 - Invalid API Key, The API key specified does not exist or was not specified. You should register an API key for free
5 - Rejected by destination site, the destination server has rejected the request. This is due to the configuration of the website at the destination of the short URL and cannot be recovered, try another URL. This is a VERY rare error and has only been witnessed on one website so far.

The error code is returned differently depending on the response format:

Plain Text:

error (0)

JSON:

{"error":0}

XML:


		<?xml version="1.0" encoding="UTF-8" ?>

		<response>

		     <error>0</error>

		</response></code>

Important Note: Error number 1 (Invalid response format) will always be returned as plain text since the system cannot tell which format to return the error in, you must handle this in your application