API Reference

facebook_ad_library.client Module

class facebook_ad_library.client.FacebookAdsLibrary(access_token: str, api_version: str = 'v14.0')

Bases: object

A class for interacting with the Facebook Ads API.

Parameters:

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

• api_version (str) – The API version to be used (optional, default is “v14.0”).

api_url = None

default_api_version = 'v14.0'

default_url_pattern = 'https://graph.facebook.com/{api_version}/ads_archive?access_token={access_token}'

search(query: List[AdLibraryType] = None, fields: List[ADField] = None, limit: int = 20)

Performs a search in the Facebook Ads API.

Parameters:

• query (List[types.AdLibraryType]) – A list of search criteria (optional).

• fields (List[fields.ADField]) – A list of fields to retrieve (optional).

• limit (int) – The maximum number of results to return (optional, default is 20).

Returns:

The search results.

Return type:

dict

session = <requests.sessions.Session object>

facebook_ad_library.fields Module

class facebook_ad_library.fields.ADField

Bases: object

field_name = None

class facebook_ad_library.fields.AdCreationTime

Bases: ADField, str

field_name = 'ad_creation_time'

class facebook_ad_library.fields.AdCreativeBodies(iterable=(), /)

Bases: ADField, List[str]

field_name = 'ad_creative_bodies'

class facebook_ad_library.fields.AdCreativeLinkCaptions(iterable=(), /)

Bases: ADField, List[str]

field_name = 'ad_creative_link_captions'

class facebook_ad_library.fields.AdCreativeLinkDescriptions(iterable=(), /)

Bases: ADField, List[str]

field_name = 'ad_creative_link_descriptions'

class facebook_ad_library.fields.AdCreativeLinkTitles(iterable=(), /)

Bases: ADField, List[str]

field_name = 'ad_creative_link_titles'

class facebook_ad_library.fields.AdDeliveryStartTime

Bases: ADField, str

field_name = 'ad_delivery_start_time'

class facebook_ad_library.fields.AdDeliveryStopTime

Bases: ADField, str

field_name = 'ad_delivery_stop_time'

class facebook_ad_library.fields.AdSnapshotUrl

Bases: ADField, str

field_name = 'ad_snapshot_url'

class facebook_ad_library.fields.AgeCountryGenderReachBreakdown(values: List[AgeGenderReachBreakdown | dict], *args, **kwargs)

Bases: ADField, List[AgeGenderReachBreakdown]

field_name = 'age_country_gender_reach_breakdown'

class facebook_ad_library.fields.AgeGenderReachBreakdown(age_range: str = <factory>, female: int = <factory>, male: int = <factory>, unknown: int = <factory>)

Bases: object

age_range: str

female: int

male: int

unknown: int

class facebook_ad_library.fields.BeneficiaryPlayer(beneficiary: str = <factory>, current: bool = <factory>, payer: str = <factory>)

Bases: object

beneficiary: str

current: bool

payer: str

class facebook_ad_library.fields.BeneficiaryPlayers(values: List[BeneficiaryPlayer | dict], *args, **kwargs)

Bases: ADField, List[BeneficiaryPlayer]

field_name = 'beneficiary_payers'

class facebook_ad_library.fields.Bylines

Bases: ADField, str

field_name = 'bylines'

class facebook_ad_library.fields.Currency

Bases: ADField, str

field_name = 'currency'

class facebook_ad_library.fields.DeliveryByRegion(values: List[AudienceDistribution | dict], *args, **kwargs)

Bases: ADField, List[AudienceDistribution]

field_name = 'delivery_by_region'

class facebook_ad_library.fields.DemographicDistribution(values: List[AudienceDistribution | dict] = [], *args, **kwargs)

Bases: ADField, List[AudienceDistribution]

field_name = 'demographic_distribution'

class facebook_ad_library.fields.EstimatedAudienceSize(lower_bound: str = <factory>, upper_bound: str = <factory>)

