AdLibAPI Module

This module provides the AdLibAPI class, which allows interaction with the Meta Ad Library API.

AdLibAPI.__init__ Method

AdLibAPI.__init__(access_token, version='v25.0', project_name='20260706090921')

Initialize the AdLibAPI object by providing a valid Meta developer token and a project name.

Parameters:

• access_token (str) – The access token for authentication.

• version (str) – The version of the Meta Ad Library API. Default is “v25.0”.

• project_name (str) – The name of the project. Default is the current date and time.

Example:

>>> from AdDownloader import adlib_api
>>> access_token = input() # your fb-access-token-here
>>> ads_api = adlib_api.AdLibAPI(access_token, project_name = "test1")

AdLibAPI.fetch_data Method

AdLibAPI.fetch_data(url, params, page_ids=None, page_number=1)

Fetch and process data based on the provided URL and parameters. Pagination is handled iteratively (rather than via recursion) so it doesn’t hit Python’s recursion limit on searches spanning many pages. Each page is retried up to three times with exponential back-off before the download stops.

Parameters:

• url (str) – The URL for making the API request.

• params (dict) – The parameters to include in the API request.

• page_ids (str) – Page IDs for naming output files. Default is None.

• page_number (int) – The page number to start from (used for file naming). Default is 1.

Example::

>>> url = "https://graph.facebook.com/v25.0/ads_archive"
>>> params = ads_api.get_parameters()
>>> ads_api.fetch_data(url, params)

AdLibAPI.add_parameters Method

AdLibAPI.add_parameters(fields=None, ad_reached_countries='NL', ad_delivery_date_min='2023-01-01', ad_delivery_date_max='2026-07-06', search_page_ids=None, search_terms=None, ad_type='ALL', **kwargs)

Add parameters for the API request. Mandatory parameters are reached countries, start and end date, and either page_ids or search_terms. See available parameters here: https://developers.facebook.com/docs/marketing-api/reference/ads_archive/

Parameters:

• fields (str) – The fields to include in the API response. Default is None, fields are retrieved from the created AdLibApi object.

• ad_reached_countries (str) – The reached country for ad targeting. Default is ‘NL’.

• ad_delivery_date_min (str) – The minimum start date of ad delivery. Default is “2023-01-01”.

• ad_delivery_date_max (str) – The maximum start date of ad delivery. Default is the current date.

• search_page_ids (str) – The name of an Excel or CSV file (with a page_id column) containing page IDs, located inside the data folder. Default is None. Complementary with search_terms.

• search_terms (str) – The search terms for ad filtering, in one string separated by a comma. Default is None. Complementary with search_page_ids.

• ad_type (str) – The type of the ads to be retrieved. Default is “ALL”, can also be “POLITICAL_AND_ISSUE_ADS”.

• kwargs** – Add additional parameters for the search query, e.g. “estimated_audience_size_max = 10000”

Example::

>>> # add only required parameters
>>> ads_api.add_parameters(ad_reached_countries = 'NL', ad_delivery_date_min = "2023-09-01", ad_delivery_date_max = "2023-09-02", search_terms = "pizza")
>>> # can also add additional parameters
>>> ads_api.add_parameters(ad_reached_countries = 'US', ad_delivery_date_min = "2023-02-01", ad_delivery_date_max = "2023-03-01", ad_type = "POLITICAL_AND_ISSUE_ADS",
             ad_active_status = "ALL", estimated_audience_size_max = 10000, languages = 'es', search_terms = "Biden")

AdLibAPI.start_download Method

AdLibAPI.start_download(params=None)

Start the download process from the Meta Ad Library API based on the provided parameters.

Parameters:

params (dict) – The parameters for the API request. Default is None, parameters are retrieved from the created AdLibApi object.

Returns:

A dataframe containing the downloaded and processed ad data from the Meta Online Ad Library.

Return type:

pandas.Dataframe

Example::

>>> data = ads_api.start_download()
>>> print(data.head(1))
      id ad_delivery_start_time ad_delivery_stop_time  ... unknown_45-54 unknown_55-64 unknown_65+
0  11111             2023-06-30            2024-01-09  ...          21.0           5.0        11.0

AdLibAPI.get_parameters Method

AdLibAPI.get_parameters()

Get the parameters used for the API request (without the access token).

Returns:

A dictionary containing the parameters for the API request.

Return type:

dict

Example::

>>> ads_api.get_parameters()
{'fields': 'id, ad_delivery_start_time, ad_delivery_stop_time, ad_creative_bodies, ad_creative_link_captions, ad_creative_link_descriptions, ad_creative_link_titles, ad_snapshot_url, beneficiary_payers, bylines, languages, page_id, page_name, publisher_platforms, target_ages, target_gender, target_locations, eu_total_reach, age_country_gender_reach_breakdown, total_reach_by_location', 'ad_reached_countries': 'BE', 'search_page_ids': None, 'search_terms': 'pizza', 'ad_delivery_date_min': '2023-09-01', 'ad_delivery_date_max': '2023-09-02', 'limit': '300', 'access_token': 'XX'}

AdLibAPI.get_fields Method

AdLibAPI.get_fields(ad_type)

Get the default fields for the API request, depends on the type of ads to be retrieved (All or Political). For available fields visit https://www.facebook.com/ads/library/api

Parameters:

ad_type (str) – The type of the ads to be retrieved.

Returns:

A string containing the fields for the API request.

Return type:

str

Example::

>>> ads_api.get_fields(ad_type = "ALL")
'id, ad_delivery_start_time, ad_delivery_stop_time, ad_creative_bodies, ad_creative_link_captions, ad_creative_link_descriptions, ad_creative_link_titles, ad_snapshot_url,
beneficiary_payers, bylines, languages, page_id, page_name, publisher_platforms, target_ages, target_gender, target_locations, eu_total_reach,
age_country_gender_reach_breakdown, total_reach_by_location'