ApiDocumentation

bitly REST API method documentation
Featured

Updated Dec 21, 2011 by matthew....@gmail.com

bitly API Documentation

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

Getting Started

Here are the topics covered in the bitly REST API documentation. Also, see our ApiBestPractices

Sections

bitly API Documentation

Getting Started
Authentication and Shared Parameters
Request / Response Formats
CORS (Cross Origin Resource Sharing)
Rate Limiting

High-volume users

OAuth

OAuth Web Flow
OAuth XAuth Flow

QR Codes
API Key Security
REST API

/v3/shorten
/v3/expand
/v3/validate
/v3/clicks
/v3/referrers
/v3/countries
/v3/clicks_by_minute
/v3/clicks_by_day
/v3/bitly_pro_domain
/v3/lookup
/v3/info
/oauth/access_token
/v3/user/clicks
/v3/user/referrers
/v3/user/countries
/v3/user/realtime_links

Discussion
Revision History

Authentication and Shared Parameters

All API endpoints require that authentication credentials be supplied as query arguments. All V3 API endpoints now support an OAuth access_token. We strongly recommend using this authentication method for any scenario in which you will be calling the bitly API on behalf of multiple users:

access_token=access_token

Most V3 API endpoints (with the exception of user-level metrics endpoints) also accept a login and apiKey. We recommend using this method if and only if you will be using the bitly API to shorten links for a single user or site:

login=login&apiKey=apiKey

To get started, you'll need a free bitly user account and apiKey. Signup at: http://bitly.com/a/sign_up

If you already have an account, you can find your apiKey at: http://bitly.com/a/your_api_key

To authenticate with OAuth, you will need to register an OAuth application and then acquire an access_token using either OAuth Web Flow or OAuth XAuth flow, both documented here. You can register an OAuth application by clicking the "Register OAuth Application" button at the bottom of your bitly account settings page.

Note: the bitlyapidemo login and apiKey, and the example OAuth access token used in this document are intended for use as examples only.

Request / Response Formats

All bitly APIs support an optional return format parameter. Note that json is the default response format. but xml is also available. Some endpoints also support a simple txt format.

format=json

All bitly 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 api.bitly.com (see examples).

HTTP Response Status Code is 200 on all valid response in json and xml formats. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid.

