Did you know that Meta has a public database of currently running and archived Meta ads? Using AI, you can identify top-performing content and trends to apply to generating new Meta ads. Here’s a step-by-step on how to do that.
This demonstration uses OpenAI’s paid GPT-4 model. The free GPT 3.5 model does not allow file upload and limits messages to 4096 tokens (roughly 4096 words) inclusive of both input and output. Using the free version, you cannot analyze your entire dataset at once, but must split the file into separate messages, each a maximum of 2000 words long.
The Basics of Meta Ad Library
Meta has 3 versions of its Ad Library, each with its own caveats.
Ad Library is a user interface that lets you search ALL the ads currently running and archived (up to 5 years) in the past across Meta. Social, election, or political ads have an archive of up to 7 years. EU ads have an archive of 1 year. In your search query, you must include location, ad category, and search term. Meta returns posts with each ad’s Library, Status, Start date, End date, Platforms, Categories, Estimated audience size, Amount spent, Impressions, Byline (who paid for the ad), and Creative. The caveat is that the data can’t be exported.
Ad Library Report is a limited interface that lets you search for ads about social issues, elections or politics. It can only search by predetermined filters: by advertiser, by location, or by preset date ranges. The interface returns information on the Disclaimer, Amount spent, and Number of ads in library, You can download a full csv report by date range.
Ad Library API is an application programming interface that lets you customize search criteria for ads in social issues, election or politics that were delivered anywhere in the world during the past 7 years, as well as ads of any type delivered to the European Union during the past year. It has more search filters and returns more data. The caveat is you need to do a little programming to get the data, there are still limitations to bulk export, and the accuracy and completeness of the data is still questionable.
For our purposes, we will be using the Ad Library to access a greater scope of ads and ad data, then export to pdf to circumvent the lack of bulk export features. Note that due to the export restrictions, you will only be able to analyze a small set of ads and the spend amount will be hidden, so this method works best for ad copy analysis of top performing ads or analysis of competitor ad copy. We will then import the data into ChatGPT for analysis.
If you have programming experience, see the Advanced section where you can use the Ad Library API to download up to *429 ads.
The Easy Steps
- Pull up ad library view.
- Sort by most impressions. This will help sort the most valuable ads to the top since the PDF export won’t include the amount spent and other details.
- Export to pdf. Modify the total pages based on your needs. Pro-tip you can include 2 pages per to fit more ads into your export.
- Prompt your AI to analyze your export.
Explore the content using the chat tool of your choice and ask for it to do things like categorize the ad themes.
Advanced Use of Facebook Ad Library API
Ok, let’s get technical. Using the Ad Library API, you can download ad data in the social, elections, and political category, or any ads in the EU from the past year. UNFORTUNATELY, Meta still makes it hard to bulk download ad data. I adjusted the data limit of my export and got it working for a day. Then, in subsequent data retrieval attempts, Meta threw an internal error, preventing access to its data. Additionally, the Ad Library API does not store image and video data, and some of the data is recorded in ranges versus concrete numbers, limiting your analysis.
When choosing the dataset you want to analyze, I suggest narrowing your search so that you are analyzing a more significant sample size of ads relative to the total number of ads for that search. For example, you can narrow your search to ads for 1 country and 1 month.
Before you can access Meta’s Code Base to retrieve ad data, you need to verify your identity so Meta knows who’s accessing their code base.
Identity Verification and Permission To Access Meta’s Code Base
- Confirm your identity and location.
Go to Facebook.com/ID and follow the confirmation process required to run ads about social issues, elections or politics. This can take a few days.
- Create a Meta for Developers account
Visit Meta for Developers and select Get Started. As part of account creation, you’ll need to agree to Meta’s Platform Policy.
- Add a new app.
Go to the Ad Library API page and select Access the API. You will be redirected to your apps tab on the Meta for Developers platform. You can then create a new app by selecting My Apps > Create App. Select Other use case. Select app type Business. This lets you access the Marketing API, which houses the Insights API you need to use to access Ad Library. Name your app. Add your contact email. Skip connecting a Business Account because you will not be accessing/managing a Business Account for this purpose. This is all you have to do with the app. For our purposes, the app only tells Facebook what permissions we need, which determine what parts of the Meta code base we’re allowed to access.
- Go to the Graph API Explorer to get your token.
The Graph API Explorer is an online environment that lets you type in search queries and return data. A token verifies your identity and lets you access Meta’s backend. On the right, make sure your Meta App is selected. Select User Token. Permissions should be set to ads_read. You only need to read what’s in the Ad Library; you do not need to edit or post anything to the Ad Library. Click get access token and copy the token. The standard token lasts for 1 hr. Because of the lack of documentation online about the Graph API Explorer syntax and how to connect it to Ads Library, use your computer’s native command line or terminal instead.
Export Data
- Type your search query into your command line or terminal. For this demonstration, I’m using a Mac OS.
We will be using cURL commands. The cURL command receives a URL to transfer data to, or receive data from, along with other options for different purposes. Follow the below syntax, including commands, quotations, underscores, equal signs, apostrophes, brackets, and back slashes. Replace search parameters and return values with your desired values. For a list of search parameter values, see here. For a list of return values, see here.
curl -G \
-d “search_terms=’voting'” \
-d “ad_type=POLITICAL_AND_ISSUE_ADS” \
-d “ad_reached_countries=[‘US’]” \
-d “ad_active_status=ALL” \
-d “ad_delivery_date_min=2023-12-01” \
-d “ad_delivery_date_max=2024-01-01” \
-d “fields=[‘id,ad_creative_bodies,ad_creative_link_captions, ad_creative_link_descriptions,ad_creative_link_titles,ad_delivery_start_time,ad_delivery_stop_time,ad_snapshot_url,bylines,delivery_by_region,demographic_distribution,estimated_audience_size,impressions,page_name,publisher_platforms,spend’]” \
-d “access_token=pasteYourAccessTokenHere” \
“https://graph.facebook.com/v19.0/ads_archive?limit=429”
*In the url, you can replace the version with the most up to date version of the ad archive. Because there is no documentation of the latest version online, I guessed the number. Any number higher than the latest version will return an error. You can also double check the online Graph API Explorer to see what version is currently running there.
Meta sets limits to how many data entries (ads) it returns using a pagination system. For me, the default was 25 entries. To adjust the limit, add ?limit=yourNumber to the end of the graph url. I tested the limit and the maximum number of ads I could pull was 429. GPT 4 can take files of up to 512 MB and only 10 files per chat. Set reasonable limits and make sure your file is under 512 MB.
- Save your data output.
Your search query will return your desired data in a json format. Json is a lightweight format for storing and transferring data. Save the terminal output directly into a text file (CMD+S for Mac). Do not copy and paste output as this will produce errors in the output file. In the saved text file remove the cURL commands and ‘data’ field that encapsulates the data you want to extract. You don’t want any nonstandard or superfluous information that will inhibit GPT from parsing your file.
This means, 1. removing the beginning of the file so that it starts at {“id”.
2. remove superfluous fields at the end of the file that contain information on paging etc. The file should end with }}. See sample text to remove below.
],”paging”:{“cursors”:{“after”:”c2NyYXBpbmdfY3Vyc29yOk1UY3dOREV5TlRVd05Eb3lOekkwT1RNNE5EUXdPVGd3T0RJMQZDZD”},”next”:”https:\/\/graph.facebook.com\/v19.0\/ads_archive?search_terms=’voting’&ad_type=POLITICAL_AND_ISSUE_ADS&ad_reached_countries=[‘US’]&ad_active_status=ALL&ad_delivery_date_min=2023-01-01&ad_delivery_date_max=2024-01-01&fields=[‘id,ad_creative_bodies,ad_creative_link_captions,ad_creative_link_descriptions,ad_creative_link_titles,ad_delivery_start_time,ad_delivery_stop_time,ad_snapshot_url,bylines,delivery_by_region,demographic_distribution,estimated_audience_size,impressions,page_name,publisher_platforms,spend’]&access_token=&limit=25&after=c2NyYXBpbmdfY3Vyc29yOk1UY3dOREV5TlRVd05Eb3lOekkwT1RNNE5EUXdPVGd3T0RJMQZDZD”}}
Convert Data to CSV File
Convert your entire dataset to csv format before proceeding with additional commands that might cause data loss. CSV is a data storage format that can be read by spreadsheets. Because your current text file has an irregular json structure, specifying a regular structure will also help GPT to analyze and return the results you want for future commands.
Upload your file. Use this prompt to convert your file to CSV so that it can be read by a spreadsheet:
Task: Convert Irregular JSON Data to CSV
You are provided with a file containing irregularly structured JSON data, similar to the previous file. The goal is to parse this data correctly and convert it into a CSV file with the following requirements:
1. Each JSON object in the file represents a single record, and each record should correspond to one row in the CSV file.
2. The CSV file should have columns named “id”, “ad_creative_bodies”, “ad_creative_link_captions”, “ad_creative_link_descriptions”, “ad_creative_link_titles”, “ad_delivery_start_time”, “ad_delivery_stop_time”, “ad_snapshot_url”, “bylines”, “delivery_by_region”, “demographic_distribution”, “estimated_audience_size”, “impressions”, “page_name”, “publisher_platforms”, and “spend”.
3. For keys that contain nested objects, lists, or have multiple values within single keys, concatenate these values into single strings in the CSV.
4. If a JSON object is missing any of the specified keys, treat the corresponding field in the CSV as blank.
To achieve this, follow these steps:
1. Implement a custom JSON parsing logic that accurately identifies the start and end of each JSON object within the file, taking into account nested structures and concatenation of multiple JSON objects.
2. Parse each identified JSON object and convert it into a dictionary with a flat structure, ensuring that keys correspond to column headers in the CSV.
3. Concatenate values for keys with nested objects, lists, or multiple values within single keys into single string values.
4. Create a DataFrame from the parsed data and then convert it into a CSV file with the specified column headers.
5. Ensure that the CSV file is populated with data and follows the specified format.
Please execute these steps to convert the irregular JSON data into a CSV file correctly. In case of any issues or errors during the process, provide detailed information about the problem encountered.
Parse the entire content, ensuring every JSON object the file contains is converted into a row in the CSV file. Tell me the number of records extracted and converted into the CSV format.
Additional Troubleshooting Notes:
If your csv file contains no lines,
- GPT may need to adjust its parsing logic. Tell GPT to create a custom parsing logic to parse the data, taking into account your previous instructions.
- your file may be corrupted and GPT can’t use a standard logic to parse each ad entry
If your csv file contains 1 line,
- GPT may only have read and parsed the first line of your data. Tell it to parse the entire content, ensuring every JSON object the file contains is converted into a row in the CSV file.
Analyze Your Data Using AI
Prompt your AI chatbot to analyze your table for top performers and trends. Use OpenAI or Anthropic to analyze an uploaded file.
Sample prompt: identify top performing ads. This gives you an overview of metrics to consider, what metrics GPT uses, a table for those metrics, and an explanation of how to determine top performers (high impressions, large estimated audience size, higher spend).
Sample prompt: identify top performing ads by impressions/spend
This gives you a new table that includes an impr/spend column and summarizes the top 3 ads by highest impr/spend.
Secondary prompt: identify [Ad Delivery Time Trends, Ad Performance Metrics, Demographic Distribution Trends, Geographic Trends, Publisher Platforms and Spend Trends, Content and Link Trends, Publisher Attribution (Bylines), General Campaign Theme] trends in the data. You can do this for top performing and worst performing ads.
Warning: Inaccuracy of Meta Ad Library API Data
There is documentation on the inaccuracy of Meta’s Ad Library data. There have been investigations that show that Facebook’s political spending numbers don’t add up, incorrect or incomplete data on ads with multiple creatives (you don’t know which creative people saw), inability to see creatives, and a lack of definitive spend. When conducting analysis using this API, do note these limitations.
Resources
Ad Library API search parameters
Marketing API Error Codes and What They Mean (terminal will output an error message in the format of html. A negative error means there’s something wrong with facebook’s side)
Data Inaccuracies with Ad Library API
How to use the Graph API Explorer tool
Insights API code examples to get your ad data
Create an ad campaign using the Marketing API, terminal, and cURL