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:

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:

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/1pa4XTq&apiKey=YOUR_API_KEY

Response:

http://unshorten.it/api/documentation


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/1pa4XTq&responseFormat=json&apiKey=YOUR_API_KEY

Response:

{"fullurl":"http:\/\/unshorten.it\/api/documentation"}


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/1pa4XTq&responseFormat=xml&apiKey=YOUR_API_KEY

Response:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
     <fullurl>http://unshorten.it/api/documentation</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/1pa4XTq&responseFormat=xml&return=domainonly&apiKey=YOUR_API_KEY

Response:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
     <domain>unshorten.it</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/1pa4XTq&responseFormat=xml&return=both&apiKey=YOUR_API_KEY

Response:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
     <fullurl>http://unshorten.it/api/documentation</fullurl>
     <domain>unshorten.it</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/1pa4XTq&responseFormat=text&return=both&apiKey=YOUR_API_KEY

Response:

http://unshorten.it/api/documentation|unshorten.it

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:

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