Shortr API Documentation

Shortr exposes its data via an Application Programming Interface (API), so developers can interact in a programmatic way with the Shortr website. This document is the official reference for that functionality. The current API version is 1.1.0

Getting Started

Here are the topics covered in the Shortr REST API documentation. Also, see API Best Practices

Sections

Shortr API Documentation

Request / Response Formats

All Shortr API calls support an optional return format parameter. Note that json is the default response format. but xml, serialized PHP array and a simple txt format is also available.

format=json

All Shortr APIs support jsonp which is the json format with a callback specified, such as:

format=json&callback=callback_method

All API requests should be against the domain shortr.tk (see examples).
HTTP Response Status Code is 200 on all valid responses. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid. In txt responses, the format status_code [space] status_txt is used for non 200 response codes.
HTTP Response Status Codes 403, 500 and 503 are used denote rate limiting, a problem with the request format, or an unknown error.
The status_code is 200 for a successful request, 403 when rate limited, 503 for an unknown error or temporary unavailability, and 500 for all other invalid requests or responses.
status_txt will be a value that describes the nature of any error encountered. Common values are MISSING_ARG_%s to denote a missing URL parameter, and INVALID_%s to denote an invalid value in a request parameter (where %s is substituted with the name of the request parameter).

Here are some examples:

json

{
  "status_code": 200,
  "status_txt": "OK",
  "data": ...
}

json

{
  "status_code": 403,
  "status_txt": "RATE_LIMIT_EXCEEDED",
  "data": null
}

json

{
  "status_code": 500,
  "status_txt": "INVALID_URL",
  "data": null
}

json

{
  "status_code": 500,
  "status_txt": "MISSING_ARG_ACTION",
  "data": null
}

json

{
  "status_code": 503,
  "status_txt": "UNKNOWN_ERROR",
  "data": null
}

jsonp

callback_method({
  "status_code": 200,
  "status_txt": "OK",
  "data": ...
})

xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
     <status_code>200</status_code>
     <status_txt>OK</status_txt>
     <data>
         ...
     </data>
</response>

CORS (Cross Origin Resource Sharing)

The Shortr API supports CORS, or Cross Origin Resource Sharing.

Previously, Javascript AJAX requests were restricted to a same domain origin policy. This meant that your website at http://mysite.com/ could not make AJAX requests to http://shortr.tk/, since they were not the same domain. With the introduction of HTML5 and advancements in modern browsers, CORS allows website owners to control who can access data via Javascript AJAX requests. In this way, CORS functions like Flash's Cross Domain Origin Policy. Shortr API supports CORS requests from any domain.

Here is some basic example Javascript to get you started:

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://shortr.tk/api.php?action=create&url=http://shortr.tk");
xhr.onreadystatechange = function() { 
    if(xhr.readyState == 4) { 
        if(xhr.status==200) {
            console.log("CORS works!", xhr.responseText);         
        } else {
            console.log("Oops", xhr);
        }
    } 
}
xhr.send();

You can also read more about CORS here.

Rate Limiting

Shortr currently limits API users to no more than four concurrent connections from a single IP address. Also, Shortr institutes a limit of 140 API requests per hour. Remaining number of API requests, for the hour, is provided in the HTTP header "X-Rate-Limit-Remaining".

While rate limits exist, default limits are more than sufficient for nearly any size site.

Please note that API rate limits reset every hour on the hour. If you are experiencing rate limiting errors, please wait until the top of the hour to resume making API calls. Reset time (in UTC) is provided, as a Unix timestamp, in the HTTP header "X-Rate-Limit-Reset".

To avoid common causes of rate limiting issues, please read API Best Practices.

High-volume users

If you're a high-volume user of the Shortr API, please contact me at ameer1234567890@gmail.com to discuss your options.

When contacting me, include a description of how you are using the Shortr API, which API endpoints you are using, and a current request volume over a 24 hour period.

QR Codes

To generate a QR code, simply append .qrcode to the end of any Shortr link. For example, the following URL: http://shortr.tk/1d.qrcode returns a QR code for the shortr.tk link to this page.

REST API

/api.php?action=create

For a long URL, /api.php?action=create encodes a URL and returns a short one.

Parameters

