bitly Data APIs
Here at bitly, we see about 4 billion clicks a month, and millions of new links a day. We love looking through this enormous set of data to find interesting stuff -- and we're extremely excited to open up some of the system-wide data endpoints we use, for you to build cool things too!
/v3/highvalue
Returns a specified number of "high-value" bitly links that are popular across bitly at this particular moment.
Authentication: oauth2
Parameters
- limit - the maximum number of high-value links to return.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/highvalue?access_token=ACCESS_TOKEN&limit=2
Example Response
{
"data": {
"params": {
"lang": "en",
"limit": 2
},
"values": [
"http://bit.ly/Shd5nT",
"http://bit.ly/VJqu9q"
]
},
"status_code": 200,
"status_txt": "OK"
}
/v3/search
Search links receiving clicks across bitly by content, language, location, and more.
Authentication: oauth2
Parameters
- limit - the maximum number of links to return.
- offset - which result to start with (defaults to 0).
- query - string to query for.
- lang - favor results in this language (two letter ISO code).
- cities - show links active in this city (ordered like country-state-city, e.g. us-il-chicago).
- domain - restrict results to this web domain.
- fields - which fields to return in the response (comma-separated). May be any of: domain, initial_epoch, h2, h3, site, lastindexed, keywords, last_indexed_epoch, title, initial, summaryText, content, score, summaryTitle, type, description, cities, lang, url, referrer, aggregate_link, lastseen, page, ogtitle, aggregate_link. By default, all will be returned.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/search?access_token=ACCESS_TOKEN&query=obama&domain=nytimes.com&limit=2&fields=aggregate_link%2Ctitle%2Curl
Example Response
{
"data": {
"results": [
{
"aggregate_link": "http://bit.ly/T21fuJ",
"title": "Debt Reckoning: The Fiscal Deadline in Washington - NYTimes.com",
"url": "http://www.nytimes.com/interactive/us/politics/debt-reckoning.html"
},
{
"aggregate_link": "http://bit.ly/WhGQTe",
"title": "Sunday Coverage of School Shooting Aftermath - NYTimes.com",
"url": "http://thelede.blogs.nytimes.com/2012/12/16/sunday-coverage-of-newtown-school-shooting/"
}
]
},
"status_code": 200,
"status_txt": "OK"
}
/v3/realtime/bursting_phrases
Returns phrases that are receiving an uncharacteristically high volume of click traffic, and the individual links (hashes) driving traffic to pages containing these phrases.
Authentication: oauth2
Example Request
API Address: https://api-ssl.bitly.com GET /v3/realtime/bursting_phrases?access_token=ACCESS_TOKEN
Example Response
{
"data": {
"current_lag": 4,
"phrases": [
{
"N": 644933,
"ghashes": [
{
"ghash": "1534dqE",
"visitors": 214
},
{
"ghash": "123Tzxi",
"visitors": 77
},
{
"ghash": "YwtqHA",
"visitors": 53
},
{
"ghash": "171mi59",
"visitors": 52
},
{
"ghash": "10VIMDX",
"visitors": 45
}
],
"mean": 0.17000000000000001,
"phrase": "north korea",
"rate": 0.29999999999999999,
"std": 0.041785272667362532,
"urls": [
{
"aggregate_url": "http://bit.ly/1534dqE",
"visitors": 214
},
{
"aggregate_url": "http://bit.ly/123Tzxi",
"visitors": 77
},
{
"aggregate_url": "http://bit.ly/YwtqHA",
"visitors": 53
},
{
"aggregate_url": "http://bit.ly/171mi59",
"visitors": 52
},
{
"aggregate_url": "http://bit.ly/10VIMDX",
"visitors": 45
}
]
},
{
"N": 4026,
"ghashes": [
{
"ghash": "123InRj",
"visitors": 266
},
{
"ghash": "12VnuGK",
"visitors": 180
},
{
"ghash": "10QUZsc",
"visitors": 38
},
{
"ghash": "171cUOS",
"visitors": 10
},
{
"ghash": "17vqEEC",
"visitors": 8
}
],
"mean": 0.01,
"phrase": "jackie robinson",
"rate": 0.16,
"std": 0.0042133518459201253,
"urls": [
{
"aggregate_url": "http://bit.ly/123InRj",
"visitors": 266
},
{
"aggregate_url": "http://bit.ly/12VnuGK",
"visitors": 180
},
{
"aggregate_url": "http://bit.ly/10QUZsc",
"visitors": 38
},
{
"aggregate_url": "http://bit.ly/171cUOS",
"visitors": 10
}
]
}
],
"selectivity": 3,
"time": 1365800585
},
"status_code": 200,
"status_txt": "OK"
}
/v3/realtime/hot_phrases
Returns phrases that are receiving a consistently high volume of click traffic, and the individual links (hashes) driving traffic to pages containing these phrases.
Authentication: oauth2
Example Request
API Address: https://api-ssl.bitly.com GET /v3/realtime/hot_phrases?access_token=ACCESS_TOKEN
Example Response
{
"data": {
"current_lag": 4,
"phrases": [
{
"ghashes": [
{
"ghash": "QSQsPh",
"visitors": 998
},
{
"ghash": "ScRWYS",
"visitors": 266
},
{
"ghash": "ScHTDa",
"visitors": 194
},
{
"ghash": "QSxSab",
"visitors": 131
},
{
"ghash": "NW3HC7",
"visitors": 101
},
{
"ghash": "P9c0rD",
"visitors": 47
},
{
"ghash": "SbjnSG",
"visitors": 26
},
{
"ghash": "QghCiw",
"visitors": 23
},
{
"ghash": "Rvip6f",
"visitors": 22
},
{
"ghash": "Sb02kE",
"visitors": 21
},
{
"ghash": "NWxRS6",
"visitors": 18
},
{
"ghash": "NbDukJ",
"visitors": 17
},
{
"ghash": "OGqPAx",
"visitors": 17
}
],
"phrase": "top gun",
"rate": 1.0414969999999999
},
{
"ghashes": [
{
"ghash": "PyyGlF",
"visitors": 914
},
{
"ghash": "SIDJ3h",
"visitors": 209
},
{
"ghash": "OQQbkR",
"visitors": 35
},
{
"ghash": "NBn40C",
"visitors": 29
},
{
"ghash": "SIv7K3",
"visitors": 29
},
{
"ghash": "QhQMGI",
"visitors": 21
}
],
"phrase": "iphone 5",
"rate": 0.76665669999999997
}
],
"time": 1345477932.46945
},
"status_code": 200,
"status_txt": "OK"
}
/v3/realtime/clickrate
Returns the click rate for content containing a specified phrase.
Authentication: oauth2
Parameters
- phrase - the phrase for which you'd like to get the click rate.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/realtime/clickrate?access_token=ACCESS_TOKEN&phrase=obama
Example Response
{
"data": {
"ghash": null,
"lag": 4,
"phrase": "obama",
"rate": 1.123823,
"time": 1342623038
},
"status_code": 200,
"status_txt": "OK"
}
/v3/link/info
Returns metadata about a single bitly link.
Authentication: oauth2
Parameters
- link - a bitly link.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/link/info?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2FMwSGaQ
Example Response
{
"data": {
"canonical_url": "http://blog.bitly.com/post/26449494972/happy-independence-day-america",
"category": "text",
"content_length": 19582,
"content_type": "text/html; charset=UTF-8",
"domain": "blog.bitly.com",
"favicon_url": "http://bitly.com/s/beta/graphics/vis/bitly-favicon-trans.png",
"global_hash": "LNY08h",
"html_title": "bitly blog - Happy Independence Day, America!",
"http_code": 200,
"indexed": 1341355564,
"linktags_other": [
[
"icon",
"http://bitly.com/s/beta/graphics/vis/bitly-favicon-trans.png"
],
[
"alternate",
"http://blog.bitly.com/rss"
]
],
"metatags_name": [
[
"color:background",
"#666"
],
[
"color:content background",
"#fff"
],
[
"color:header background",
"#fff"
],
[
"color:title",
"#555555"
],
[
"color:description",
"#fff"
],
[
"color:date",
"#666"
],
[
"color:permalinks",
"#4AADF0"
],
[
"color:post title",
"#222"
],
[
"color:text",
"#222"
],
[
"color:inline link",
"#ff9900"
],
[
"color:quote",
"#333"
],
[
"color:quote source",
"#666"
],
[
"color:link post",
"#ff9900"
],
[
"color:conversation background 1",
"#f4f4f4"
],
[
"color:conversation background 2",
"#e8e8e8"
],
[
"color:conversation border",
"#ccc"
],
[
"color:conversation text",
"#000"
],
[
"color:photo background",
"#ccc"
],
[
"color:video background",
"#eee"
],
[
"viewport",
"width=675"
]
],
"original_url": "http://blog.bitly.com/post/26449494972/happy-independence-day-america",
"robots_allowed": true,
"source_domain": "blog.bitly.com",
"url": "http://blog.bitly.com/post/26449494972/happy-independence-day-america",
"url_fetched": "http://blog.bitly.com/post/26449494972/happy-independence-day-america"
},
"status_code": 200,
"status_txt": "OK"
}
/v3/link/content
Returns the “main article” from the linked page, as determined by the content extractor, in either HTML or plain text format.
Authentication: oauth2
Parameters
- link - a bitly link.
- content_type (optional) - specifies whether to return the content as html or plain text (default: html).
Example Request
API Address: https://api-ssl.bitly.com GET /v3/link/content?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2FMwSGaQ
Example Response
{
"data": {
"content": "<div class=\"regular\">\r\n <h2>\r\n<a href=\"http://blog.bitly.com/post/26449494972/ ....",
"content_type": "html"
},
"status_code": 200,
"status_txt": "OK"
}
/v3/link/category
Returns the detected categories for a document, in descending order of confidence.
Authentication: oauth2
Parameters
- link - a bitly link.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/link/category?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2F1234
Example Response
{
"data": {
"categories": [
"Social Media",
"Advertising",
"Software and Internet",
"Technology",
"Business"
]
},
"status_code": 200,
"status_txt": "OK"
}
/v3/link/social
Returns the "social score" for a specified bitly link. Note that the social score are highly dependent upon activity (clicks) occurring on the bitly link. If there have not been clicks on a bitly link within the last 24 hours, it is possible a social score for that link does not exist.
Authentication: oauth2
Parameters
- link - a bitly link.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/link/social?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2FMwSGaQ
Example Response
{
"data": {
"social_scores": {
"http://bit.ly/MwSGaQ": "76"
}
},
"status_code": 200,
"status_txt": "OK"
}
/v3/link/location
Returns the significant locations for the bitly link or None if locations do not exist. Note that locations are highly dependent upon activity (clicks) occurring on the bitly link. If there have not been clicks on a bitly link within the last 24 hours, it is possible that location data for that link does not exist.
Authentication: oauth2
Parameters
- link - a bitly link.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/link/location?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2FMZGoYV
Example Response
{
"data": {
"locations": [
"us-ny-new york",
"us-ny-brooklyn"
]
},
"status_code": 200,
"status_txt": "OK"
}
/v3/link/language
Returns the significant languages for the bitly link. Note that languages are highly dependent upon activity (clicks) occurring on the bitly link. If there have not been clicks on a bitly link within the last 24 hours, it is possible that language data for that link does not exist.
Authentication: oauth2
Parameters
- link - a bitly link.
Example Request
API Address: https://api-ssl.bitly.com GET /v3/link/language?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2FMwSGaQ
Example Response
{
"data": {
"languages": {
"http://bit.ly/MwSGaQ": "en"
}
},
"status_code": 200,
"status_txt": "OK"
}