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:

• 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/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:

• 0 - No URL was specified or the URL specified was invalid, 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

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