fbads

https://travis-ci.org/rpedigoni/fbads.png

Python client for the Facebook Ads API. Under development!

Note

The Ads API is a restricted platform which may only be accessed by whitelisted Apps. You can learn more about the program and apply online. You need to apply separately for each app.

Documentation:

Installation

At the command line:

$ pip install fbads

Then check the installation:

$ python -c "import fbads; print fbads.__version__"
0.3.2

Ad campaigns

Create an ad campaign

fbads.campaign.add(name, campaign_status)

Add a new campaign to the ad account

Parameters:
  • name (str) – Campaign name
  • campaign_status (str) – CampaignStatus.ACTIVE or CampaignStatus.INACTIVE (from fbads.resources.campaign.CampaignStatus)
Return type:

An ad campaign ID (str)

Example:

from fbads import FBAds
from fbads.resources.campaign import CampaignStatus

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

campaign_id = api.campaign.add(
    name=u'Testing campaign #001',
    campaign_status=CampaignStatus.ACTIVE,
)

print u'Campaign created with ID {0}'.format(campaign_id)

List campaigns

fbads.campaign.list([limit])

List all account campaigns.

Parameters:limit (int) – An optional limit
Return type:list of CampaignResource

Example:

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

for campaign in api.campaign.list(fields=['name'], limit=10):
    print campaign.name

Remove an ad campaign

fbads.campaign.delete(campaign_id)

Remove an ad campaign from the ad account

Parameters:campaign_id (long) – Campaign ID
Return type:True

Example:

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

print api.campaign.delete(123456787654321)  # returns True

Ad creatives

Create an ad creative

fbads.creative.add(title, body, object_url, image_url, actor_id=None)

Add a new creative to the ad account

Parameters:
  • name (str) – Creative title
  • body (str) – Body (ad text)
  • object_url (str) – Target URL
  • image_url (str) – Ad image URL
  • actor_id (str) – An optional Facebook Object ID (eg.: a page)
Return type:

An ad creative ID (str)

Example:

from fbads import FBAds

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

creative_id = fbads.creative.add(
    title=u'Test creative',
    body=u'Testing creative creation! Lorem ipsum here.',
    object_url='http://fbads.readthedocs.org/en/latest/index.html',
    image_url='https://d1dhh18vvfes41.cloudfront.net/417x300/051057500.jpg',
)

print u'Creative created with ID {0}'.format(creative_id)

List creatives

fbads.creative.list([fields, limit])

List all ad creatives.

Parameters:
  • fields (list) – Fields to be retrieved
  • limit (int) – An optional limit
Return type:

list of CreativeResource

Example:

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

for creative in api.creative.list(fields=['title'], limit=10):
    print creative.title

Remove an ad creative

fbads.creative.delete(creative_id)

Removes an ad creative from the ad account

Parameters:creative_id (str) – Creative ID
Return type:True

Example:

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

print api.creative.delete('123456787654321')  # returns True

Ad groups

Create an ad group

fbads.group.add(name, bid_type, bid_info, set_id, creative_id, targeting_specs)

Add a new ad group to the ad account

Parameters:
  • name (str) – Ad group name
  • bid_type (BidType) – BidType.CPC, BidType.CPM, BidType.MULTI_PREMIUM, BidType.ABSOLUTE_OCPM, BidType.CPA (from fbads.resources.group.BidType)
  • bid_info (BidInfo) – bid - must be an BidInfo (fbads.resources.group.BidInfo) instance (see the examples below)
  • set_id (str) – Ad set ID
  • creative_id (str) – Creative ID
  • targeting_specs (TargetingSpecs) – a TargetingSpecs (fbads.resources.group.TargetingSpecs) instances - see the examples below
Return type:

An ad group ID (str)

Note

There a few other attributes (tracking_specs, conversion_specs, view_tags) not mentioned here – take a look at fbads/managers/group.py if you need to use them

Example:

from decimal import Decimal
from fbads import FBAds
from fbads.resources.group import BidInfo, BidType, TargetingSpecs

fbads = FBAds(account_id='1234', access_token='a_valid_token')

targeting_specs = TargetingSpecs()

# target to one (or many) custom audiences
targeting_specs.add_custom_audience('a_custom_aud_id', 'a_custom_aud_name')
targeting_specs.add_custom_audience('a_custom_aud_id', 'a_custom_aud_name')

# you can exclude a specific custom audience
targeting_specs.exclude_custom_audience('a_custom_aud_id', 'a_custom_aud_name')

# and / or filter by age
targeting_specs.age_min = 18
targeting_specs.age_max = 35

# you *always* need to specify at least one country
# this is the only required targeting attribute
targeting_specs.countries = ['BR', 'US']

group_id = fbads.group.add(
    name=u'An ad group name',
    bid_type=BidType.CPC,
    bid_info=BidInfo.get(
        BidType.CPC,
        clicks=Decimal('0.25'),
    ),
    set_id='an_ad_set_id',
    creative_id='an_ad_creative_id',
    targeting_specs=targeting_specs,
)

print u'Created ad group with ID {0}'.format(group_id)

List ad groups

fbads.group.list([fields, limit])

List all ad groups.

Parameters:
  • fields (list) – Fields to be retrieved
  • limit (int) – An optional limit
Return type:

list of GroupResource

Example:

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

for group in api.group.list(fields=['name', 'bid_info'], limit=10):
    print u'{0}: bid is {1}'.format(group.name, group.bid_info)

Remove an ad group

fbads.group.delete(group_id)

Remove an ad group from the ad account

Parameters:group_id (str) – Group ID
Return type:True

Example:

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

print api.group.delete('14352345234523')  # returns True

Custom audiences

Note

Before using the Custom Audiences API you must accept the Terms of Service.

Creating a custom audience

fbads.customaudience.add(name, description=None, opt_out_link=None)

Add a new custom audience to the ad account

Parameters:
  • name (str) – Custom audience name
  • description (str) – Custom audience description
  • opt_out_link (str) – Custom audience description
Return type:

A custom audience ID (long)

Exemplo:

from fbads import FBAds

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

custom_audience_id = api.customaudience.add(
    name=u'Test custom audience',
    description='My custom audience',
)

print u'Custom audience created with ID {0}'.format(custom_audience_id)

Adding users

fbads.customaudience.add_users(customaudience_id, facebook_ids=[], emails=[])

You can add users using facebook_ids or e-mails. fbads will hash the e-mail list using md5.

Parameters:
  • customaudience_id (str) – Custom audience ID
  • facebook_ids (str) – List of Facebook IDs
  • emails (str) – List of emails – do not hash the email list, it will be done automatically
Return type:

True (hopefully!)

Exemplo:

from fbads import FBAds

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

api.customaudience.add_users(
    customaudience_id='12345678987654321',
    emails=[
        'example-01@email.com',
        'example-02@email.com',
        'example-03@email.com',
        # ...
    ],
)

# you cannot use emails and facebook_ids at the same time, so
api.customaudience.add_users(
    customaudience_id='12345678987654321',
    facebook_ids=[
        '12345678987001',
        '12345678987002',
        '12345678987003',
        # ...
    ],
)

Removing a custom audience

fbads.customaudience.delete(customaudience_id)

Removes a custom audience from the ad account

Parameters:customaudience_id (str) – Custom audience ID
Return type:True

Exemplo:

api = FBAds(
    account_id='1233',
    access_token='token_with_ads_permission',
)

api.customaudience.delete('123456787654321')

Indices and tables