Skip to content

fbertola/searchads-api

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Apple Search Ads Python API

Install instructions

  1. Install the library with pip, running pip install search_ads
  2. Go to: https://app.searchads.apple.com/cm/app/settings/apicertificates and download the certificates
  3. Unzip the certificates
  4. Create in the root of your Python project a text file called .env as follows:
SEARCH-ADS-PEM='<pem certificate full path>'
SEARCH-ADS-KEY='<key certificate full path>'

Alternatively you can set environment variables or use the set_env function as shown in the last example of this page.

What can you do now?

  • Edit Campaigns attributes
  • Edit AdGroups attributes
  • Edit Keywords attributes (*)
  • Add / Pause (*) keywords
  • Work with reports (campaign, adgroup, keywords, search terms)
  • Create a Campaign
  • Create an Ad Group

(*) Note that editing keywords / removing keywords / removing campaigns operations are not allowed by the search ads v1 api. Where implemented they are implicitly translated as pausing the old keyword and creating a new one.

Objects & methods quick ref:

  • SearchAds
    • get_campaigns
    • get_campaigns_by_name
    • get_campaign_keywords_report
    • get_campaign_searchterms_report
    • get_campaign_adgroups_report
    • get_campaign_report
    • create_campaign
  • Campaign
    • pause
    • activate
    • get_ad_group_by_name
    • save
  • AdGroup
    • pause
    • activate
    • save
  • Keyword
    • pause
    • unpause
    • prepare_for_bulk_export

Campaigns, AdGroups and Keywords have various properties that you can edit. If you want to save all the changes done inside a campaign (including on its adgroups) simply call save(cascade=True) on it.

As always, when in doubt type help() or on any object you want to know more about

Sample usage

from search_ads import SearchAds

api = SearchAds("MyCompany")  # Our company account
campaign = api.get_campaigns_by_name('MyCampaing')[0]
ad_group = campaign.get_ad_group_by_name('Brand')

campaign.name = 'change my name!'
campaign.save()

ad_group.default_cpc_bid = '0.05'  # Amounts are strings

ad_group.keywords[0].text += "ss"
ad_group.keywords[0].bid_amount['amount'] = '0.6'
ad_group.save()  # Equivalently: campaign.save(cascade=True)

Reports

from search_ads import SearchAds

api = SearchAds("MyCompany")  # Our company account
campaign = api.get_campaigns_by_name('MyCampaign')[0]
print(api.get_campaign_adgroups_report(campaign))

Output:

     adGroupId        adGroupName  avgCPA  avgCPT  bidAmount  conversionRate  ...
0      123456  Generic Keywords     0.0     0.0       0.05             0.0
1      123456  Generic Keywords     0.0     0.0       0.05             0.0
2      123456  Generic Keywords     0.0     0.0       0.05             0.0
...

Create a campaign, an ad group and add a keyword

from search_ads import SearchAds
from search_ads import Campaign, Keyword, AdGroup

api = SearchAds("MyCompany")  # Our company account

campaign = api.create_campaign(
    campaign_name="fb test", # Campaign name
    ad_group_name="fb adGroup test", # AdGroup name
    app_id=284882215, # This should be a valid ID, this is facebook
    automatic_keywords_opt_in=False, # True if you want apple to choose keywords for you
    default_cpc_bid=1, # Default CPC bid in dollars (can be a float)
    budget=100, # Total budget for the campaign
    daily_budget=100 # Daily budget for the campaign
)

ad_group = campaign.ad_groups[0]
ad_group.keywords.append(
    Keyword(
        adGroupId = ad_group._id, # The id of the AdGroup
        text = "facebook", # The keyword text
        status = "ACTIVE", # Is the keyword active or paused?
        matchType = "EXACT", # Is the match broad or exact?
        bidAmount = {"amount":"1","currency":"USD"} # Bid amount object
    )
)
ad_group.save()

Advanced Usage and Synchronization

This library also offers ways to programmatically set the certificates and to batch-downloads reports (using time windows) to a local cache that can be later used for further analysis

from search_ads import SearchAds, DataBase
from search_ads import set_env
from search_ads import Keyword, Campaign, AdGroup, SyncManager

import pandas as pd
certs = {
    "SEARCH-ADS-PEM": "<path-to-your-pem>",
    "SEARCH-ADS-KEY": "<path-to-your-key>",
}

with set_env(**certs):
    api = SearchAds("MyCompany")
    campaigns=api.get_campaigns_by_name("MyApp")
    s = SyncManager(certs)
    for campaign in campaigns:
        campaign.set_sync_manager(s)
    print(campaigns)

    # Let's apply changes that won't be immediately written to the APIs
    for campaign in campaigns:
        campaign.name = 'pippo'  # Probably you don't want to do this..
        campaign.save()  # We are committing the changes to a local storage

    # Now it's time to write all our changes to our search ads account
    s.synchronize()

    # Let's now work with reports, downloading hourly data for all of our campaigns,
    # search terms, keywords and ad groups.
    db = DataBase()
    # This will take a while as it stores locally all the report data
    api.store_reports(campaigns, db)

# Let's find the daily average CPA per keyword over time
# Note that we have hourly data about this so we resample by day and average
df = db.reports[campaigns[0]]['keywords']
df.index = pd.to_datetime(df['date'])
df.groupby(['keyword', pd.TimeGrouper('D')])[['avgCPA']].mean()

And read/play with the DataFrame in output.

Enjoy!

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages