In this godawful year of all godawful years, it’s good to keep an eye on who’s trying to sell what to you, why, and for how much. Facebook’s Ad Library gives (limited) insight into the market for political advertising on the platform, and you can browse it here.
If you’re doing more in-depth research, though, browsing the Library via the web is likely to put a brake on what you can do – much better to pull the data from Facebook’s API. You get the results back as JSON, making it easy to manipulate and display or store in a database and query.
It took me a while to figure out how to do that, so I’m outlining it here. A Facebook account is required (sigh).
Step 1 – Make an App
To access the API you need to create an App. Open the Developer Portal here:
https://developers.facebook.com/apps/
And choose Add New App, then “For Everything Else”. Give it a name (“Ad Library App” or whatever will do), then click Create App ID. You’ll probably have to complete a CAPTCHA.
A page showing your app’s settings will open. From the left menu choose Settings, then Basic. Copy and paste the following to a text editor for reference:
- The App ID (numeric)
- The App Secret (click Show, then copy it)
That’s all you need to do in this portal. Assuming the app will only be used for you to access the API, you don’t need to progress the setup here any further.
Step 2 – Get a Token
Now you have an App, you can create an Access Token – linked to both that app and your account – which allows you to access the API. This can be done from the online UI. Open the API Explorer:
https://developers.facebook.com/tools/explorer/
On the right side, make sure your new App is selected under “Facebook App”. Permissions can be left as “public_profile”. Under “User or Page” choose “Get User Access Token”.
A longish token will appear at the top, headed “Access Token”. Copy that to your file of credentials.
At this point, you could use the token to start fetching ad information – but this token is only valid for one hour, so it’ll soon become useless and require you to repeat this step. Instead, exchange it for a Long-Lived token.
Step 3 – Get a Long-Lived Token
By exchanging this token you can get one that’s valid for approximately 60 days. To do that, send a GET to
https://graph.facebook.com/v5.0/oauth/access_token
With the parameters:
- grant_type = fb_exchange_token
- client_id = (the App ID)
- client_secret = (the App Secret)
- fb_exchange_token = (the token from Step 2)
Via CURL, that’s:
curl -i -X GET “https://graph.facebook.com/v5.0/oauth/access_token?
grant_type=fb_exchange_token&
client_id={app-id}&
client_secret={app-secret}&
fb_exchange_token={your-access-token}”
This returns you the long-lived token that you should use from now on. After 60 days you will need to repeat steps 2 to 3, fetching a short-lived login token and exchanging it.
Step 4 – Get Ads
Now that you have a token that won’t expire for a while, you’re finally ready to start fetching some adverts. The basic call is a GET request to:
https://graph.facebook.com/v5.0/ads_archive
And the full list of parameters can be found here. In short, though, I usually send the following:
- access_token = (long lived token from Step 3)
- ad_type = POLITICAL_AND_ISSUE_ADS
- ad_reached_countries = [‘GB’,’US’]
- ad_active_status = (INACTIVE or ACTIVE)
- search_terms =
- search_page_ids =
Either search_terms (“Lewisham”) or search_page_ids (numeric ID) is required.
The “fields” parameter allows you to specify many data points. I usually request quite a lot:
[‘impressions, ad_creation_time, ad_creative_body, ad_creative_link_caption, ad_creative_link_description, ad_creative_link_title, ad_delivery_start_time, ad_delivery_stop_time, ad_snapshot_url, currency, demographic_distribution, funding_entity, page_id, page_name, region_distribution, spend’]