User Metrics

/v3/user/clicks
/v3/user/countries
/v3/user/popular_links
/v3/user/referrers
/v3/user/referring_domains
/v3/user/share_counts
/v3/user/share_counts_by_share_type
/v3/user/shorten_counts

/v3/user/clicks

Returns the aggregate number of clicks on all of the authenticated user's bitly links.

Authentication: oauth2

Parameters

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.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7.

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.
days - the number of days for which data is provided (ONLY returned if unit is not specified).
user_clicks - the number of clicks on this user's links. If rollup = false, the following values are returned for each specified unit:
- dt: a unix timestamp representing the beginning of this unit.
- day_start: a unix timestamp representing the beginning of the specified day (ONLY returned if unit is not specified).
- clicks: the number of clicks on this user's links in the specified timeframe.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/clicks?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "clicks": [
      {
        "clicks": 3,
        "day_start": 1331784000
      },
      {
        "clicks": 129,
        "day_start": 1331697600
      },
      {
        "clicks": 53,
        "day_start": 1331611200
      },
      {
        "clicks": 151,
        "day_start": 1331524800
      },
      {
        "clicks": 2,
        "day_start": 1331438400
      },
      {
        "clicks": 5,
        "day_start": 1331352000
      },
      {
        "clicks": 45,
        "day_start": 1331265600
      }
    ],
    "days": 7,
    "total_clicks": 388
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/countries

Returns aggregate metrics about the countries referring click traffic to all of the authenticated user's bitly links.

Authentication: oauth2

Parameters

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.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7. When a unit is specified, rollup is always true.

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.
days - the number of days for which data is provided (ONLY returned if unit is not specified).
countries - a list of countries referring traffic to this user's links. 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/user/countries?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "countries": [
      [
        {
          "clicks": 3,
          "country": "US"
        }
      ],
      [
        {
          "clicks": 96,
          "country": "US"
        },
        {
          "clicks": 19,
          "country": "None"
        },
        {
          "clicks": 4,
          "country": "CA"
        },
        {
          "clicks": 3,
          "country": "GB"
        },
        {
          "clicks": 2,
          "country": "NZ"
        },
        {
          "clicks": 2,
          "country": "IE"
        },
        {
          "clicks": 1,
          "country": "DE"
        },
        {
          "clicks": 1,
          "country": "HK"
        },
        {
          "clicks": 1,
          "country": "AU"
        }
      ],
      [
        {
          "clicks": 41,
          "country": "US"
        },
        {
          "clicks": 8,
          "country": "None"
        },
        {
          "clicks": 3,
          "country": "PL"
        },
        {
          "clicks": 1,
          "country": "GB"
        }
      ],
      [
        {
          "clicks": 113,
          "country": "US"
        },
        {
          "clicks": 21,
          "country": "None"
        },
        {
          "clicks": 4,
          "country": "CA"
        },
        {
          "clicks": 4,
          "country": "GB"
        },
        {
          "clicks": 3,
          "country": "NO"
        },
        {
          "clicks": 1,
          "country": "CL"
        },
        {
          "clicks": 1,
          "country": "AR"
        },
        {
          "clicks": 1,
          "country": "SE"
        },
        {
          "clicks": 1,
          "country": "IN"
        },
        {
          "clicks": 1,
          "country": "IE"
        },
        {
          "clicks": 1,
          "country": "PL"
        }
      ],
      [
        {
          "clicks": 1,
          "country": "US"
        },
        {
          "clicks": 1,
          "country": "TH"
        }
      ],
      [
        {
          "clicks": 4,
          "country": "US"
        },
        {
          "clicks": 1,
          "country": "None"
        }
      ],
      [
        {
          "clicks": 40,
          "country": "US"
        },
        {
          "clicks": 2,
          "country": "None"
        },
        {
          "clicks": 2,
          "country": "CA"
        },
        {
          "clicks": 1,
          "country": "PL"
        }
      ]
    ],
    "days": 7
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/popular_links

Returns the authenticated user's most-clicked bitly links (ordered by number of clicks) in a given time period.

Note: This replaces the realtime_links endpoint.

Authentication: oauth2

Parameters

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.
popular_links - the links that have received click traffic in the specified timeframe. Each link returns:
- link: a bitly link.
- clicks: the number of clicks on that bitly link in the specified timeframe.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/popular_links?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "popular_links": [
      {
        "clicks": 6150,
        "link": "http://bit.ly/123456"
      },
      {
        "clicks": 3647,
        "link": "http://bit.ly/234567"
      },
      {
        "clicks": 1814,
        "link": "http://bit.ly/abc123"
      },
      {
        "clicks": 1813,
        "link": "http://bit.ly/bcd234"
      }
    ],
    "tz_offset": -4,
    "unit": "day",
    "units": -1
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/referrers

Returns aggregate metrics about the pages referring click traffic to all of the authenticated user's bitly links.

Authentication: oauth2

