A Beginner’s Guide to the CrowdTangle API

A Beginner’s Guide to the CrowdTangle API

Sometimes We Need the Raw Data

Make no mistake: a CrowdTangle dashboard is, right out of the box, a fluid and powerful GUI. The platform handles the sweeping majority of our research needs with ease (and without any “under the hood” tomfoolery). If you’re looking for help with the basics, check out my beginner’s guide!

If you’re a superfan of the tool, though, you’ll eventually come up with an idea that demands direct access to the platform’s data pipeline. Luckily, CrowdTangle has a free and (uncannily) intuitive API! Barring a few unwritten steps — the GitHub repository is pretty barebones — you can be GET-ting calls within an hour.

To skip to different steps in this guide:

1. Setup Your Dashboard for API Use
2. Get Your API Token
3. Construct Your API Call
4. Find Your Account in the Returned Data
5. Get Relevant Metrics

Setup

Create a list in each of your CrowdTangle dashboards with ONLY the account you want to monitor. Because I’m looking at CrowdTangle, I made lists (one Facebook, one Instagram, one Twitter) with just their accounts.

Get Your Token

Every different dashboard within CrowdTangle has its own unique API key. With this string of characters, you’ll be able to query the CrowdTangle database and get back raw data.

CrowdTangle does not use any kind of OAuth or verified handshakes, and the token does not expire unless a replacement is generated. Treat this like you would a password!

Assuming you have access to the API: To get your token, simply click on your settings and select “API Access.” Paste this to your text editor of choice.

Construct Your Call

You can query the API by including your token and filters as simple ?query-parameters. (You can also send a header request, but for the purposes of this guide we’re going to keep everything in the browser). The root URI from which we will work is:

https://api.crowdtangle.com/

Note: You must use https.

The first thing we need to choose what kind of data we want. Here are our options:

• /posts -> Returns a list of posts
• /posts/search -> Returns a list of posts but using the search functionality, AKA from CrowdTangle’s entire database (requires special approval for use)
• /leaderboard -> Returns a leaderboard from a grouping of accounts
• /links -> Returns up to 100 posts matching a certain link
• /lists -> Returns the lists, saved searches, and saved posts lists of the dashboard associated with the API token

You’ll notice that there’s no “account” option by default – kind of like getting post histories, we need to work through a dedicated list (and then a leaderboard) to perform calls on a specific social profile.

That said, we now have:

https://api.crowdtangle.com/lists

I want to get everything back in XML format (makes it easily parsable in Google Sheets), so I’ll add “.xml” to the end of this path.

https://api.crowdtangle.com/lists.xml

The third thing that the API needs is your access token. Luckily, you just got that from your CrowdTangle dashboard! Append it to the URL using the query parameter “?token=your-api-token”.

https://api.crowdtangle.com/lists.xml?token=your-api-token

At this point, if you click on this link, you should get back an XML tree of every list within your dashboard.

Pin Down Your Account

Scroll through these lists to find the list that you created earlier and get that list’s <id>. Save this number in your text editor alongside your API key.

Next, we need to go into this list to find the ID tied to the account you’d like to report on. We’ll use a leaderboard to do so; append “&listId=your-list-id” to the end of a leaderboard.xml URI to see the results:

https://api.crowdtangle.com/leaderboard.xml?token=your-api-token&listId=your-list-id

Within this response, you’ll see another <id> element, under the <account> parent container – this is (at long last) the account ID we’ve been looking for!

Get Account Performance

The last step to raw account performance data is querying another leaderboard with an accountID set. You can do this by replacing listId from before with “accountIds=your-account-id”.

https://api.crowdtangle.com/leaderboard.xml?token=your-api-token&accountIds=your-account-id

Then, set your date range with “&startDate=YYYY-MM-DD” and “&endDate=YYYY-MM-DD”:

https://api.crowdtangle.com/leaderboard.xml?token=your-api-token&accountIds=your-account-id&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Boom! A specific social profile’s raw performance structured data, filtered by a date range, and returned as an XML document! You will need to repeat this whole process for each CrowdTangle dashboard to cover each different social platform.

From here, you can do any kind of parsing you’d like to suit your fancy. Keep in mind the following few rules to the CrowdTangle API:

• To make calls to the API, you must use your own token
• CrowdTangle has internal limits to the number of calls you can make. After 2 per minute per token, the API will rate limit you and throw back an error

Don’t make front-end facing widgets using CrowdTangle’s API – instead, pull data and store it on your own, and then use that data to power your own projects.

For example, for my projects, I usually pull and copy historical data independently into a helper sheet. Then, when my team goes to my Data Studio, Tableau, etc. dashboards, it can call numbers from that sheet instead of from the API directly.

API rules exist for any API to keep access fluid and fair for all users :-).

The CrowdTangle API is very powerful. Now that you’re familiar with the syntax, have fun diving in and seeing what you can get back! Additional parameters and filters can be found in the GitHub documentation.

Happy calling!