On June 10th, the Ad Library and the Facebook’s Ad Library API went live in Canada. The release of these new ad transparency tools in Canada is part of an expansion of Facebook’s 61 nations-strong ad transparency initiative. The timing of this release in Canada is significant, as this precedes the start of the pre-election campaign period for the 2019 Canadian Federal Election, which is scheduled for October 21st. This move is also significant for another reason. Facebook is in a rarefied position as one of only three websites in Canada (from among the top 20 most visited websites, alongside Instagram, which is also owned by Facebook, and CBC.ca) that is now accepting political and issue ads in Canada. Google decided to not accept any political ads in this election cycle, citing a lack of time to build systems that are compliant with the Canada Elections Act, and Twitter has opted not to accept any partisan and political ads until the formal campaigning period begins.
This post is part of a two-part series on the Canadian version of Facebook’s Ad Library and Facebook’s Ad Library API as of mid-July 2019. In this blog (Part 1), we will cover what the Ad Library and Ad Library API are and how to access them. In the next blog (Part 2), we discuss what we found (and couldn’t find) using both, compare Facebook’s offerings to that of one of their main political ads competitors, Twitter, and provide some recommendations for improving both the Ad Library and the Ad Library API.
What are the Facebook Ad Library and Ad Library API?
The Facebook Ad Library is a searchable, web-based archive of political ads run on Facebook in certain regions of the world. All ads related to politics (or issues of national importance), whether subsequently taken offline or not, will be stored in the Ad Library for seven years. The Ad Library can be accessed by anyone, whether they have a Facebook account or not. (See Fig. 1)
The Ad Library API, on the other hand, provides a programmable interface to access and query Facebook’s archive of ads automatically using a script. (See Fig. 2)
Both the web-based Ad Library and the Ad Library API allow you to easily access a variety of information about ads, including details about when the ad was run, the amount of money spent on it and by who, how many impressions it made, where it was viewed, different demographic groups who engaged with the ad (in aggregate), different versions of the same ad, and more.
However, there are some differences between the Ad Library and the Ad Library API. The Ad Library provides a more intuitive interface for people to browse and explore the ads that Facebook has archived, with the added benefit of being able to view more information about the advertisers themselves, such as their contact information. This additional information about advertisers is not something that can be queried using the Ad Library API, and those using the API who would like to access this information would have to look it up manually in the Ad Library. The Ad Library, then, is most well suited to users who want to generally browse the ads on Facebook or have a specific topic or advertiser that they are interested in learning more about. (See Fig. 3A-3C)
The Ad Library API, on the other hand, provides more details and advanced filtering options for archived ads. For example, the API allows you to specify the ad type you are querying, be it those that are political and issue-based, news, or those that are uncategorized. Curiously, however, the option to filter ads by whether they are related to politics, elections, or issues is available when viewing all ads for a specific advertiser in the United States’ Ad Library, but does not appear to be available anywhere else in the world, including Canada. Similarly, when searching for ads by keyword, the option to filter ads by whether they are active or inactive is available in both Canada and the United States, but filtering by activity for a specific advertiser is only available in the United States’ Ad Library. (See Fig. 4A & 4B) These features may be tied to unique legislative requirements in the United States, but are curious omissions given that the Ad Library API permits filtering by advertisement type and activity, and does not require searching amongst the ads of a specific advertiser to filter by advertisement type specifically.
The Ad Library API also lets you query multiple, select countries at once, whereas the Ad Library only lets you search within a single country or across all countries. For any given ad, and unlike the Ad Library, the API allows for extraction of demographic breakdowns to six decimal points, page IDs, and permalinks to “snapshots” of the ads, which show how the ads looked on users’ timelines when they were run. For example, using the API, researchers could automate the extraction of the specific proportions of male, female, and nonbinary Facebook users who view ads from a given political candidate, and statistically analyze which gender(s) of users they are reaching most.
Given the more specific percentage values for who viewed the ads and greater filtering options, the Ad Library API is best suited for developers and data-centric researchers and journalists who aim to systematically explore large amounts of the Ad Library at once.
How to access the Ad Library API
Unlike the Ad Library, which is freely accessible to all, the Ad Library API requires people to have a Facebook account and go through a three-step verification process to gain access. (See Fig. 5) This three-step process is akin to the one that advertisers running political ads have to go through.
The second and third steps are more straightforward, however the first step has a few quirks associated with it. Interestingly, even if you just want to access the API, you must click the “Running Ads Related to Politics or National Issues” option to proceed, which gives the impression that Facebook is treating those who run ads and those who intend to do research on them similarly. (See Fig. 6)
Step 1 also requires people to confirm their identity with Facebook, including uploading a photo of valid identification documents, such as a driver’s license. As we discovered, Facebook does not accept Ontario Photo Cards as a legitimate form of personal identification, despite being government-issued and acceptable by law across the province.
To finalize Step 1, you will have to wait for a confirmation code to be physically mailed to you. But while you are waiting for the code, you can start exploring the Ad Library API by using Facebook’s Graph API Explorer. But before you do, be sure to review the documentation on the parameters and fields you can use in your queries.
Below is an example of a query. Ampersands allow you to add multiple search parameters (blue text), and commas allow you to add multiple terms (red text) within each of those search parameters.
ads_archive?ad_reached_countries=CA&ad_active_status=ACTIVE&search_terms=election&fields=ad_creative_body,ad_snapshot_url
The query above would return the ad text bodies and ad snapshot URLs for active ads in Canada that contain the term election anywhere in their contents. In the Graph API, the data returned would look something like this: (See Fig. 7)
It looks like there are a lot of duplicates in the image above, but that is mainly because it is returning multiple versions of the same ad (as intended!).
This conclude our brief introduction into Facebook’s new political ad transparency tools, the Ad Library and Ad Library API. In Part 2, we discuss what we’ve found from investigating ads on Facebook using these tools, compare them to Twitter’s offerings, and share our ideas on how these tools could be improved to provide even better transparency than they currently do.
*Written By Arvin Jagayat, Anatoliy Gruzd and Philip Mai
