Link Metrics

/v3/link/clicks
/v3/link/countries
/v3/link/encoders_count
/v3/link/keyword_clicks_by_destination
/v3/link/referrers
/v3/link/referrers_by_domain
/v3/link/referring_domains

/v3/link/clicks

Returns the number of clicks on a single Bitlink.

Authentication: oauth2

Parameters

link - a Bitlink.
unit - minute, hour, day, week or month, default: day
Note: when unit is minute the maximum value for units is 60.
units - an integer representing the time units to query data for. Pass -1 to return all units of time.
timezone - an integer hour offset from UTC (-14 to 14), or a timezone string default: America/New_York.
rollup - true or false. Return data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit - 1 to 1000 (default=100).
unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics, default: now.
Note: the value of unit_reference_ts rounds to the nearest unit.
Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.
format - json, xml, txt. Default: json.
Note: txt format only available with rollup=true.

Return Values

link_clicks - the number of clicks on the specified Bitlink.
tz_offset - the offset for the specified timezone, in hours.
unit - an echo of the specified unit value.
units - an echo of the specified units value.
unit_reference_ts - an echo of the specified unit_reference_ts value.

Example Requests

API Address: https://api-ssl.bitly.com
GET /v3/link/clicks?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2F1234

{
  "data": {
    "link_clicks": 9139, 
    "tz_offset": -5, 
    "unit": "day", 
    "unit_reference_ts": 1360351157, 
    "units": -1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

With rollup=false

API Address: https://api-ssl.bitly.com
GET /v3/link/clicks?units=5&access_token=ACCESS_TOKEN&rollup=false&link=http%3A%2F%2Fbit.ly%2F1234

{
  "data": {
    "link_clicks": [
      {
        "clicks": 1, 
        "dt": 1360299600
      }, 
      {
        "clicks": 2, 
        "dt": 1360213200
      }, 
      {
        "clicks": 2, 
        "dt": 1360126800
      }, 
      {
        "clicks": 3, 
        "dt": 1360040400
      }, 
      {
        "clicks": 10, 
        "dt": 1359954000
      }
    ], 
    "tz_offset": -5, 
    "unit": "day", 
    "unit_reference_ts": 1360351157, 
    "units": 5
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

With format=txt

API Address: https://api-ssl.bitly.com
GET /v3/link/clicks?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2F1234&format=txt

/v3/link/countries

Returns metrics about the countries referring click traffic to a single Bitlink.

Authentication: oauth2

Parameters

link - a Bitlink.
unit - minute | hour | day | week | month default:day
Note: when unit is minute the maximum value for units is 60
units = an integer representing the time units to query data for. pass -1 to return all units of time.
timezone - an integer hour offset from UTC (-14..14), or a timezone string default:America/New_York.
limit=1..1000 (default=100)
unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics. default:now
Note: the value of unit_reference_ts rounds to the nearest unit.
Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.

Return Values

tz_offset - the offset for the specified timezone, in hours.
unit - an echo of the specified unit value.
units - an echo of the specified units value.
countries - a list of countries referring traffic to this link. Each country returns the following fields:
- clicks - the number of clicks referred from this country.
- country - the two-letter code of the referring country.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/link/countries?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2F1234

Example Response

{
  "data": {
    "countries": [
      {
        "clicks": 517, 
        "country": "US"
      }, 
      {
        "clicks": 165, 
        "country": "None"
      }, 
      {
        "clicks": 141, 
        "country": "JP"
      }, 
      {
        "clicks": 84, 
        "country": "DE"
      }, 
      {
        "clicks": 84, 
        "country": "GB"
      }
    ], 
    "tz_offset": -5, 
    "unit": "day", 
    "units": -1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/link/encoders_count

Returns the number of users who have shortened (encoded) a single Bitlink.

Parameters

link - a Bitlink.

Return Values

aggregate_link - the aggregate (global) Bitlink for the provided Bitlink.
count - the number of bitly users who have shortened (encoded) this link.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/link/encoders_count?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2Fze6poY

Example Response

{
  "data": {
    "aggregate_link": "http://bitly.com/900913", 
    "count": 3490
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/link/keyword_clicks_by_destination

Returns past destination urls for a keyword with the clicks per destination.

Authentication: oauth2

Parameters

link - a Bitlink.
unit - minute | hour | day | week | month default:day
Note: when unit is minute the maximum value for units is 60
units = an integer representing the time units to query data for. pass -1 to return all units of time.
timezone - an integer hour offset from UTC (-14..14), or a timezone string default:America/New_York.
limit=1..1000 (default=100)
unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics. default:now
Note: the value of unit_reference_ts rounds to the nearest unit.
Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.

Return Values

tz_offset - the offset for the specified timezone, in hours.
unit - an echo of the specified unit value.
units - an echo of the specified units value.
keyword_destinations - a list of past destination urls for the custom keyword
- clicks - the number of clicks on the custom bitlink while it pointed to this destination
- domain - the domain for the bitlink associated with this destination url
- user_hash - the user hash for this destination url
- long_url - the complete destination url

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/link/keyword_clicks_by_destination?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2Fchauncey

Example Response

{
  "data": {
    "keyword_destinations": [
      {
        "clicks": 13, 
        "domain": "bitly.qa", 
        "long_url": "https://mail.google.com/mail/u/0/#inbox", 
        "user_hash": "Gzmb6Y"
      }, 
      {
        "clicks": 4, 
        "domain": "bitly.qa", 
        "long_url": "https://jenkins.bitly.net/job/pull-requests/61529/testReport/infrastructure.tests/test_sh/tests_test_sh/", 
        "user_hash": "Gzmb8Q"
      }, 
      {
        "clicks": 1, 
        "domain": "bitly.qa", 
        "long_url": "https://deploy.bitly.net/servers/queuereader_metrics.dc4", 
        "user_hash": "Gzmb5C"
      }
    ], 
    "tz_offset": -4, 
    "unit": "hour", 
    "unit_reference_ts": null, 
    "units": -1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/link/referrers

Returns metrics about the pages referring click traffic to a single Bitlink.

Authentication: oauth2

Parameters

link - a Bitlink.
unit - minute | hour | day | week | month default:day
Note: when unit is minute the maximum value for units is 60
units = an integer representing the time units to query data for. pass -1 to return all units of time.
timezone - an integer hour offset from UTC (-14..14), or a timezone string default:America/New_York.
limit=1..1000 (default=100)
unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics. default:now
Note: the value of unit_reference_ts rounds to the nearest unit.
Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.

Return Values

tz_offset - the offset for the specified timezone, in hours.
unit - an echo of the specified unit value.
units - an echo of the specified units value.
referrers - a list of URLs referring traffic to this link. Each URL returns the following fields:
- clicks - the number of clicks referred from this URL.
- referrer - the URL referring clicks.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/link/referrers?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2F1234

Example Response

{
  "data": {
    "referrers": [
      {
        "clicks": 1129, 
        "referrer": "direct"
      }, 
      {
        "clicks": 55, 
        "referrer": "http://news.ycombinator.com/item"
      }, 
      {
        "clicks": 41, 
        "referrer": "http://twitter.com/"
      }, 
      {
        "clicks": 25, 
        "referrer": "yxG0tQXMY40="
      }, 
      {
        "clicks": 24, 
        "referrer": "http://localhost/www/2ii.jp/ii.php"
      }
    ], 
    "tz_offset": -5, 
    "unit": "day", 
    "units": -1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/link/referrers_by_domain

Returns metrics about the pages referring click traffic to a single Bitlink, grouped by referring domain.

Authentication: oauth2

Parameters

link - a Bitlink.
unit - minute | hour | day | week | month default:day
Note: when unit is minute the maximum value for units is 60
units = an integer representing the time units to query data for. pass -1 to return all units of time.
timezone - an integer hour offset from UTC (-14..14), or a timezone string default:America/New_York.
limit=1..1000 (default=100)
unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics. default:now
Note: the value of unit_reference_ts rounds to the nearest unit.
Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.

Return Values

tz_offset - the offset for the specified timezone, in hours.
unit - an echo of the specified unit value.
units - an echo of the specified units value.
referrers - a mapping from referring domain to a list of URLs referring traffic to this link. Each URL returns the following fields:
- clicks - the number of clicks referred from this URL.
- referrer - the URL referring clicks.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/link/referrers_by_domain?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2F1234

Example Response

{
  "data": {
    "referrers": {
      "Twitter": [
        {
          "clicks": 41, 
          "referrer": "http://twitter.com/"
        }, 
        {
          "clicks": 4, 
          "referrer": "http://t.co/123"
        }
      ], 
      "direct": [
        {
          "clicks": 1129, 
          "referrer": "direct"
        }
      ], 
      "localhost": [
        {
          "clicks": 24, 
          "referrer": "http://localhost/www/2ii.jp/ii.php"
        }
      ], 
      "news.ycombinator.com": [
        {
          "clicks": 55, 
          "referrer": "http://news.ycombinator.com/item"
        }
      ], 
      "yxG0tQXMY40=": [
        {
          "clicks": 25, 
          "referrer": "yxG0tQXMY40="
        }
      ]
    }, 
    "tz_offset": -5, 
    "unit": "day", 
    "units": -1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/link/referring_domains

Returns metrics about the domains referring click traffic to a single Bitlink.

Authentication: oauth2

Parameters

link - a Bitlink.
unit - minute | hour | day | week | month default:day
Note: when unit is minute the maximum value for units is 60
units = an integer representing the time units to query data for. pass -1 to return all units of time.
timezone - an integer hour offset from UTC (-14..14), or a timezone string default:America/New_York.
limit=1..1000 (default=100)
unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics. default:now
Note: the value of unit_reference_ts rounds to the nearest unit.
Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.

Return Values

tz_offset - the offset for the specified timezone, in hours.
unit - an echo of the specified unit value.
units - an echo of the specified units value.
referring_domains - a list of domains referring traffic to this link. Each domain returns the following fields:
- clicks - the number of clicks referred from this domain.
- domain - the domain referring clicks.
- url - the complete URL of the domain referring clicks.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/link/referring_domains?access_token=ACCESS_TOKEN&link=http%3A%2F%2Fbit.ly%2F1234

Example Response

{
  "data": {
    "referring_domains": [
      {
        "clicks": 1129, 
        "domain": "direct"
      }, 
      {
        "clicks": 72, 
        "domain": "twitter.com", 
        "url": "http://twitter.com/"
      }, 
      {
        "clicks": 56, 
        "domain": "news.ycombinator.com", 
        "url": "http://news.ycombinator.com/"
      }, 
      {
        "clicks": 26, 
        "domain": "www.facebook.com", 
        "url": "http://www.facebook.com/"
      }
    ], 
    "tz_offset": -5, 
    "unit": "day", 
    "units": -1
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}