facebookresearch / ad-library-api-script-repository

GitHub repository of commonly used python scripts that allows everyone to pull data via the Ad Library API

Ads-Library-API-Script-Repository

Ads-Library-API-Script-Repository is a set of code examples to help user/researchers understand how the Facebook Ads Library API works. It also provides a simple command-line interface(CLI) for users to easily use the Facebook Ads Library API.

Examples

Here's an example on how to use the CLI:

$ python fb_ads_library_api_cli.py -t {access_token} -f 'page_id,ad_snapshot_url,funding_entity,ad_delivery_start_time' -c 'CA' -s '.' -v count

It would count the number of all polictical ads in CA(Canada);

Note: please replace the '{access_token}' with your Facebook Developer access token.

Requirements

Ads-Library-API-Script-Repository requires or works with

• Mac OS X or Linux or Window
• Python 3.0+
• Python Requests Library (installation)
• Python iso3166 Library (installation)

How Ads-Library-API-Script-Repository works

The script will query the Facebook Ads library API to get all the Ads Library information on the Facebook platform;

Full documentation

You can find the full documentation here: (--to-be-added--)

More about Facebook Ads Library

• Website: https://www.facebook.com/ads/library
• Report: https://www.facebook.com/ads/library/report
• API: https://www.facebook.com/ads/library/api

See the CONTRIBUTING file for how to help out.

License

Ads-Library-API-Script-Repository is licensed under the Facebook Platform License, as found in the LICENSE file.

ad-library-api-script-repository's Issues

Alyssa Carson

Beta

https://github.com/topics/github-config

App permissions and features clarification

Can you please clarify what app permissions and features are needed to access ads library data via the API? I'm very confused trying to debug failures. I don't know if I'm doing something wrong or if I don't have the permissions and features needed to access the ads library via the graph API.

Alyssa Carson

The API can't give back more than 40k results.

Either I run this script or use my own solution, I just can't get more than 40 thousand results back. After reaching 40k records, the API drops an exception: {"code": 1, "message": "An unknown error occurred"}]

Is there a way to fix this?

Thanks

Sociales

@

How to find page ids from URL?

I'm trying to look at the ads run by specific pages (~200 of them). I have these in the form of URLs of pages.

I have this working once I have the page id, but I can't figure out an automated way of finding the page id from a URL.

Any tips?

Thank you!

Is it possible to access Demographics Data of any user's ads??

I want to access the demographics data of any defined keyword like laptop,mobile or shirt.The data is visible in all inactive ads and shows the number of reach.Let Me Know If its possible.

The demographic data needed can be found here

Generating app_token

Currently I generate an access token in pretty much the same steps as @skylarcheung outline's here however I'd like to try to do this programatically instead of manually every 60 days. With access to the app id and secret, what call would I need to make to get the token, and then extend it?

Currently trying the following to get the token:
response = requests.get(f"https://graph.facebook.com/oauth/access_token?client_id={app_id}&client_secret={app_secret}&grant_type=client_credentials")
but the returned app_token does not work when I try to pull political ads data or try to extend it:
second_response = requests.get(f"https://graph.facebook.com/oauth/access_token?client_id={app_id}&client_secret={app_secret}&grant_type=fb_exchange_token&fb_exchange_token={app_token}")

(I am verified and when I manually generate the token and extend it I am able to pull ads without issue)

Application does not have permission for this action. Can't get account verified.

My FB account has completed the verification process, it looks complete, but I never got a chance to request a code (the one that is mailed to you) and now I can't access this part of the API because I get "Application does not have permission for this action" which supposedly happens when your account is not fully verified.

Does anybody know where or how to request the code so they can mail it to you? Or what other issue could be causing this error message....

How can i use Meta Ad Library API with African countries

Hello,

I would like to inquire about conducting research on ads in African countries like Ivory Coast, Nigeria, Niger, Senegal, South Africa, Cameroon, and others. Upon my observation, it appears that these countries are not currently supported. I'm curious to know if this limitation is due to an outdated version of the platform or if there is a possibility for me to manually add the necessary code for these countries.

Thank you for your assistance.

Best regards,

What does count_start_time_trending actually do?

The comment says "output the count trending of ads by start date;
Accept one parameters:
output_file: path to write the csv". What does this mean?