Parameters

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.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7. When a unit is specified, rollup is always true.

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.
days - the number of days for which data is provided (ONLY returned if unit is not specified).
referrers - a list of URLs referring traffic to this user's links. 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/user/referrers?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "days": 7,
    "referrers": [
      [
        {
          "clicks": 5,
          "referrer": "direct"
        },
        {
          "clicks": 3,
          "referrer": "https://twitter.com/"
        }
      ],
      [
        {
          "clicks": 24,
          "referrer": "direct"
        },
        {
          "clicks": 7,
          "referrer": "https://twitter.com/"
        },
        {
          "clicks": 1,
          "referrer": "http://www.linkedin.com/home"
        },
        {
          "clicks": 1,
          "referrer": "http://mobile.twitter.com/"
        }
      ],
      [
        {
          "clicks": 11,
          "referrer": "direct"
        },
        {
          "clicks": 1,
          "referrer": "https://twitter.com/"
        },
        {
          "clicks": 1,
          "referrer": "http://www.linkedin.com/home"
        }
      ],
      [
        {
          "clicks": 27,
          "referrer": "direct"
        },
        {
          "clicks": 13,
          "referrer": "https://twitter.com/"
        },
        {
          "clicks": 2,
          "referrer": "http://hootsuite.com/dashboard"
        }
      ],
      [
        {
          "clicks": 1,
          "referrer": "http://blog.bitlyenterprise.com/"
        }
      ],
      [
        {
          "clicks": 2,
          "referrer": "https://twitter.com/"
        },
        {
          "clicks": 1,
          "referrer": "direct"
        }
      ],
      [
        {
          "clicks": 6,
          "referrer": "direct"
        },
        {
          "clicks": 2,
          "referrer": "https://twitter.com/"
        },
        {
          "clicks": 1,
          "referrer": "http://www.facebook.com/home.php"
        }
      ]
    ]
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/referring_domains

Returns aggregate metrics about the domains referring click traffic to all of the authenticated user's bitly links.

Authentication: oauth2

Parameters

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.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7. When a unit is specified, rollup is always true.

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.
days - the number of days for which data is provided (ONLY returned if unit is not specified).
referring_domains - a list of domains referring traffic to this user's links. 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/user/referring_domains?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "days": 7,
    "referring_domains": [
      {
        "dt": 1333339200,
        "values": [
          {
            "clicks": 1,
            "domain": "direct"
          }
        ]
      },
      {
        "dt": 1333252800,
        "values": [
          {
            "clicks": 3,
            "domain": "direct"
          }
        ]
      },
      {
        "dt": 1333166400,
        "values": [
          {
            "clicks": 7,
            "domain": "t.co",
            "url": "http://t.co/"
          },
          {
            "clicks": 4,
            "domain": "direct"
          }
        ]
      },
      {
        "dt": 1333080000,
        "values": [
          {
            "clicks": 36,
            "domain": "t.co",
            "url": "http://t.co/"
          },
          {
            "clicks": 6,
            "domain": "direct"
          },
          {
            "clicks": 5,
            "domain": "twitter.com",
            "url": "http://twitter.com/"
          },
          {
            "clicks": 1,
            "domain": "hootsuite.com",
            "url": "http://hootsuite.com/"
          }
        ]
      },
      {
        "dt": 1332993600,
        "values": [
          {
            "clicks": 96,
            "domain": "t.co",
            "url": "http://t.co/"
          },
          {
            "clicks": 21,
            "domain": "direct"
          },
          {
            "clicks": 15,
            "domain": "twitter.com",
            "url": "http://twitter.com/"
          },
          {
            "clicks": 3,
            "domain": "hootsuite.com",
            "url": "http://hootsuite.com/"
          },
          {
            "clicks": 1,
            "domain": "www.linkedin.com",
            "url": "http://www.linkedin.com/"
          }
        ]
      },
      {
        "dt": 1332907200,
        "values": [
          {
            "clicks": 49,
            "domain": "t.co",
            "url": "http://t.co/"
          },
          {
            "clicks": 33,
            "domain": "direct"
          },
          {
            "clicks": 4,
            "domain": "twitter.com",
            "url": "http://twitter.com/"
          },
          {
            "clicks": 2,
            "domain": "mail.verizon.com",
            "url": "http://mail.verizon.com/"
          },
          {
            "clicks": 2,
            "domain": "hootsuite.com",
            "url": "http://hootsuite.com/"
          }
        ]
      },
      {
        "dt": 1332820800,
        "values": [
          {
            "clicks": 16,
            "domain": "t.co",
            "url": "http://t.co/"
          },
          {
            "clicks": 16,
            "domain": "direct"
          },
          {
            "clicks": 1,
            "domain": "twitter.com",
            "url": "http://twitter.com/"
          },
          {
            "clicks": 1,
            "domain": "www.google.com",
            "url": "http://www.google.com/"
          }
        ]
      }
    ]
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/share_counts

Returns the number of shares by the authenticated user in a given time period.

Authentication: oauth2

Parameters

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

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.
share_counts - the number of shares from this user's account. If rollup=false, returns timeseries data per unit:
- dt - timestamp corresponding to the specified unit.
- shares - the number of shares in that timeframe.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/share_counts?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "share_metrics": 17,
    "tz_offset": -4,
    "unit": "day",
    "units": -1
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/share_counts_by_share_type

Returns the number of shares by the authenticated user, broken down by share type (ie: twitter, facebook, email) in a given time period.

Authentication: oauth2

Parameters

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

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.
share_counts_by_share_type - the number of shares from this user's account for each share_type. Each type of share returns:
- dt - timestamp corresponding to the specified unit. Included in timeseries response only if rollup=false.
- share_type - the type of share (twitter, email, facebook).
- shares - the number of shares of the specified type in that timeframe.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/share_counts_by_share_type?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "share_counts_by_share_type": [
      {
        "share_type": "twitter",
        "shares": 10
      },
      {
        "share_type": "email",
        "shares": 7
      }
    ],
    "tz_offset": -4,
    "unit": "day",
    "units": -1
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/shorten_counts

Returns the number of links shortened (encoded) in a given time period by the authenticated user.

Authentication: oauth2

Parameters

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

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.
user_shorten_counts - the number of shortens made by the specified user in the specified time.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/shorten_counts?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "tz_offset": -4,
    "unit": "day",
    "units": -1,
    "user_shorten_counts": 1254
  },
  "status_code": 200,
  "status_txt": "OK"
}