On October 20th, 2020, we’ll be implementing a change to our API that requires action from our API users who rely on the CrowdTangle Post ID. Below, we’ll walk you through what code you need to implement to ensure there’s no disruption in your API calls.
For every post in CrowdTangle, we have always stored two different IDs: our internal CrowdTangle Post ID, and the ID that the actual platform (Facebook, Instagram, Reddit) uses (platformExternalId).
On October 20, we will switch to a new format for CrowdTangle Post IDs that is derived directly from those platformExternalIds.
There will be minimal disruption at first, but starting October 20, all CrowdTangle Post IDs will be different. To ensure no disruption at all, the changes will need to be put in before October 1. You likely won’t notice a difference until our change goes fully into effect in mid-October.
If you do not rely on the CrowdTangle Post ID for your API tooling, no action is needed on your part.
What do I need to do?
Please make sure the person managing your API tools is aware of this change. There are two states that you can choose for the account:
State 1 (existing way - if you don’t make any changes, you will remain in this state): In this case, the CrowdTangle Post ID will remain the same as it has been, and we will expose a new variable called newId which will contain the soon-to-be ID of the post in the API response. If you don't make any changes, you will automatically be switched into state 2 starting October 20. Staying in State 1 gives you more time to accommodate the change.
State 2 (opting in to the new CrowdTangle Post ID structure): In this case, the CrowdTangle Post ID will be the new ID of the post, and we will expose a new variable called legacyId which will contain the former ID of the post.
You may choose which state you’d like for each dashboard by using the below toggle. It is critical that you make the decision for all dashboards that you’re using for API access:
The differences between old and new IDs
The old CrowdTangle Post ID was an integer (technically a long integer). The new ID is a string, made by concatenating two other IDs together. Let’s use an example of the old ID of 1234, and a new ID of 555|987654321.
If you have not opted in to receiving the new CrowdTangle Post ID via your dashboard’s API settings dialog (state 1), you will receive the following 2 IDs in API responses: id (1234), and newID (555|987654321).
If you have opted in (state 2), the main ID field will switch, and your two IDs will be: id (555|987654321) and legacyId (1234).
How to determine the new ID of a post
You have two options:
1. Call our API for the post and save the returned newId field.
2. Build the new ID from data you may already have in your database.
To get the ID from our API (option 1), simply call /ctpost/1234. It will return a post, complete with the new ID either in the newId or id field (depending on state 1 or 2).
To build the new ID (option 2), you can use 3 existing fields if you have them in your database: account.id, platform, and platformId. The newId is “account.id|postExternalId”.
The first step is to find the postExternalId, which depends upon the platform:
- For Facebook, the platformId will be in the format “<number1>_<number2>”. “postExternalId” will be number 2.
- For Instagram, the platformId will be in the format “<number1>_<number2>”. “postExternalId” will be number 1.
Yes, we know that is confusing. We didn’t create the IDs in either case. :-)
- For Reddit, the platformId is already “postExternalId”.
Below are the steps to build the ID once you've obtained the postExternalId.
Code Sample: How to create the new ID in your DB
Here is an example SQL query to add a new field that will be the right type for the ID:
Edit your table to make newId the primary key. Leave the other ID indexed but stop it from being a primary key. Later, after you have edited your code, you can change the following names to match the new API:
- id -> legacyID
- newId -> id
Code Sample: How to replace the old CrowdTangle Post ID in your DB, without calling our API again
As noted above, you have two options for replacing the old CrowdTangle Post ID in your DB. If you already have the fields account.id, platform, and platformID in your DB, you can create the new ID on your own. For example, if you have this table:
You can add a newId field by running:
You can populate the newId field by running this SQL statement:
Then, after you have opted in to state 2, you can rename the fields accordingly:
- id -> legacyId
- newId -> id
What happens if I don’t make any changes?
If you don’t make any changes, we will consider you to have chosen State 1, i.e. “opted out.” The CrowdTangle pPost ID will remain the same as always, and we will expose a new variable called newId (name can change) which will contain the soon-to-be ID of the post in the API response.
Starting October 1, any new account added to the CrowdTangle database will return the new form of CrowdTangle Post IDs. You can remain in state 1, but posts from accounts that only have the new form of CrowdTangle Post ID will show up with the ID of 0.
On October 20, all CrowdTangle Post IDs will transition to the new system, so if you want to pull in any new posts (e.g. posts that did not exist in our system prior to that time), the code change must be implemented by October 20.
What if I’m unable to make this change in time?
Please reach out to firstname.lastname@example.org and we can help walk you through what needs to be done and find a solution.