|
ApiDocumentation
bitly REST API method documentation
Featured bitly API Documentationbitly 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 StartedHere are the topics covered in the bitly REST API documentation. Also, see our ApiBestPractices Sections
Authentication and Shared ParametersAll 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 FormatsAll 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
Here are some examples:
<?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 Limitingbitly 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 usersIf 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. OAuthbitly 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 FlowWeb applications can easily acquire an OAuth access token for a bitly end user by following these steps:
OAuth XAuth FlowFor 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 CodesTo 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 SecurityTo 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/shortenFor a long URL, /v3/shorten encodes a URL and returns a short one. Parameters
Output
Examples
{
"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"
}
{
"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 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>
http://bit.ly/cmeH01 /v3/expandGiven a bitly URL or hash (or multiple), /v3/expand decodes it and returns back the target URL. Parameters
Note
Output
Examples
{
"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 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>{
"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 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>
http://cnn.com/ /v3/validateFor any given a bitly user login and apiKey, you can validate that the pair is active. Parameters
Output
Examples
{
"status_code": 200,
"data": {
"valid": 0
},
"status_txt": "OK"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<status_code>200</status_code>
<status_txt>OK</status_txt>
<data>
<valid>0</valid>
</data>
</response>
0 /v3/clicksFor one or more bitly URL's or hashes, you can generate statistics about the clicks on that link. Parameters
Note
Output
Examples
{
"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 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/referrersProvides a list of referring sites for a specified bitly short link, and the number of clicks per referrer. Parameters
Note
Output
Examples
{
"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 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/countriesProvides a list of countries from which clicks on a specified bitly short link have originated, and the number of clicks per country. Parameters
Note
Output
Examples
{
"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 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_minuteFor 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
Note
Output
Examples
{
"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 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_dayFor 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
Note
Output
Examples
{
"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_domainThis 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
Output
Examples
{
"status_code": 200,
"data": {
"domain": "nyti.ms",
"bitly_pro_domain": 1
},
"status_txt": "OK"
}
<?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/lookupThis 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
Note
Output
Examples
{
"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 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>
{
"data": {
"lookup": [
{
"error": "NOT_FOUND",
"url": "asdf://www.google.com/not/a/real/link"
}
]
},
"status_code": 200,
"status_txt": "OK"
}
<?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/infoThis is used to return the page title for a given bitly link. Parameters
Note
Output
Examples
{
"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 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_tokenThis 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
Parameters for OAuth XAuth
Output URL encoded string in the format of access_token=%s&login=%s&apiKey=%s
/v3/user/clicksOAuth 2 endpoint that provides the total clicks per day on a user’s bitly links. Parameters
Note
Output
Examples
{
"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/referrersOAuth 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
Note
Output
Examples
{
"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/countriesOAuth 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
Note
Output
Examples
{
"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_linksOAuth 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
Note
Output
Examples
{
"status_code": 200,
"data": {
"realtime_links": [
{
"clicks": 15,
"user_hash": "i7JWw0"
}, {
"clicks": 1,
"user_hash": "eiRiMo"
}
]
},
"status_txt": "OK"
}DiscussionWe 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
| ||||||||||||||||||||||||