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='v20.0', project_name='20251212193839')

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 “v18.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.

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 for tracking the progress. Default is 1.

Example::

>>> url = "https://graph.facebook.com/v18.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='2025-12-12', 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 the file containing page IDs. 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, page_id, page_name, target_ages, target_gender, target_locations, eu_total_reach, age_country_gender_reach_breakdown', '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,
page_id, page_name, target_ages, target_gender, target_locations, eu_total_reach, age_country_gender_reach_breakdown'