For txt format calls, the HTTP Response Status Codes 403, 500 and 503 are used denote rate limiting, a problem with the request format, or an unknown error. The response body will be equivalent to status_txt in json and xml calls for non 200 response codes.

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_URI", "data" : null }
json { "status_code": 500, "status_txt": "MISSING_ARG_LOGIN", "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 bitly 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://api.bitly.com/, since there 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. The latest version of the bitly API (V3) supports CORS requests from any domain.

Here is some basic example Javascript to get you started:

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://api.bitly.com/v3/expand?login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&shortUrl=http://bit.ly/hnB7HI");
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

bitly currently limits API users to no more than five concurrent connections from a single IP address. Also, bitly also institutes per-hour, per-minute, and per-ip rate limits for each API method.

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

Please note that our 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.

To avoid common causes of rate limiting issues, please read our ApiBestPractices.

High-volume users

If you're a high-volume user of the bitly API, please contact us at api@bitly.com to discuss your options.

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

OAuth

bitly currently supports the OAuth 2 draft specification. All OAuth 2 requests MUST use the SSL endpoint available at https://api-ssl.bitly.com/ To register an OAuth application, click the "Register OAuth Application" button at the bottom of your bitly account settings page. You will be sent a registration code to the email address with which you have registered your bitly account.

OAuth 2.0 is a simple and secure authentication mechanism. It allows web applications to acquire an access token for bitly via a quick redirect to the bitly site. Once a web application has an access token, it can access a user’s link metrics, and shorten links using that user’s bitly account. Authentication with OAuth can be accomplished in the following steps:

OAuth Web Flow

Web applications can easily acquire an OAuth access token for a bitly end user by following these steps:

Register your application from within your bitly account settings -- your application will be assigned a client_id and a client_secret. You can start this process by clicking the "Register Oauth Application" button at the bottom of your bitly account settings page.

Redirect the user to https://bitly.com/oauth/authorize, using the client_id and redirect_uri parameters to pass your client ID and the page you would like to redirect to upon acquiring an access token. An example redirect URL looks like: https://bitly.com/oauth/authorize?client_id=...&redirect_uri=http://myexamplewebapp.com/oauth_page

Upon authorizing your application, the user is directed to the page specified in the redirect_uri parameter. We append a “code” parameter to this URI, that contains a value that can be exchanged for an OAuth access token using the oauth/access_token endpoint documented below. For example, if you passed a redirect_uri value of http://myexamplewebapp.com/oauth_page, a successful authentication will redirect the user to http://myexamplewebapp.com/oauth_page?code=....

Use the /oauth/access_token API endpoint documented below to acquire an OAuth access token, passing the “code” value appended by bitly to the previous redirect and the same redirect_uri value that was used previously. This API endpoint will return an OAuth access token, as well as the specified bitly user’s login and API key, allowing your application to utilize the bitly API on that user’s behalf.

OAuth XAuth Flow

For applications where OAuth web flow cannot be used (for example, mobile applications without a browser layer), an OAuth access token can be acquired by making a single call to the /oauth/access_token API endpoint and passing the end-user’s bitly account credentials with the x_auth_username and x_auth_password parameters. Note that the end-user need only enter his/her username and password once for the application to authenticate -- applications using XAuth SHOULD NOT store end-user passwords. Authentication via XAuth must be requested by e-mailing api@bitly.com.

QR Codes

To generate a QR code, simply append .qrcode to the end of any bitly link. For example, the following URL: http://bit.ly/3eI7.qrcode returns a QR code for the bitly link to this page.'

API Key Security

To ensure the absolute security of your API key, we suggest that you always make API calls server-side.

If it is absolutely necessary to call our API from client-side code, please keep in mind that there is no way to positively ensure that your API key will not be discovered. However, certain measures can be taken to mitigate this risk.

One basic security measure that can be taken is to never include your api_key in javascript embedded inline in the page. Keep any references to your api_key in code that is contained in external javascript files which are included in the page.

For an additional level of security, do not include the key itself anywhere in your javascript code, but rather make an ajax call to load it, and keep it in a variable stored in a privately scoped method. See the following code for an example of this method:

<!DOCTYPE html>
<html>

<head>
    <script type="text/javascript" charset="utf-8"
        src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js"></script>
</head>

<body>
    
    <form>
        <input type="button" id="shorten" value="click me" />
    </form>
    
    <script type="text/javascript">
         (function() {
            // store variables in a privately scoped anonymous function
            // initializing them to null because we will be loading them in later
            var api_key = null,
                api_login = null,
                api_url = null;

            // define the method that will be used to do the actual shortening
            // and let it accept a callback method that will be used to process the result from the call to the bitly api
            function shorten(url, callback) {
                // if the call to load the api_key  and api_url has not yet returned, 
                // and the key/url are still null do not try to shorten
                if(!api_key || !api_login || !api_url) { console.log("returning... not yet initialized"); return; } 

                // make sure that the required parameters  are included
                if(!url || !callback) { throw "Attempt to call shorten without a url or a callback function"; }

                // here is where the call to the bitly api would go
                // with the callback method that was passed in used as the success handler
                // for example ( using jquery )
                $.getJSON("http://"+api_url+"/v3/shorten?longUrl="+encodeURIComponent(url)+"&login="+api_login+"&apiKey="+api_key+"&callback=?", callback);

            }


            // make the request to load the details which are stored externally
            // ideally this request goes to an endpoint that only responds to POST requests
            // and does some cross-site request forgery protection
            // http://en.wikipedia.org/wiki/Cross-site_request_forgery
            // this example uses jquery, but it can be replicated using any other js library
            // or just a generic xmlhttprequest (implemented without a library)
            $.ajax({
                url: "api_key_include.js", // << this should return the data
                success: function(data) {
                    api_key     = data.api_key;
                    api_login   = data.api_login;
                    api_url     = data.api_url;
                },
                data: {},
                type: "POST",
                dataType:"json"
            });

             // when the DOM is ready, bind any event handlers that you want to use to have
             $(function() {
                // for example, binding a handler to the click event of an element with the id of shorten
                // that will make a request to shorten the url "http://example.com" and log the api response to the console
                $("#shorten").bind("click", function() { shorten("http://example.com", function(response) { console.log(response); }); })
             });
             
             
         })();
    </script>
    
</body>

</html>

In this scenario, the API key, URL and login would be stored in a file called 'api_key_include.js', which would look like this:

{
  "api_key":"***REPLACE ME WITH YOUR API KEY***", 
  "api_login":"***REPLACE ME WITH YOUR LOGIN***", 
  "api_url":"api.bitly.com"
}

REST API

/v3/shorten

For a long URL, /v3/shorten encodes a URL and returns a short one.

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml, txt.
longUrl is a long URL to be shortened (example: http://betaworks.com/).
domain (optional) refers to a preferred domain; either bit.ly, j.mp, or bitly.com, for users who do NOT have a custom short domain set up with bitly. This affects the output value of url. The default for this parameter is the short domain selected by each user in his/her bitly account settings. Passing a specific domain via this parameter will override the default settings for users who do NOT have a custom short domain set up with bitly. For users who have implemented a custom short domain, bitly will always return short links according to the user's account-level preference.

Notes

Long URLs should be URL-encoded. You can not include a longUrl in the request that has '&', '?', '#', ' ', or other reserved parameters without first encoding it.
Long URLs should not contain spaces: any longUrl 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.
Long 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
The default value for the "domain" parameter is selected by each user from within his/her bitly account settings at http://bitly.com/a/account

Output

new_hash designates if this is the first time this long_url was shortened by this user. The return value will equal 1 the first time a long_url is shortened. It will also then be added to the user history.
url is the actual link that should be used, and is a unique value for the given bitly account.
hash is a bitly identifier for long_url which is unique to the given account.
global_hash is a bitly identifier for long_url which can be used to track aggregate stats across all matching bitly links.
long_url is an echo back of the longUrl request parameter. This may not always be equal to the URL requested. That's 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, authenticated via Oauth https://api-ssl.bitly.com/v3/shorten?access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&longUrl=http%3A%2F%2Fbetaworks.com%2F&format=json

{
    "status_code": 200, 
    "data": {
        "url": "http://bit.ly/cmeH01", 
        "hash": "cmeH01", 
        "global_hash": "1YKMfY", 
        "long_url": "http://betaworks.com/", 
        "new_hash": 0
    }, 
    "status_txt": "OK"
}

json format, authenticated via login/API key https://api-ssl.bitly.com/v3/shorten?login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&longUrl=http%3A%2F%2Fbetaworks.com%2F&format=json

{
    "status_code": 200, 
    "data": {
        "url": "http://bit.ly/cmeH01", 
        "hash": "cmeH01", 
        "global_hash": "1YKMfY", 
        "long_url": "http://betaworks.com/", 
        "new_hash": 0
    }, 
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/shorten?access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&longUrl=http%3A%2F%2Fbetaworks.com%2F&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <status_txt>OK</status_txt>
    <data>
        <url>http://bit.ly/cmeH01</url>
        <hash>cmeH01</hash>
        <global_hash>1YKMfY</global_hash>
        <long_url>http://betaworks.com/</long_url>
        <new_hash>0</new_hash>
    </data>
</response>

txt format https://api-ssl.bitly.com/v3/shorten?access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&longUrl=http%3A%2F%2Fbetaworks.com%2F&format=txt

http://bit.ly/cmeH01

/v3/expand

Given a bitly URL or hash (or multiple), /v3/expand decodes it and returns back the target URL.

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml, txt.
shortUrl refers to one or more bitly URLs, (e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT).
hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name ).

Note

Either shortUrl or hash must be given as a parameter
The maximum number of shortUrl and hash parameters is 15

Output

short_url this is an echo back of the shortUrl request parameter.
hash this is an echo back of the hash request parameter.
user_hash is the corresponding bitly user identifier.
global_hash is the corresponding bitly aggregate identifier.
error indicates there was an error retrieving data for a given shortUrl or hash. An example error is "NOT_FOUND".
long_url is the URL that the requested short_url or hash points to.

Examples

json format https://api-ssl.bitly.com/v3/expand?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&hash=j3&hash=a35.&format=json

{
    "status_code": 200, 
    "data": {
        "expand": [
            {
                "short_url": "http://tcrn.ch/a4MSUH", 
                "global_hash": "bWw49z", 
                "long_url": "http://www.techcrunch.com/2010/01/29/windows-mobile-foursquare/", 
                "user_hash": "a4MSUH"
            }, 
            {
                "short_url": "http://bit.ly/1YKMfY", 
                "global_hash": "1YKMfY", 
                "long_url": "http://betaworks.com/", 
                "user_hash": "1YKMfY"
            }, 
            {
                "long_url": "http://www.scotster.com/qf/?1152", 
                "global_hash": "lLWr", 
                "hash": "j3", 
                "user_hash": "j3"
            }, 
            {
                "hash": "a35.", 
                "error": "NOT_FOUND"
            }
        ]
    }, 
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/expand?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&hash=j3&hash=a35.&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <status_txt>OK</status_txt>
    <data>
        <entry>
            <short_url>http://tcrn.ch/a4MSUH</short_url>
            <long_url>http://www.techcrunch.com/2010/01/29/windows-mobile-foursquare/</long_url>
            <user_hash>a4MSUH</user_hash>
            <global_hash>bWw49z</global_hash>
        </entry>
        <entry>
            <short_url>http://bit.ly/1YKMfY</short_url>
            <long_url>http://betaworks.com/</long_url>
            <user_hash>1YKMfY</user_hash>
            <global_hash>1YKMfY</global_hash>
        </entry>
        <entry>
            <hash>j3</hash>
            <long_url>http://www.scotster.com/qf/?1152</long_url>
            <user_hash>j3</user_hash>
            <global_hash>lLWr</global_hash>
        </entry>
        <entry>
            <error>NOT_FOUND</error>
            <hash>a35.</hash>
        </entry>
    </data>
</response>

json format https://api-ssl.bitly.com/v3/expand?shortUrl=http%3A%2F%2Fbit.ly%2F31IqMl&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=json

{
    "status_code": 200, 
    "data": {
        "expand": [
            {
                "short_url": "http://bit.ly/31IqMl", 
                "global_hash": "31IqMl", 
                "long_url": "http://cnn.com/", 
                "user_hash": "31IqMl"
            }
        ]
    }, 
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/expand?shortUrl=http%3A%2F%2Fbit.ly%2F31IqMl&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <status_txt>OK</status_txt>
    <data>
        <entry>
            <short_url>http://bit.ly/31IqMl</short_url>
            <long_url>http://cnn.com/</long_url>
            <user_hash>31IqMl</user_hash>
            <global_hash>31IqMl</global_hash>
        </entry>
    </data>
</response>

txt format https://api-ssl.bitly.com/v3/expand?shortUrl=http%3A%2F%2Fbit.ly%2F31IqMl&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=txt

http://cnn.com/

/v3/validate

For any given a bitly user login and apiKey, you can validate that the pair is active.

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml, txt.
x_login is the end users user's bitly login (for validation).
x_apiKey is the end users bitly apiKey (for validation).

Output

valid 0 or 1 designating whether the x_login and x_apiKey pair is currently valid.

Examples

json format https://api-ssl.bitly.com/v3/validate?x_login=notbilytapi&x_apiKey=not_apikey&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=json

{
    "status_code": 200, 
    "data": {
        "valid": 0
    }, 
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/validate?x_login=notbilytapi&x_apiKey=not_apikey&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=xml

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

txt format https://api-ssl.bitly.com/v3/validate?x_login=notbilytapi&x_apiKey=not_apikey&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=txt

/v3/clicks

For one or more bitly URL's or hashes, you can generate statistics about the clicks on that link.

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml.
shortUrl refers to one or more bitly URLs, (e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT).
hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name).

Note

Either shortUrl or hash must be given as a parameter
The maximum number of shortUrl and hash parameters is 15

Output

short_url this matches the shortUrl request parameter.
hash this matches the hash request parameter.
user_hash is the corresponding bitly user identifier.
global_hash is the corresponding bitly aggregate identifier.
user_clicks this is the total count of clicks to this user's bitly link.
global_clicks this is the total count of clicks to all bitly links that point to the same same long url.
error indicates there was an error retrieving data for a given shortUrl or hash. An example error is "NOT_FOUND"

Examples

json format https://api-ssl.bitly.com/v3/clicks?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&hash=j3&hash=a35.&format=json

{
    "status_code": 200, 
    "data": {
        "clicks": [
            {
                "short_url": "http://tcrn.ch/a4MSUH", 
                "global_hash": "bWw49z", 
                "user_clicks": 0, 
                "user_hash": "a4MSUH", 
                "global_clicks": 1105
            }, 
            {
                "short_url": "http://bit.ly/1YKMfY", 
                "global_hash": "1YKMfY", 
                "user_clicks": 2218, 
                "user_hash": "1YKMfY", 
                "global_clicks": 2218
            }, 
            {
                "hash": "j3", 
                "global_hash": "lLWr", 
                "user_clicks": 105, 
                "user_hash": "j3", 
                "global_clicks": 106
            }, 
            {
                "hash": "a35.", 
                "error": "NOT_FOUND"
            }
        ]
    }, 
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/clicks?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&hash=j3&hash=a35.&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <data>
        <clicks>
            <short_url>http://tcrn.ch/a4MSUH</short_url>
            <global_hash>bWw49z</global_hash>
            <user_clicks>0</user_clicks>
            <user_hash>a4MSUH</user_hash>
            <global_clicks>1105</global_clicks>
        </clicks>
        <clicks>
            <short_url>http://bit.ly/1YKMfY</short_url>
            <global_hash>1YKMfY</global_hash>
            <user_clicks>2218</user_clicks>
            <user_hash>1YKMfY</user_hash>
            <global_clicks>2218</global_clicks>
        </clicks>
        <clicks>
            <user_clicks>105</user_clicks>
            <global_hash>lLWr</global_hash>
            <hash>j3</hash>
            <user_hash>j3</user_hash>
            <global_clicks>106</global_clicks>
        </clicks>
        <clicks>
            <hash>a35.</hash>
            <error>NOT_FOUND</error>
        </clicks>
    </data>
    <status_txt>OK</status_txt>
</response>

/v3/referrers

Provides a list of referring sites for a specified bitly short link, and the number of clicks per referrer.

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml.
shortUrl refers a bitly URL, (e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT).
hash refers to a bitly hashes, (e.g.: 2bYgqR or a-custom-name).

Note

Either shortUrl or hash must be given as a parameter.
This API endpoint can only provide data for one bitly short link per API call.

Output

short_url this matches the shortUrl request parameter.
hash this matches the hash request parameter.
user_hash is the corresponding bitly user identifier.
global_hash is the corresponding bitly aggregate identifier.
referrer is a referring site for a given bitly link.
referrer_app is a referring application (such as Tweetdeck) for a given bitly link.
url is the URL of a referring application (such as http://tweetdeck.com).
clicks is the number of clicks from the corresponding referrer.

Examples

json format https://api-ssl.bitly.com/v3/referrers?shortUrl=http%3A%2F%2Fbit.ly%2FdjZ9g4&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=json

{
    "data": {
        "created_by": "bitly",
        "global_hash": "djZ9g4",
        "referrers": [
            {
                "clicks": 42,
                "referrer": "direct"
            },
            {
                "clicks": 15,
                "referrer": "http://twitter.com/"
            },
            {
                "clicks": 12,
                "referrer": "http://twitter.com/bitly"
            },
            {
                "clicks": 8,
                "referrer_app": "TweetDeck",
                "url": "http://www.tweetdeck.com/"
            },
            {
                "clicks": 1,
                "referrer": "http://bit.ly/a/sidebar"
            },
            {
                "clicks": 1,
                "referrer": "http://translate.googleusercontent.com/translate_c"
            },
            {
                "clicks": 1,
                "referrer": "http://twitter.com/atul/statuses/26029156685"
            },
            {
                "clicks": 1,
                "referrer": "http://twitter.com/home"
            },
            {
                "clicks": 1,
                "referrer": "http://untiny.me/"
            }
        ],
        "short_url": "http://bit.ly/djZ9g4",
        "user_hash": "djZ9g4"
    },
    "status_code": 200,
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/referrers?shortUrl=http%3A%2F%2Fbit.ly%2FdjZ9g4&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <data>
        <short_url>http://bit.ly/djZ9g4</short_url>
        <global_hash>djZ9g4</global_hash>
        <user_hash>djZ9g4</user_hash>
        <created_by>bitly</created_by>
        <referrers>
            <referrer>direct</referrer>
            <clicks>42</clicks>
        </referrers>
        <referrers>
            <referrer>http://twitter.com/</referrer>
            <clicks>15</clicks>
        </referrers>
        <referrers>
            <referrer>http://twitter.com/bitly</referrer>
            <clicks>12</clicks>
        </referrers>
        <referrers>
            <url>http://www.tweetdeck.com/</url>
            <referrer_app>TweetDeck</referrer_app>
            <clicks>8</clicks>
        </referrers>
        <referrers>
            <referrer>http://bit.ly/a/sidebar</referrer>
            <clicks>1</clicks>
        </referrers>
        <referrers>
            <referrer>http://translate.googleusercontent.com/translate_c</referrer>
            <clicks>1</clicks>
        </referrers>
        <referrers>
            <referrer>http://twitter.com/atul/statuses/26029156685</referrer>
            <clicks>1</clicks>
        </referrers>
        <referrers>
            <referrer>http://twitter.com/home</referrer>
            <clicks>1</clicks>
        </referrers>
        <referrers>
            <referrer>http://untiny.me/</referrer>
            <clicks>1</clicks>
        </referrers>
    </data>
    <status_txt>OK</status_txt>
</response>

/v3/countries

Provides a list of countries from which clicks on a specified bitly short link have originated, and the number of clicks per country.

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml.
shortUrl refers a bitly URL, (e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT).
hash refers to a bitly hashes, (e.g.: 2bYgqR or a-custom-name).

Note

Either shortUrl or hash must be given as a parameter.
This API endpoint can only provide data for one bitly short link per API call.

Output

short_url this matches the shortUrl request parameter.
hash this matches the hash request parameter.
user_hash is the corresponding bitly user identifier.
global_hash is the corresponding bitly aggregate identifier.
countries is a list of countries from which clicks on the bitly short link have originated.
clicks is the number of clicks that have originated from the corresponding country.

Examples

json format https://api-ssl.bitly.com/v3/countries?shortUrl=http%3A%2F%2Fbit.ly%2FdjZ9g4&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=json

{
    "data": {
        "countries": [
            {"clicks": 40, "country": "US"},
            {"clicks": 7,"country": null},
            {"clicks": 4,"country": "AU"},
            {"clicks": 4,"country": "BR"},
            {"clicks": 4,"country": "FR"},
            {"clicks": 3,"country": "CA"},
            {"clicks": 3,"country": "GB"},
            {"clicks": 2,"country": "DE"},
            {"clicks": 2,"country": "IN"},
            {"clicks": 2,"country": "NO"},
            {"clicks": 2,"country": "PL"},
            {"clicks": 2,"country": "TW"},
            {"clicks": 1,"country": "BE"},
            {"clicks": 1,"country": "BG"},
            {"clicks": 1,"country": "ES"},
            {"clicks": 1,"country": "HK"},
            {"clicks": 1,"country": "PH"},
            {"clicks": 1,"country": "PT"},
            {"clicks": 1,"country": "SE"},
            {"clicks": 1,"country": "VE"}
        ],
        "created_by": "bitly",
        "global_hash": "djZ9g4",
        "short_url": "http://bit.ly/djZ9g4",
        "user_hash": "djZ9g4"
    },
    "status_code": 200,
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/countries?shortUrl=http%3A%2F%2Fbit.ly%2FdjZ9g4&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <data>
        <short_url>http://bit.ly/djZ9g4</short_url>
        <global_hash>djZ9g4</global_hash>
        <user_hash>djZ9g4</user_hash>
        <created_by>bitly</created_by>
        <countries><country>US</country><clicks>40</clicks></countries>
        <countries><country/><clicks>7</clicks></countries>
        <countries><country>AU</country><clicks>4</clicks></countries>
        <countries><country>BR</country><clicks>4</clicks></countries>
        <countries><country>FR</country><clicks>4</clicks></countries>
        <countries><country>CA</country><clicks>3</clicks></countries>
        <countries><country>GB</country><clicks>3</clicks></countries>
        <countries><country>DE</country><clicks>2</clicks></countries>
        <countries><country>IN</country><clicks>2</clicks></countries>
        <countries><country>NO</country><clicks>2</clicks></countries>
        <countries><country>PL</country><clicks>2</clicks></countries>
        <countries><country>TW</country><clicks>2</clicks></countries>
        <countries><country>BE</country><clicks>1</clicks></countries>
        <countries><country>BG</country><clicks>1</clicks></countries>
        <countries><country>ES</country><clicks>1</clicks></countries>
        <countries><country>HK</country><clicks>1</clicks></countries>
        <countries><country>PH</country><clicks>1</clicks></countries>
        <countries><country>PT</country><clicks>1</clicks></countries>
        <countries><country>SE</country><clicks>1</clicks></countries>
        <countries><country>VE</country><clicks>1</clicks></countries>
    </data>
    <status_txt>OK</status_txt>
</response>

/v3/clicks_by_minute

For one or more bitly links, provides time series clicks per minute for the last hour in reverse chronological order (most recent to least recent).

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml.
shortUrl refers to one or more bitly URLs, (e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT).
hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name).

Note

Either shortUrl or hash must be given as a parameter
The maximum number of shortUrl and hash parameters is 15

Output

short_url this matches the shortUrl request parameter.
hash this matches the hash request parameter.
user_hash is the corresponding bitly user identifier.
global_hash is the corresponding bitly aggregate identifier.
clicks is the number of clicks received for a given link that minute.

Examples

json format https://api-ssl.bitly.com/v3/clicks_by_minute?shortUrl=http%3A%2F%2Fj.mp%2F9DguyN&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=json

{
    "data": {
        "clicks_by_minute": [
            {
                "clicks": [0,0,0,0,2,2,4,3,1,0,1,0,2,0,0,0,1,1,0,0,2,1,1,3,1,2,1,1,0,1,1,0,1,1,1,0,1,1,1,0,2,3,1,1,3,2,0,3,3,2,2,1,3,3,2,1,0,4,0,2,1],
                "global_hash": "9DguyN",
                "short_url": "http://j.mp/9DguyN",
                "user_hash": "9DguyN"
            }
        ]
    },
    "status_code": 200,
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/clicks_by_minute?shortUrl=http%3A%2F%2Fj.mp%2F9DguyN&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <data>
        <clicks_by_minute>
            <short_url>http://j.mp/9DguyN</short_url>
            <global_hash>9DguyN</global_hash>
            <user_hash>9DguyN</user_hash>
            <clicks>0</clicks>
            <clicks>0</clicks>
            <clicks>0</clicks>
            <clicks>0</clicks>
            <clicks>2</clicks>
            <clicks>2</clicks>
            <clicks>4</clicks>
            <clicks>3</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>2</clicks>
            <clicks>0</clicks>
            <clicks>0</clicks>
            <clicks>0</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>0</clicks>
            <clicks>2</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>3</clicks>
            <clicks>1</clicks>
            <clicks>2</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>2</clicks>
            <clicks>3</clicks>
            <clicks>1</clicks>
            <clicks>1</clicks>
            <clicks>3</clicks>
            <clicks>2</clicks>
            <clicks>0</clicks>
            <clicks>3</clicks>
            <clicks>3</clicks>
            <clicks>2</clicks>
            <clicks>2</clicks>
            <clicks>1</clicks>
            <clicks>3</clicks>
            <clicks>3</clicks>
            <clicks>2</clicks>
            <clicks>1</clicks>
            <clicks>0</clicks>
            <clicks>4</clicks>
            <clicks>0</clicks>
            <clicks>2</clicks>
            <clicks>1</clicks>
        </clicks_by_minute>
    </data>
    <status_txt>OK</status_txt>
</response>

/v3/clicks_by_day

For one or more bitly links, provides time series clicks per day for the last 1-30 days in reverse chronological order (most recent to least recent).

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml.
shortUrl refers to one or more bitly URLs, (e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT).
hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name).
days (optional) specifies the number of days for which to retrieve click data, from 1 to 30 (default 7).

Note

Either shortUrl or hash must be given as a parameter
The maximum number of shortUrl and hash parameters is 15

Output

short_url this matches the shortUrl request parameter.
hash this matches the hash request parameter.
user_hash is the corresponding bitly user identifier.
global_hash is the corresponding bitly aggregate identifier.
clicks is the number of clicks received for a given link that day.
day_start is time code representing the start of the day for which click data is provided.

Examples

json format https://api-ssl.bitly.com/v3/clicks_by_day?access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=json&days=7&hash=grqSlY&hash=dYhyia

{
    "status_code": 200,
    "data": {
        "clicks_by_day": [
            {
                "global_hash": "doWfPZ",
                "hash": "grqSlY",
                "user_hash": "grqSlY",
                "clicks": [
                    {
                        "clicks": 0, 
                        "day_start": 1291093200
                    }, {
                        "clicks": 1,
                        "day_start": 1291006800
                    }, {
                        "clicks": 1, 
                        "day_start": 1290920400
                    }, {
                        "clicks": 0,
                        "day_start": 1290834000
                    }, {
                        "clicks": 6,
                        "day_start": 1290747600
                    }, {
                        "clicks": 0,
                        "day_start": 1290661200
                    }, {
                        "clicks": 0,
                        "day_start": 1290574800
                    }
                ]
            }, {
                "global_hash": "cW0m0h",
                "hash": "dYhyia",
                "user_hash": "dYhyia",
                "clicks": [
                    {
                        "clicks": 0,
                        "day_start": 1291093200
                    }, {
                        "clicks": 0,
                        "day_start": 1291006800
                    }, {
                        "clicks": 0,
                        "day_start": 1290920400
                    }, {
                        "clicks": 0,
                        "day_start": 1290834000
                    }, {
                        "clicks": 0,
                        "day_start": 1290747600
                    }, {
                        "clicks": 0,
                        "day_start": 1290661200
                    }, {
                        "clicks": 0, 
                        "day_start": 1290574800
                    }
                ]
            }
        ]
    },
    "status_txt": "OK"
}

/v3/bitly_pro_domain

This is used to query whether a given short domain is assigned for bitly.Pro, and is consequently a valid shortUrl parameter for other api calls. keep in mind that bitly.pro domains are restricted to less than 15 characters in length.

Parameters

domain A short domain (ie: nyti.ms).
format (optional) indicates the requested response format. supported formats: json (default), xml.

Output

bitly_pro_domain 0 or 1 designating whether this is a current bitly.Pro domain.
domain this is an echo back of the request parameter.

Examples

json format https://api-ssl.bitly.com/v3/bitly_pro_domain?domain=nyti.ms&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=json

{
    "status_code": 200, 
    "data": {
        "domain": "nyti.ms", 
        "bitly_pro_domain": 1
    }, 
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/bitly_pro_domain?domain=nyti.ms&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=xml

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

/v3/lookup

This is used to query for a bitly link based on a long URL. For example you would use /v3/lookup followed by /v3/clicks to find click data when you have a long URL to start with.

Parameters

url One or more long URLs to lookup.
format (optional) indicates the requested response format. supported formats: json (default), xml.

Note

The maximum number of url parameters is 15

Output

url an echo back of the url parameter.
short_url is the corresponding bitly short link.
global_hash is the corresponding bitly aggregate identifier.

Examples

json format https://api-ssl.bitly.com/v3/lookup?url=http%3A%2F%2Fbetaworks.com%2F&url=http%3A%2F%2Fcode.google.com%2Fp%2Fbitly-api%2F&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=json

{
    "data": {
        "lookup": [
            {
                "global_hash": "beta",
                "short_url": "http://bit.ly/beta",
                "url": "http://betaworks.com/"
            },
            {
                "global_hash": "1oDCU",
                "short_url": "http://bit.ly/1oDCU",
                "url": "http://code.google.com/p/bitly-api/"
            }
        ]
    },
    "status_code": 200,
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/lookup?url=http%3A%2F%2Fbetaworks.com%2F&url=http%3A%2F%2Fcode.google.com%2Fp%2Fbitly-api%2F&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <data>
        <lookup>
            <url>http://betaworks.com/</url>
            <short_url>http://bit.ly/beta</short_url>
            <global_hash>beta</global_hash>
        </lookup>
        <lookup>
            <url>http://code.google.com/p/bitly-api/</url>
            <short_url>http://bit.ly/1oDCU</short_url>
            <global_hash>1oDCU</global_hash>
        </lookup>
    </data>
    <status_txt>OK</status_txt>
</response>

json format https://api-ssl.bitly.com/v3/lookup?url=asdf%3A%2F%2Fwww.google.com%2Fnot%2Fa%2Freal%2Flink&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=json

{
    "data": {
        "lookup": [
            {
                "error": "NOT_FOUND",
                "url": "asdf://www.google.com/not/a/real/link"
            }
        ]
    },
    "status_code": 200,
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/lookup?url=asdf%3A%2F%2Fwww.google.com%2Fnot%2Fa%2Freal%2Flink&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <data>
        <lookup>
            <url>asdf://www.google.com/not/a/real/link</url>
            <error>NOT_FOUND</error>
        </lookup>
    </data>
    <status_txt>OK</status_txt>
</response>

/v3/info

This is used to return the page title for a given bitly link.

Parameters

format (optional) indicates the requested response format. supported formats: json (default), xml, txt.
shortUrl refers to one or more bitly URLs, (e.g.: http://bit.ly/1RmnUT or http://j.mp/1RmnUT).
hash refers to one or more bitly hashes, (e.g.: 2bYgqR or a-custom-name ).

Note

Either shortUrl or hash must be given as a parameter
The maximum number of shortUrl and hash parameters is 15

Output

short_url this is an echo back of the shortUrl request parameter.
hash this is an echo back of the hash request parameter.
user_hash is the corresponding bitly user identifier.
global_hash is the corresponding bitly aggregate identifier.
error indicates there was an error retrieving data for a given shortUrl or hash. An example error is "NOT_FOUND".
title is the HTML page title for the destination page (when available).
created_by the bitly username that originally shortened this link.

Examples

json format https://api-ssl.bitly.com/v3/info?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&hash=j3&hash=a.35&format=json

{
    "data": {
        "info": [
            {
                "created_by": "scotster",
                "global_hash": "lLWr",
                "hash": "j3",
                "title": null,
                "user_hash": "j3"
            },
            {
                "error": "NOT_FOUND",
                "hash": "a.35"
            },
            {
                "created_by": "j3h14h",
                "global_hash": "bWw49z",
                "short_url": "http://tcrn.ch/a4MSUH",
                "title": "Windows Mobile Finally Checks Out Foursquare",
                "user_hash": "a4MSUH"
            },
            {
                "created_by": "bitly",
                "global_hash": "1YKMfY",
                "short_url": "http://bit.ly/1YKMfY",
                "title": null,
                "user_hash": "1YKMfY"
            }
        ]
    },
    "status_code": 200,
    "status_txt": "OK"
}

xml format https://api-ssl.bitly.com/v3/info?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&access_token=f356652cf912f5ce51de5b614f1aacfc48fc1da7&hash=j3&hash=a.35&format=xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status_code>200</status_code>
    <data>
        <info>
            <global_hash>lLWr</global_hash>
            <hash>j3</hash>
            <user_hash>j3</user_hash>
            <created_by>scotster</created_by>
            <title/>
        </info>
        <info>
            <hash>a.35</hash>
            <error>NOT_FOUND</error>
        </info>
        <info>
            <short_url>http://tcrn.ch/a4MSUH</short_url>
            <global_hash>bWw49z</global_hash>
            <user_hash>a4MSUH</user_hash>
            <created_by>j3h14h</created_by>
            <title>Windows Mobile Finally Checks Out Foursquare</title>
        </info>
        <info>
            <short_url>http://bit.ly/1YKMfY</short_url>
            <global_hash>1YKMfY</global_hash>
            <user_hash>1YKMfY</user_hash>
            <created_by>bitly</created_by>
            <title/>
        </info>
    </data>
    <status_txt>OK</status_txt>
</response>

/oauth/access_token

This endpoint returns an OAuth access token, and is the 3rd step for Oauth Web Flow and the only step for OAuth XAuth Flow.

Parameters for OAuth Web flow

client_id is your application’s bitly client id.
client_secret is your application’s bitly client secret.
code is the OAuth verification code acquired via OAuth’s web authentication protocol.
redirect_uri is the page to which a user was redirected upon successfully authenticating.

Parameters for OAuth XAuth

client_id is your application’s bitly client id.
client_secret is your application’s bitly client secret.
x_auth_username is the end-user's bitly username for XAuth authentication only.
x_auth_password is the end-user's bitly password for XAuth authentication only..

Note

This request MUST be a HTTP POST request.
This endpoint is only available on https://api-ssl.bitly.com/
The x_auth_username and x_auth_password are only to be used when authentication via web redirect is not possible (for example, mobile applications without a browser layer). Access to these parameters must be requested by e-mailing api@bitly.com.

Output

URL encoded string in the format of access_token=%s&login=%s&apiKey=%s

access_token is the OAuth access token for specified user
login is the end-user’s bitly username
apiKey is the end-user’s bitly API key

/v3/user/clicks

OAuth 2 endpoint that provides the total clicks per day on a user’s bitly links.

Parameters

access_token is the OAuth access token for a bitly user
days (optional) an integer value for the number of days (counting backwards from the current day) from which to retrieve data (min:1, max:30, default:7).
format (optional) indicates the requested response format. Supported formats: json (default), xml.

Note

This endpoint is only available on https://api-ssl.bitly.com/
Results are returned in reverse chronological order (from most recent to least recent)

Output

days is an echo of the "days" parameter
total_clicks is the total number of clicks in the specified time period
clicks the total number of clicks on that day
day_start is time code representing the start of the day for which click data is provided.

Examples

json format https://api-ssl.bitly.com/v3/user/clicks?access_token=BITLY_ASSIGNED_ACCESS_TOKEN&days=7

{
    "status_code": 200, 
    "data": {
        "days": 7, 
        "total_clicks": 29, 
        "clicks": [
            {
                "clicks": 4, 
                "day_start": 1291093200
            }, {
                "clicks": 6, 
                "day_start": 1291006800
            }, {
                "clicks": 1, 
                "day_start": 1290920400
            }, {
                "clicks": 2, 
                "day_start": 1290834000
            }, {
                "clicks": 8,
                "day_start": 1290747600
            }, {
                "clicks": 5,
                "day_start": 1290661200
            }, {
                "clicks": 3,
                "day_start": 1290574800
            }
        ]
    }, 
    "status_txt": "OK"
}

/v3/user/referrers

OAuth 2 endpoint that provides a list of top referrers (up to 500 per day) for a given user’s bitly links, and the number of clicks per referrer.

Parameters

access_token is the OAuth access token for a bitly user,
days (optional) an integer value for the number of days (counting backwards from the current day) from which to retrieve data (min:1, max:30, default:7)
format (optional) indicates the requested response format. Supported formats: json (default), xml.

Note

This endpoint is only available on https://api-ssl.bitly.com/
Results are returned in reverse chronological order (from most recent to least recent).

Output

referrers a list of top referrers (up to 500) for that day.
clicks the number of clicks received from a given referrer for that day.

Examples

json format https://api-ssl.bitly.com/v3/user/referrers?access_token=BITLY_ASSIGNED_ACCESS_TOKEN&days=7

{
    "status_code": 200, 
    "data": {
        "referrers": [
            [
                {
                    "referrer": "direct",
                    "clicks": 3
                }, {
                    "referrer": "http://www.facebook.com/l.php",
                    "clicks": 1
                }
            ], [
                {
                    "referrer": "direct",
                    "clicks": 5
                }, {
                    "referrer": "http://twitter.com/",
                    "clicks": 1
                }
            ], [
                {
                    "referrer": "direct",
                    "clicks": 1
                }
            ], [
                {
                    "referrer": "http://twitter.com/",
                    "clicks": 1
                }, {
                    "referrer": "http://twitter.com/falicon",
                    "clicks": 1
                }
            ], [
                {
                    "referrer": "http://twitter.com/",
                    "clicks": 4
                }, {
                    "referrer": "direct",
                    "clicks": 3
                }, {
                    "referrer": "http://hootsuite.com/dashboard",
                    "clicks": 1
                }
            ], [
                {
                    "referrer": "direct",
                    "clicks": 4
                }, {
                    "referrer": "http://www.facebook.com/l.php",
                    "clicks": 1
                }
            ], [
                {
                    "referrer": "http://twitter.com/falicon",
                    "clicks": 2
                }, {
                    "referrer": "direct",
                    "clicks": 1
                }
            ]
        ],
        "days": 7
    }, 
    "status_txt": "OK"
}

/v3/user/countries

OAuth 2 endpoint that provides a list of countries from which clicks on a given user’s bitly links are originating, and the number of clicks per country.

Parameters

access_token is the OAuth access token for a bitly user.
days (optional) an integer value for the number of days (counting backwards from the current day) from which to retrieve data (min:1, max:30, default:7).
format (optional) indicates the requested response format. supported formats: json (default), xml.

Note

This endpoint is only available on https://api-ssl.bitly.com/
Results are returned in reverse chronological order (from most recent to least recent).

Output

countries a list of countries from which clicks on the specified bitly user’s links are originating.
clicks the number of clicks originating from a given country.

Examples

json format https://api-ssl.bitly.com/v3/user/countries?access_token=BITLY_ASSIGNED_ACCESS_TOKEN&days=7

{
    "status_code": 200, 
    "data": {
        "days": 7,
        "countries": [
            [
                {
                    "country": "US",
                    "clicks": 4
                }
            ], [
                {
                    "country": "US",
                    "clicks": 5
                }, {
                    "country": "unknown",
                    "clicks": 1
                }
            ], [
                {
                    "country": "unknown",
                    "clicks": 1
                }
            ], [
                {
                    "country": "US",
                    "clicks": 2
                }
            ], [
                {
                    "country": "US",
                    "clicks": 5
                }, {
                    "country": "IN",
                    "clicks": 1
                }, {
                    "country": "FR",
                    "clicks": 1
                }, {
                    "country": "CA",
                    "clicks": 1
                }
            ], [
                {
                    "country": "US",
                    "clicks": 5
                }
            ], [
                {
                    "country": "CA",
                    "clicks": 2
                }, {
                    "country": "US",
                    "clicks": 1
                }
            ]
        ]
    },
    "status_txt": "OK"
}

/v3/user/realtime_links

OAuth 2 endpoint that provides a given user’s 100 most popular links based on click traffic in the past hour, and the number of clicks per link.

Parameters

access_token is the OAuth access token for a bitly user
format (optional) indicates the requested response format. supported formats: json (default), xml.

Note

This endpoint is only available on https://api-ssl.bitly.com/
This endpoint returns a maximum of 100 results.

Output

clicks is the number of clicks within the past hour.
user_hash is the corresponding bitly user link identifier.

Examples

json format https://api-ssl.bitly.com/v3/user/realtime_links?format=json&access_token=BITLY_ASSIGNED_ACCESS_TOKEN

{
    "status_code": 200,
    "data": {
        "realtime_links": [
            {
                "clicks": 15,
                "user_hash": "i7JWw0"
            }, {
                "clicks": 1,
                "user_hash": "eiRiMo"
            }
        ]
    },
    "status_txt": "OK"
}

Discussion

We invite you to visit our Google Group to discuss technical issues related to using the bitly API:

http://groups.google.com/group/bitly-api

To report an error with a request or response please submit an issue:

http://code.google.com/p/bitly-api/issues/list

Revision History

Date	Change
2011-Nov-29	added OAuth support to all v3 endpoints
2011-Jun-15	updated behavior of "domain" parameter for /v3/shorten
2011-Mar-09	removed /v3/authenticate endpoint
2011-Feb-16	migrated endpoints to api.bitly.com
2010-Dec-15	added CORS support
2010-Oct-12	added /v3/clicks_by_day
2010-Oct-7	added QR Code support
2010-Sep-15	added OAuth2 support, /v3/referrers, /v3/countries, /v3/clicks_by_minute, /v3/user/realtime_links, /v3/user/clicks /v3/user/countries /v3/user/referrers
2010-Jun-28	added /v3/info
2010-Jun-4	added /v3/lookup and /v3/authenticate
2010-Mar-30	Initial v3 documentation