A Meta Ad Library API client for Rust.

This project is in active development, and it will currently fail on data that is not captured in its model (since we want to know as soon as possible if the API is providing data that we are not modeling). It has been tests on hundreds of searches and tens of thousands of ads, but it is likely to fail on some requests.

In order to use this project, you will need to confirm your identity with Meta, create a Meta for Developers account, and add a new app (see Meta's onboarding documentation for details).

Once you've created an app, you should confirm that you are able to make requests against the /ads_archive endpoint through the Graph API Explorer (with the path ads_archive?search_terms='chess'&ad_reached_countries=['DE'], for example). Note that the "User or Page" field should be set to "User Token".

The Graph API Explorer will give you a User Access Token that you can use here, but it will only last a few hours. You can upgrade this short-lived token to a long-lived token by running the following commands (replacing 123, XXX, and ABC):

> cargo build --release
> target/release/meta-ads-access -vvvv upgrade-token --app-id 123 --app-secret XXX --token ABC > creds.toml

Note that you will need to have installed Rust on your system for this to work. You can find your app's ID and "secret" by going to the dashboard and selecting "App settings > Basic". You can paste the short-lived token from the Graph API Explorer, but note that it must be active at the time the upgrade request is made.

If the command above succeeds, your new long-lived token will be saved to a creds.toml file in your current directory. This file will be used by default for all future API requests.

This project provides a client for the Ads Archive search API, and also supports scraping the Ads Library HTML pages directly.

Both kinds of requests support an --output option that saves detailed information about requests and responses. These archived request-response pairs can be parsed later using other commands.

If you've compiled the project and set up your credentials, you can run the following command (the -vvv verbosity will log details about pagination requests):

$ target/release/meta-ads-access -vvv search --output data/search/ --terms "ai chess"

This particular search currently takes around four minutes to run, will make around 190 pagination requests, and returns around 4,700 ads.

See the CLI documentation for more information about search options:

Perform a search (possibly paginated) and print the ad IDs, page IDs, and page names as CSV

Usage: meta-ads-access search [OPTIONS] --terms <TERMS>

Options:
      --creds <CREDS>              [default: creds.toml]
  -v, --verbose...                 Level of verbosity
      --version <VERSION>          [default: 24.0]
      --terms <TERMS>
      --country <COUNTRY>          [default: DE]
      --exact
      --after <AFTER>              Optional pagination token
      --output <OUTPUT>            Archive directory to log requests and responses to [default: data/search]
      --limit <LIMIT>              Limit to a specified number of pages
      --full                       Download full ad information
      --full-output <FULL_OUTPUT>  Archive directory to log full requests and responses to [default: data/library]
      --delay <DELAY>              Optional duration (in seconds) between requests [default: 0]
  -h, --help                       Print help

If you've used the --output command while making searches, you can parse the archived data (without making new requests) using the search-archive command:

$ target/release/meta-ads-access -vvv search-archive --data data/search/ | head
576535441426103,157817344084965,Chessiverse
589129136845222,1834313933459789,BBC StoryWorks
551290891182597,367754219763901,writer_kalyani
1059818455891627,104986081671617,it.com Domains
3839155272998853,108227973861366,Miko
1734255410761430,108227973861366,Miko
1292315335117015,669389136462669,Social Discovery Group
1224569318778818,105486451504054,Chessnut
1068754781111526,268914469632645,Patriticpttic
484518928069113,268914469632645,Patriticpttic

Once you have a list of ad IDs (the first column returned by the commands in the previous section), you can scrape and extract data from the Ads Library HTML pages for these ads.

$ target/release/meta-ads-access -vvv library-ad --output data/library/ --id 576535441426103

You can also use the library-ads command to run requests for a batch of ad IDs provided on standard input (one numeric ID per line). Both commands will save the requests and responses to the provided --output directory.

You can then run the following command to list the contents of that directory:

$ target/release/meta-ads-access -vvv library-archive --data data/library/

This will print CSV rows where the columns are the ad ID, the advertiser page ID, the ad link, the advertiser page profile image URL, and an ad preview URL.

This software is licensed under the GNU General Public License v3.0 (GPL-3.0).