API Documentation

API No Longer Supported

The Unshorten.It! API is no longer supported and new registrations for API keys will not be accepted. The API will continue to operate for current users however it is recommended that users migrate away from it. The documentation below has been left for current users of the API.

It is suggested that instead of using the API, Applications implement the logic to expand the shortened URL themselves, this is a fairly simple task. The way that Unshorten.It's logic works is as follows. The application makes an HTTP GET request to the shortened URL and looks at the resposne time, if it is a 301 redirect it will do the same request again for the URL pointed to by the redirect. If the response code is 200 it will check the body for any meta tag redirects, if a meta redirect is found it will again follow the same process with the URL pointed to by this redirect, if the response code is 200 and the body does not contain a meta redirect, then that URL is said to be the full URL. This is expressed as psuedocode below. If you are using Python, the Python Requests library is great for this sort of thing and is what Unshorten.It uses internally.

function unshorten_url(url) {
    response = make_get_request(url)
    if (response.status_code == 301) {
        // Attempt to unshorten the redirected to URL
        return unshorten_url(response.redirect_destination)
    } else if (response.status_code == 200) {
        if (response.body.contains_meta_redirect) {
            // Attempt to unshorten the redirected to URL
            return unshorten_url(response.body.meta_redirect_destintation)
        } else {
            // No more redirects found so return the final URL
            return url
        }
    } else {
        // Throw exception or something
    }
}

Documentation for current users

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