/v3/link/clicks

Returns the number of clicks on a single bitly link.

Authentication: oauth2

Parameters

link - a bitly link.
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.

Return Values

link_clicks - the number of clicks on the specified bitly link.
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"
}

/v3/link/countries

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

Authentication: oauth2

Parameters

link - a bitly link.
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

Returns users who have encoded this link (optionally only those in the requesting user's social graph).

Note: Some users may not be returned from this call depending on link privacy settings.

Parameters

link - a bitly link.
my_network (optional) true or false - restrict to my network.
limit - (optional) integer in the range of 1 to 25 that specifies the number of records to return (default: 10).
expand_user (optional) true or false - include display names of encoders.

Return Values

aggregate_link - the aggregate (global) bitly link for the provided bitly link.
entries - a mapping of link, user, and ts (when the link was created).

Example Request

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

Example Response

{
  "data": {
    "aggregate_link": "http://bit.ly/900913",
    "entries": [
      {
        "link": "http://bit.ly/a5YvlH",
        "ts": 1265002617,
        "user": "mang0"
      },
      {
        "link": "http://bit.ly/97CuIj",
        "ts": 1265018066,
        "user": "ogakiyaku"
      }
    ]
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/link/encoders_count

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

Parameters

link - a bitly link.

Return Values

aggregate_link - the aggregate (global) bitly link for the provided bitly link.
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/referrers

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

Authentication: oauth2

Parameters

link - a bitly link.
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 bitly link, grouped by referring domain.

Authentication: oauth2

Parameters

link - a bitly link.
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 bitly link.

Authentication: oauth2

Parameters

link - a bitly link.
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"
}

/v3/link/shares

Returns metrics about a shares of a single link.

Authentication: oauth2

Parameters

link - a bitly link
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.

Return Values

shares - the number of shares for the specified bitly link, by the type of share (twitter, email, facebook).
total_shares - the total number of shares for the specified bitly link.
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.

Link Metrics

/v3/link/clicks

Parameters

Return Values

Example Requests

/v3/link/countries

Parameters

Return Values

Example Request

Example Response

/v3/link/encoders

Parameters

Return Values

Example Request

Example Response

/v3/link/encoders_count

Parameters

Return Values

Example Request

Example Response

/v3/link/referrers

Parameters

Return Values

Example Request

Example Response

/v3/link/referrers_by_domain

Parameters

Return Values

Example Request

Example Response

/v3/link/referring_domains

Parameters

Return Values

Example Request

Example Response

/v3/link/shares

Parameters

Return Values