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.
- 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. - 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:
API¶
-
class
parsons.
CrowdTangle
(api_key=None)[source]¶ Instantiate CrowdTangle Class
- Args:
- 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.
- Args:
- 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
oryyyy-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
oryyyy-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
andlive_video_complete
parameters.The
video
type does not mean all videos, it refers to videos that are notnative_video
,youtube
orvine
.
- 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.
- Args:
- 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
oryyyy-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
oryyyy-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, theaccount_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.
- Args:
- 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
oryyyy-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
oryyyy-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 forstart_date
. - platforms: list
- Filter by platforms
- Returns:
- Parsons Table
- See Parsons Table for output options.