Bitly¶

class bitly.Bitly(token)¶

Create a Bitly service.

Variables:	token (str) – an OAuth 2.0 token.

HighValue¶

Bitly.highvalue()¶: Return the resource corresponding to all high-value links.

HighValue.get(limit)¶

Returns a specified number of “high-value” bitly links that are popular across bitly at this particular moment.

Variables:	limit (int) – the maximum number of high-value links to return.

Link¶

Bitly.link(link)¶: Return the resource corresponding to a single link.

Link.category()¶: Returns the detected categories for a document, in descending order of confidence.

Link.clicks(unit=None, units=None, timezone=None, rollup=None, limit=None, unit_reference_ts=None)¶

Returns the number of clicks on a single bitly link.

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
rollup (bool) – returns data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

Link.content(content_type=None)¶

Returns the “main article” from the linked page, as determined by the content extractor, in either HTML or plain text format.

Variables:	content_type (str) – specifies whether to return the content as html or plain text. if` not indicated, defaults to ‘html’.

Link.countries(unit=None, units=None, timezone=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

Link.encoders_count()¶: Returns the number of users who have shortened a single bitly link.

Link.info()¶: Returns metadata about a single bitly link.

Link.language()¶: Returns the significant languages for the bitly link.

Link.location()¶: Returns the significant locations for the bitly link or None if locations do not exist.

Link.referrers(unit=None, units=None, timezone=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

Link.referrers_by_domain(unit=None, units=None, timezone=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

Link.referring_domains(unit=None, units=None, timezone=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

Link.shares(unit=None, units=None, timezone=None, rollup=None, limit=None, unit_reference_ts=None)¶

Returns metrics about a shares of a single link.

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
rollup (bool) – returns data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

Link.social()¶: Returns the “social score” for a specified bitly link.

RealTime¶

Bitly.realtime()¶: Return the resource corresponding to a single object.

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.

RealTime.clickrate(phrase)¶

Returns the click rate for content containing a specified phrase.

Variables:	phrase (str) – the phrase for which you’d like to get the click rate.

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.

Search¶

Bitly.search()¶: Return the resource corresponding to all links.

Search.get(limit=None, offset=None, query=None, lang=None, cities=None, domain=None, fields=None)¶

Search links receiving clicks across bitly by content, language, location, and more

Variables:

limit (int) – the maximum number of links to return.
offset (int) – which result to start with (defaults to 0).
query (str) – the string to query for.
lang (str) – favor results in this language (two letter ISO code).
cities (str) – show links active in this city.
domain (str) – restrict results to this web domain.
fields (str) – 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.

User¶

Bitly.user()¶: Return the resource corresponding to a single user.

User.clicks(unit=None, units=None, timezone=None, rollup=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
rollup (bool) – returns data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

User.countries(unit=None, units=None, timezone=None, rollup=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
rollup (bool) – returns data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

User.info(login=None, full_name=None)¶

Return or update information about a user.

Variables:	login (str) – the bitly login of the user whose info to look up. If not given, the authenticated user will be used. full_name (str) – set the users full name value (only available for the authenticated user).

User.link_history(link=None, limit=None, offset=None, created_before=None, created_after=None, modified_after=None, expand_client_id=None, archived=None, private=None, user=None)¶

Returns entries from a user’s link history in reverse chronological order.

:var link the bitly link to return metadata for (when specified,: overrides all other options).

:var limit the max number of results to return. :vartype login: int

:var offset the numbered result at which to start (for pagination). :vartype offset: int

:var created_before timestamp as an integer unix epoch. :vartype created_before: int

:var created_after timestamp as an integer unix epoch. :vartype created_after: int

:var modified_after timestamp as an integer unix epoch. :vartype modified_after: int

:var expand_client_id whether to provide additional information about: encoding application.

:var archived whether to include or exclude archived: history entries. Defaults to ‘off’.

:var private whether to include or exclude private: history entries. Defaults to ‘both’.

Variables:	user (str) – the user for whom to retrieve history entries (if different from authenticated user).

User.network_history(limit=None, offset=None, expand_client_id=None, expand_user=None)¶

Returns entries from a user’s network history in reverse chronogical order.

:var limit the max number of results to return. :vartype login: int

:var offset the numbered result at which to start (for pagination). :vartype offset: int

:var expand_client_id whether to provide additional information about: encoding application.

:var expand_user include extra user info in response. :vartype expand_user: bool

User.popular_links(unit=None, units=None, timezone=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

User.referrers(unit=None, units=None, timezone=None, rollup=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
rollup (bool) – returns data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

User.referring_domains(unit=None, units=None, timezone=None, rollup=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
rollup (bool) – returns data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

User.share_counts(unit=None, units=None, timezone=None, rollup=None, limit=None, unit_reference_ts=None)¶

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

Variables:

unit (str) – timspan: minute, hour, day, week or month. When unit is minute the maximum value for units is 60. if` not indicated, defaults to day.
units (int) – an integer representing the time units to query data for. If -1 is passed, it will return all units of time.
timezone (str) – an integer hour offset from UTC (-14..14) or a timezone string. If not indicated, defaults to America/New_York.
rollup (bool) – returns data for multiple units rolled up to a single result instead of a separate value for each period of time.
limit (int) – the number of rows it will return. Default is 100.
unit_reference_ts (int) – an epoch timestamp, indicating the most recent time for which to pull metrics. If not indicated, it defaults to now.

User.tracking_domain_list()¶: Returns a list of tracking domains a user has configured.