Bases: ADField, InsightsRangeValue

field_name = 'estimated_audience_size'

class facebook_ad_library.fields.EuTotalReach

Bases: ADField, int

field_name = 'eu_total_reach'

class facebook_ad_library.fields.Impressions(lower_bound: str = <factory>, upper_bound: str = <factory>)

Bases: ADField, InsightsRangeValue

field_name = 'impressions'

class facebook_ad_library.fields.Languages(iterable=(), /)

Bases: ADField, List[str]

field_name = 'languages'

class facebook_ad_library.fields.LibraryId

Bases: ADField, int

field_name = 'id'

class facebook_ad_library.fields.PageId

Bases: ADField, str

field_name = 'page_id'

class facebook_ad_library.fields.PageName

Bases: ADField, str

field_name = 'page_name'

class facebook_ad_library.fields.PublisherPlatformsField(iterable=(), /)

Bases: ADField, List[str]

field_name = 'publisher_platforms'

class facebook_ad_library.fields.Spend(lower_bound: str = <factory>, upper_bound: str = <factory>)

Bases: ADField, InsightsRangeValue

field_name = 'spend'

class facebook_ad_library.fields.TargetAges(iterable=(), /)

Bases: ADField, List[str]

field_name = 'target_ages'

class facebook_ad_library.fields.TargetGender

Bases: ADField, str

field_name = 'target_gender'

class facebook_ad_library.fields.TargetLocations

Bases: ADField, str

field_name = 'target_locations'

facebook_ad_library.types Module

class facebook_ad_library.types.AdActiveStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: AdLibraryType, Enum

ACTIVE = 'ACTIVE'

ALL = 'ALL'

INACTIVE = 'INACTIVE'

class facebook_ad_library.types.AdDeliveryDateMax(date: date, date_str_format: str = '%Y-%m-%d')

Bases: AdDateType

date: date

date_str_format: str = '%Y-%m-%d'

class facebook_ad_library.types.AdDeliveryDateMin(date: date, date_str_format: str = '%Y-%m-%d')

Bases: AdDateType

date: date

date_str_format: str = '%Y-%m-%d'

class facebook_ad_library.types.AdLibraryType

Bases: object

class facebook_ad_library.types.AdReachedCountries(values: List[facebook_ad_library.types.ad_reached_countries.AdReachedCountry] = <factory>)

Bases: AdLibraryType

values: List[AdReachedCountry]