Jordan Safe Country

Application doesn't have permission for this

Is this an access token issue or something else? Can someone help out? My ID is confirmed too.

{"error":{"message":"Application does not have permission for this action","type":"OAuthException","code":10,"error_subcode":2332002,"is_transient":false,"error_user_title":"Authorization and login needed","error_user_msg":"To access the API, you'll need to follow the steps at facebook.com\/ads\/library\/api.","fbtrace_id":"AdnFHKk6D9J0eBf10RJY3FU"}}%

Do we need to give any specific permissions? I tried ads_read and ads_management.

Query issue

Hi,
Has anyone else run into this issue before ?
Traceback (most recent call last):
File "C:\Ad-Library-API-Script-Repository-main\python\fb_ads_library_api_cli.py", line 147, in
main()
File "C:\Ad-Library-API-Script-Repository-main\python\fb_ads_library_api_cli.py", line 138, in main
get_operators()[opts.action](
File "C:\Ad-Library-API-Script-Repository-main\python\fb_ads_library_api_operators.py", line 35, in count_ads
for ad_archives in generator_ad_archives:
File "C:\Ad-Library-API-Script-Repository-main\python\fb_ads_library_api.py", line 80, in _get_ad_archives_from_url
start_time_cutoff_after = datetime.strptime(after_date, "%Y-%m-%d").timestamp()
OSError: [Errno 22] Invalid argument

Here is the query that i ran :
py fb_ads_library_api_cli.py -t (access-token) -f "id,page_id,page_name,spend,demographic_distribution,bylines" -c "CA" -s "." --after-date "2023-07-01" save_to_csv data.csv

Further extract or download ad creative such as images and text for an individual ad

The result of the API query is somewhat very abstract, and it seems the ad_snapshot_url is temporary link.
I tries to make a query of an individual ad but I have got the error below. Anyone who might have an idea about the root cause?
I have both pages_read_engagement permission and pages_read_user_content permission added before making the call.

Error :
{
    "error": {
        "message": "(#10) This endpoint requires the 'pages_read_engagement' permission or the 'Page Public Content Access' feature or the 'Page Public Metadata Access' feature. Refer to https://developers.facebook.com/docs/apps/review/login-permissions#manage-pages, https://developers.facebook.com/docs/apps/review/feature#reference-PAGES_ACCESS and https://developers.facebook.com/docs/apps/review/feature#page-public-metadata-access for details.",
        "type": "OAuthException",
        "code": 10,
        "fbtrace_id": "Ay1JovtZ_DRs3e1SX3rksWA"
    }
}

Filter by "before-date"?

I was wondering if it's possible to filter by "before-date" in addition to the "after-date"? The description here seems to suggest that one could use "ad_delivery_date_max", but I wasn't sure how to do it.

Unsupported fields: 'page_id,ad_delivery_start_time'

I follow the document and try the example in read.md

python fb_ads_library_api_cli.py -t {access_token} -f 'page_id,ad_snapshot_url,funding_entity,ad_delivery_start_time' -c 'CA' -s '.' -v count
but an error occured and says

usage: fb_ads_library_api_cli.py [-h] -t ACCESS_TOKEN -f FIELDS [-s SEARCH_TERM] -c COUNTRY [--search-page-ids SEARCH_PAGE_IDS] [--ad-active-status AD_ACTIVE_STATUS] [--after-date AFTER_DATE] [--batch-size BATCH_SIZE] [--retry-limit RETRY_LIMIT] [-v] action ... fb_ads_library_api_cli.py: error: argument -f/--fields: Unsupported fields: 'page_id,ad_delivery_start_time'

Is there a way to fix this?

Thanks

Meta Ad Library API does not return any ad for some page and also not return same data as it shows on ads library

I have connected my application into Facebook Ad Library API using https calls.
It is working fine on some pages. but in some other pages it does not return all pages ads or in some it does not return any! but when you take a look at the page itself in the Facebook Ad Library Website. It is showing the page ads.
An example of this would be Hunger Games page which is at url https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&view_all_page_id=159746560708670&search_type=page&media_type=all and you can see that it is displaying more than 20 ads in the page but when you try to get its ads from the Ads Library API. it returns {"data":[]}

Is verification by passport or ID absolutely required for this API?

 curl -G \
-d "search_terms='california'" \
-d "ad_type=ALL" \
-d "ad_reached_countries=['US']" \
-d "access_token=EAA<.........>" \
"https://graph.facebook.com/v17.0/ads_archive"

===>

{"error":{
  "message":"Application does not have permission for this  action",
  "type":"OAuthException",
  "code":10,
  "error_subcode":2332002,
  "is_transient":false,
  "error_user_title":"Authorization and login needed",
  "error_user_msg":"To access the API, you'll need to follow the steps at facebook.com\/ads\/library\/api.",
  "fbtrace_id":"<...>"}
}

I don't understand - will I have to verify my personal account by passport or ID to then be permitted to use this API?

Or what's this error about?

Anh

PermissionError: [Errno 13] Permission denied:

Hello,

I am running this command on my terminal :

C:\Ad-Library-API-Script-Repository-main\python> py fb_ads_library_api_cli.py -t (token) -f "id,page_id,page_name,ad_creative_bodies,spend,demographic_distribution,bylines,ad_delivery_start_time" -c "CA" -s "climate" --after-date "2024-05-01" save_to_csv file.csv

And I get the following error :

Traceback (most recent call last):
File "C:\Ad-Library-API-Script-Repository-main\python\fb_ads_library_api_cli.py", line 147, in
main()
File "C:\Ad-Library-API-Script-Repository-main\python\fb_ads_library_api_cli.py", line 134, in main
save_to_csv(
File "C:\Ad-Library-API-Script-Repository-main\python\fb_ads_library_api_operators.py", line 96, in save_to_csv
with open(output_file, "w") as csvfile:
^^^^^^^^^^^^^^^^^^^^^^
PermissionError: [Errno 13] Permission denied.

I have tried adding "encoding="utf-8" in the fb_ads_library_api_operators file, but it didn't work (i am able to get one dataset then i get the same error all over again)

Does anyone have a solution ? i'm not sure I understand how the Permission system works in the Graph Api.

Un equipo

https://github.com/facebook

Alyssa Carson

Why is only POLITICAL_AND_ISSUE_ADS available for ad_type?

https://www.facebook.com/ads/library/api/

Please reduce the amount of data you're asking for, then retry your request?

Hi, I get the following error after getting 32,000 ads:

{'error': {'code': 1,
'message': "Please reduce the amount of data you're asking for, then retry your request"}}

Can you explain what it means and how I can overcome this, as I am trying to gather all ads published within a given time interval of start and stop dates?

It's not clear how I can "cut" my query in chunks since that was what the paging is already supposed to do, right?

Thanks.

somlegal

Any update following to release note?

Hi,

I found that some parameters are not updated to the recent Graph API version (e.g., 13.0) which includes funding entity, ad_creativity_ body, etc. Do you have any plan to manage this repository?

Best,

Scraping Date Range specific data

I want to include ads from 2016. Is there any way to scrap by a particular date? or maybe specifying a date range as after_date and before_Date?

Access Token Required?

Is the access token required by the -t argument a User, App or Page access token?

Alyssa Carson

Hello world💙💙💙

Hi @frapierri!

          Hi @frapierri! 

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

Originally posted by @facebook-github-bot in #19 (comment)

Application does not have permission for this action

I get access token from: https://developers.facebook.com/tools/accesstoken

python fb_ads_library_api_cli.py -t <access token> -f 'page_id,ad_snapshot_url,ad_delivery_start_time' -c 'HU' -s '""' --ad-active-status 'ALL' --batch-size '5000' -v save 'output-.json'

And I get the following error, can someone do what I can to run cli?

{
    "error": {
        "message": "Application does not have permission for this action",
        "type": "OAuthException",
        "code": 10,
        "error_subcode": 2332002,
        "is_transient": false,
        "error_user_title": "Authorization and login needed",
        "error_user_msg": "To access the API, you'll need to follow the steps at facebook.com/ads/library/api.",
        "fbtrace_id": "AOxlW9wwYGgl5evOXSPcbiD"
    }
}

How to get Instagram username/ID of advertiser?

/ads_archive - does return Facebook page ID of an advertiser, but not Instagram ID/username.

Web desktop version does include Instagram info - example link

How to get username/ID of advertiser?