CrowdTangle¶

Overview¶

CrowdTangle is a Facebook-owned content monitoring and social monitoring platform. This Parsons integration with the CrowdTangle API supports getting posts and leaderboard data.

Note

Authentication: An API Token is required to access the API. Assuming you have access to the CrowdTangle API, you can find the API Token in your dashboard under Settings > API Access. Contact your CrowdTangle representative for access.

Note

Rate Limits: The CrowdTangle API has strict rate limits that vary depending on the endpoint. In the CrowdTangle class, method docstrings indicate the rate limit for the relevant endpoint. For more information on rate limits and best practices for meeting them, check the API documentation.

Note

Performance: CrowdTangle queries are expensive because they search and score billions of posts. Calls should be made from your server and stored in order to avoid making API calls every time someone hits your app server.

Quickstart¶

To instantiate the CrowdTangle class,either store your CrowdTangle API as the environmental variable CROWDTANGLE_API_KEY or pass it as a keyword argument:

from parsons import CrowdTangle

# First approach: Use environmental variable for API Key
ct = CrowdTangle()

# Second approach: Pass API Key as argument
ct = CrowdTangle(api_key='my_api_key')

# Get posts matching the given parameters
ct.get_posts(start_date='2020-06-01', min_interactions=50, search_term='test',
             types=['live_video', 'live_video_complete'])

API¶

class parsons.crowdtangle.crowdtangle.CrowdTangle(api_key=None)[source]¶

Instantiate CrowdTangle Class

Parameters:: api_key – str A valid CrowdTangle API key. Not required if CROWDTANGLE_API_KEY env variable set.
Returns:: CrowdTangle Class

get_posts(start_date=None, end_date=None, language=None, list_ids=None, min_interations=None, search_term=None, types=None)[source]¶

Return a set of posts for the given parameters.

See the API documentation for more information.

Warning

Rate limit is 2 calls / minute.

Parameters:

start_date – str Filter to the earliest date at which a post could be posted. The time is formatted as UTC (e.g. yyyy-mm-ddThh:mm:ss or yyyy-mm-dd).
end_date – str Filter to the latest date at which a post could be posted. The time is formatted as UTC (e.g. yyyy-mm-ddThh:mm:ss or yyyy-mm-dd).
language – str Filter to 2-character Locale code. Some languages require more than two characters: Chinese (Simplified) is zh-CN and Chinese (Traditional) is zh-TW.
list_ids – list Filter to the ids of lists or saved searches to retrieve.
min_interactions – int Filter to posts with total interactions above this threshold.
search_team – str Returns only posts that match this search term. For multiple terms, separate with commas for OR, use quotes for phrases.
types –
list Filter to post types including: * episode * extra_clip * link * live_video * live_video_complete * live_video_scheduled * native_video * photo * status * trailer * tweet * vimeo * vine * youtube

If you want all live videos (whether currently or formerly live), pass include both live_video and live_video_complete parameters.

The video type does not mean all videos, it refers to videos that are not native_video, youtube or vine.

Returns:

Parsons Table: See Parsons Table for output options.

get_leaderboard(start_date=None, end_date=None, list_ids=None, account_ids=None)[source]¶

Return leaderboard data.

See the API documentation for more information.

Warning

Rate limit is 6 calls / minute.

Parameters:

start_date – str Filter to the earliest date at which a post could be posted. The time is formatted as UTC (e.g. yyyy-mm-ddThh:mm:ss or yyyy-mm-dd).
end_date – str Filter to the latest date at which a post could be posted. The time is formatted as UTC (e.g. yyyy-mm-ddThh:mm:ss or yyyy-mm-dd).
list_ids – list Filter to the ids of lists or saved searches to retrieve.
account_ids – list A list of CrowdTangle accountIds to retrieve leaderboard data for. This and list_id are mutually exclusive; if both are sent, the account_ids value will be used.

Returns:

Parsons Table: See Parsons Table for output options.

get_links(link, start_date=None, end_date=None, include_summary=None, platforms=None)[source]¶

Return up to 100 posts based on a specific link. It is strongly recommended to use the start_date parameter to limit queries to relevant dates.

See the API documentation for more information.

Warning

Rate limit is 2 calls / minute.

Parameters:

link – str The link to filter posts to.
start_date – str Filter to the earliest date at which a post could be posted. The time is formatted as UTC (e.g. yyyy-mm-ddThh:mm:ss or yyyy-mm-dd).
end_date – str Filter to the latest date at which a post could be posted. The time is formatted as UTC (e.g. yyyy-mm-ddThh:mm:ss or yyyy-mm-dd).
include_summary – boolean Adds a summary column with account statistics for each platform that has posted this link. It will look beyond the count requested to summarize across the time searched. Requires a value for start_date.
platforms – list Filter by platforms

Returns:

Parsons Table: See Parsons Table for output options.