class facebook_ad_library.types.AdReachedCountry(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

AD = 'AD'

AE = 'AE'

AF = 'AF'

AG = 'AG'

AI = 'AI'

AL = 'AL'

ALL = 'ALL'

AM = 'AM'

AN = 'AN'

AO = 'AO'

AQ = 'AQ'

AR = 'AR'

AS = 'AS'

AT = 'AT'

AU = 'AU'

AW = 'AW'

AX = 'AX'

AZ = 'AZ'

BA = 'BA'

BB = 'BB'

BD = 'BD'

BE = 'BE'

BF = 'BF'

BG = 'BG'

BH = 'BH'

BI = 'BI'

BJ = 'BJ'

BL = 'BL'

BM = 'BM'

BN = 'BN'

BO = 'BO'

BQ = 'BQ'

BR = 'BR'

BS = 'BS'

BT = 'BT'

BV = 'BV'

BW = 'BW'

BY = 'BY'

BZ = 'BZ'

CA = 'CA'

CC = 'CC'

CD = 'CD'

CF = 'CF'

CG = 'CG'

CH = 'CH'

CI = 'CI'

CK = 'CK'

CL = 'CL'

CM = 'CM'

CN = 'CN'

CO = 'CO'

CR = 'CR'

CV = 'CV'

CW = 'CW'

CX = 'CX'

CY = 'CY'

CZ = 'CZ'

DE = 'DE'

DJ = 'DJ'

DK = 'DK'

DM = 'DM'

DO = 'DO'

DZ = 'DZ'

EC = 'EC'

EE = 'EE'

EG = 'EG'

EH = 'EH'

ER = 'ER'

ES = 'ES'

ET = 'ET'

FI = 'FI'

FJ = 'FJ'

FK = 'FK'

FM = 'FM'

FO = 'FO'

FR = 'FR'

GA = 'GA'

GB = 'GB'

GD = 'GD'

GE = 'GE'

GF = 'GF'

GG = 'GG'

GH = 'GH'

GI = 'GI'

GL = 'GL'

GM = 'GM'

GN = 'GN'

GP = 'GP'

GQ = 'GQ'

GR = 'GR'

GS = 'GS'

GT = 'GT'

GU = 'GU'

GW = 'GW'

GY = 'GY'

HK = 'HK'

HM = 'HM'

HN = 'HN'

HR = 'HR'

HT = 'HT'

HU = 'HU'

ID = 'ID'

IE = 'IE'

IL = 'IL'

IM = 'IM'

IN = 'IN'

IO = 'IO'

IQ = 'IQ'

IS = 'IS'

IT = 'IT'

JE = 'JE'

JM = 'JM'

JO = 'JO'

JP = 'JP'

KE = 'KE'

KG = 'KG'

KH = 'KH'

KI = 'KI'

KM = 'KM'

KN = 'KN'

KR = 'KR'

KW = 'KW'

KY = 'KY'

KZ = 'KZ'

LA = 'LA'

LB = 'LB'

LC = 'LC'

LI = 'LI'

LK = 'LK'

LR = 'LR'

LS = 'LS'

LT = 'LT'

LU = 'LU'

LV = 'LV'

LY = 'LY'

MA = 'MA'

MC = 'MC'

MD = 'MD'

ME = 'ME'

MF = 'MF'

MG = 'MG'

MH = 'MH'

MK = 'MK'

ML = 'ML'

MM = 'MM'

MN = 'MN'

MO = 'MO'

MP = 'MP'

MQ = 'MQ'

MR = 'MR'

MS = 'MS'

MT = 'MT'

MU = 'MU'

MV = 'MV'

MW = 'MW'

MX = 'MX'

MY = 'MY'

MZ = 'MZ'

NA = 'NA'

NC = 'NC'

NE = 'NE'

NF = 'NF'

NG = 'NG'

NI = 'NI'

NL = 'NL'

NO = 'NO'

NP = 'NP'

NR = 'NR'

NU = 'NU'

NZ = 'NZ'

OM = 'OM'

PA = 'PA'

PE = 'PE'

PF = 'PF'

PG = 'PG'

PH = 'PH'

PK = 'PK'

PL = 'PL'

PM = 'PM'

PN = 'PN'

PR = 'PR'

PS = 'PS'

PT = 'PT'

PW = 'PW'

PY = 'PY'

QA = 'QA'

RE = 'RE'

RO = 'RO'

RS = 'RS'

RU = 'RU'

RW = 'RW'

SA = 'SA'

SB = 'SB'

SC = 'SC'

SE = 'SE'

SG = 'SG'

SH = 'SH'

SI = 'SI'

SJ = 'SJ'

SK = 'SK'

SL = 'SL'

SM = 'SM'

SN = 'SN'

SO = 'SO'

SR = 'SR'

SS = 'SS'

ST = 'ST'

SV = 'SV'

SX = 'SX'

SZ = 'SZ'

TC = 'TC'

TD = 'TD'

TF = 'TF'

TG = 'TG'

TH = 'TH'

TJ = 'TJ'

TK = 'TK'

TL = 'TL'

TM = 'TM'

TN = 'TN'

TO = 'TO'

TR = 'TR'

TT = 'TT'

TV = 'TV'

TW = 'TW'

TZ = 'TZ'

UA = 'UA'

UG = 'UG'

UM = 'UM'

US = 'US'

UY = 'UY'

UZ = 'UZ'

VA = 'VA'

VC = 'VC'

VE = 'VE'

VG = 'VG'

VI = 'VI'

VN = 'VN'

VU = 'VU'

WF = 'WF'

WS = 'WS'

XK = 'XK'

YE = 'YE'

YT = 'YT'

ZA = 'ZA'

ZM = 'ZM'

ZW = 'ZW'

class facebook_ad_library.types.AdType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: AdLibraryType, Enum

ALL = 'ALL'

CREDIT_ADS = 'CREDIT_ADS'

EMPLOYMENT_ADS = 'EMPLOYMENT_ADS'

HOUSING_ADS = 'HOUSING_ADS'

POLITICAL_AND_ISSUE_ADS = 'POLITICAL_AND_ISSUE_ADS'

class facebook_ad_library.types.AudienceDistribution(age: str = <factory>, gender: str = <factory>, percentage: str = <factory>, region: str = <factory>)

Bases: object

age: str

gender: str

percentage: str

region: str

class facebook_ad_library.types.Bylines(searches: list = <factory>)

Bases: AdArray

class facebook_ad_library.types.DeliveryByRegion(searches: list = <factory>)

Bases: AdArray

class facebook_ad_library.types.EstimatedAudienceSizeMax(value: int = <factory>)

Bases: AdInt

class facebook_ad_library.types.EstimatedAudienceSizeMin(value: int = <factory>)

Bases: AdInt

class facebook_ad_library.types.InsightsRangeValue(lower_bound: str = <factory>, upper_bound: str = <factory>)

Bases: object

lower_bound: str

upper_bound: str

class facebook_ad_library.types.Languages(searches: list = <factory>)

Bases: AdArray

class facebook_ad_library.types.MediaType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: AdLibraryType, Enum

ALL = 'ALL'

IMAGE = 'IMAGE'

MEME = 'MEME'

NONE = 'NONE'

VIDEO = 'VIDEO'

class facebook_ad_library.types.PublisherPlatform(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: AdLibraryType, Enum

AUDIENCE_NETWORK = 'AUDIENCE_NETWORK'

FACEBOOK = 'FACEBOOK'

INSTAGRAM = 'INSTAGRAM'

MESSENGER = 'MESSENGER'

OCULUS = 'OCULUS'

WHATSAPP = 'WHATSAPP'

class facebook_ad_library.types.PublisherPlatforms(values: List[facebook_ad_library.types.publisher_platform.PublisherPlatform] = <factory>)

Bases: AdLibraryType

values: List[PublisherPlatform]

class facebook_ad_library.types.SearchPageIds(searches: list = <factory>)

Bases: AdArray

class facebook_ad_library.types.SearchTerms(value: str = <factory>)

Bases: AdStr

class facebook_ad_library.types.SearchType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: AdLibraryType, Enum

KEYWORD_EXACT_PHRASE = 'KEYWORD_EXACT_PHRASE'

KEYWORD_UNORDERED = 'KEYWORD_UNORDERED'

class facebook_ad_library.types.TargetLocation(excluded: bool = <factory>, name: str = <factory>, num_obfuscated: int = <factory>, type: str = <factory>)

Bases: object

excluded: bool

name: str

num_obfuscated: int

type: str

class facebook_ad_library.types.UnmaskRemovedContent(value: bool = <factory>)

Bases: AdBool

facebook_ad_library.exceptions Module

class facebook_ad_library.exceptions.ExceptionData(message: str = <factory>, code: int = <factory>, error_subcode: int = <factory>, is_transient: bool = <factory>, error_user_title: str = <factory>, error_user_msg: str = <factory>, fbtrace_id: str = <factory>)

Bases: object

code: int

error_subcode: int

error_user_msg: str

error_user_title: str

fbtrace_id: str

is_transient: bool

message: str

exception facebook_ad_library.exceptions.OAuthException(error: dict, *args, **kwargs)

Bases: Exception

error: ExceptionData = None