format indicates the requested response format. supported formats: json, jsonp, xml, txt.
url is a long URL to be shortened (example: http://www.google.com).
v (optional) is the API version being used. This is version 1 of the API. If ommitted, this would default to the latest version. Thus, it is recommended to indicate a version number if you care about backwards incompatibilities in future versions. Note that only major versions of the API should be passed in v parameter. Backwards incompatible changes would be done only in major versions.

Notes

URLs should be URL-encoded. You can not include a URL in the request that has '&', '?', '#', ' ', or other reserved parameters without first encoding it.
URLs should not contain spaces: any URL with spaces will be rejected. All spaces should be either percent encoded (%20) or plus encoded (+). Note that tabs, newlines and trailing spaces are all indications of errors. Please remember to strip leading and trailing whitespace from any user input before shortening.
URLs must have a slash between the domain and the path component. For example, http://example.com?query=parameter is invalid, and instead should be formatted as http://example.com/?query=parameter

Output

short_url is the shortened link.
long_url is an echo back of the url request parameter. This may not always be equal to the URL requested. That is because some URL normalization may occur (e.g., due to encoding differences, or case differences in the domain). This long_url will always be functionally identical the the request parameter.

Examples

json format http://shortr.tk/api.php?action=create&url=http%3A%2F%2Fwww.google.com&v=1&format=json

{
  "status_code": 200,
  "status_txt": "OK",
  "data": {
    "short_url": "http://shortr.tk/12",
    "long_url": "http://www.google.com",
    }
}

xml format http://shortr.tk/api.php?action=create&url=http%3A%2F%2Fwww.google.com&v=1&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status_code>200</status_code>
  <status_txt>OK</status_txt>
  <data>
    <short_url>http://shortr.tk/12</short_url>
    <long_url>http://www.google.com</long_url>
  </data>
</response>

serialized php array format http://shortr.tk/api.php?action=create&url=http%3A%2F%2Fwww.google.com&v=1&format=php

a:3:{s:11:"status_code";s:3:"200";s:10:"status_txt";s:2:"OK";s:4:"data";a:2:{s:9:"short_url";s:19:"http://shortr.tk/12";s:8:"long_url";s:21:"http://www.google.com";}}

which, when unserialized returns an array in the form:

array (
  'status_code' => '200',
  'status_txt' => 'OK',
  'data' => 
  array (
    'short_url' => 'http://shortr.tk/12',
    'long_url' => 'http://www.google.com',
  ),
)

txt format http://shortr.tk/api.php?action=create&url=http%3A%2F%2Fwww.google.com&v=1&format=txt
```
http://shortr.tk/12
```

/api.php?action=view

Given a Shortr URL, /api.php?action=view decodes it and returns back the target URL.

Parameters

format indicates the requested response format. supported formats: json, jsonp, xml, txt.
id refers to the Shortr URL, (e.g.: http://shortr.tk/12).
v (optional) is the API version being used. This is version 1 of the API. If ommitted, this would default to the latest version. Thus, it is recommended to indicate a version number if you care about backwards incompatibilities in future versions. Note that only major versions of the API should be passed in v parameter. Backwards incompatible changes would be done only in major versions.

Notes

ID parameter should not include "http://shortr.tk/"

Output

short_url this is an echo back of the id request parameter preceeded by "http://shortr.tk/".
long_url is the URL that the requested short_url points to.

Examples

json format http://shortr.tk/api.php?action=view&id=12&v=1&format=json

{
  "status_code": 200, 
  "status_txt": "OK",
  "data": {
    "short_url": "http://shortr.tk/12", 
    "long_url": "http://www.google.com", 
  }
}

xml format http://shortr.tk/api.php?action=view&id=12&v=1&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status_code>200</status_code>
  <status_txt>OK</status_txt>
  <data>
    <short_url>http://shortr.tk/12</short_url>
    <long_url>http://www.google.com</long_url>
  </data>
</response>

serialized php array format http://shortr.tk/api.php?action=view&id=12&v=1&format=php

a:3:{s:11:"status_code";s:3:"200";s:10:"status_txt";s:2:"OK";s:4:"data";a:2:{s:9:"short_url";s:19:"http://shortr.tk/12";s:8:"long_url";s:21:"http://www.google.com";}}

which, when unserialized returns an array in the form:

array (
  'status_code' => '200',
  'status_txt' => 'OK',
  'data' => 
  array (
    'short_url' => 'http://shortr.tk/12',
    'long_url' => 'http://www.google.com',
  ),
)

txt format http://shortr.tk/api.php?action=view&id=12&v=1&format=txt
```
http://www.google.com
```

Revision History

Version	Date	Change
1.0.0	2011-Jun-13	Initial v1 API released.
1.1.0	2011-Aug-20	Serialized php array response format added.