Package: apple-searchads-api
Apple SearchAds APIThis is an updated version of the Phiture's searchads_api client.
New features include:Update cryptography library to compile on M1 machines.Add support for get Ads reports by dateInstallationpipinstallapple_searchads_apiAbout PhiturePhitureis a Berlin-based mobile growth consultancy working with the teams behind leading apps. Using the company’s industry-acclaimed Mobile Growth Stack as a strategic framework, Phiture team offers 4 key services: App Store Optimization, Apple Search Ads, User Retention services and Growth Consulting.Apple Searchads API Library in PythonIn order to facilitate the usage of the Apple Search Ads API Phiture's Engineers have built a library in Python which allows users to manage campaigns, ad groups, keywords and creative sets. This library only requires intermediate Python skills and therefore makes it possible not only for Engineers but also for Data Analysts and Apple Search Ads Consultants to work with it.  While the library is extensive it is not complete and users are encouraged to commit suggestions.
The official link to the searchads campaign management api ishttps://developer.apple.com/documentation/search_ads/Setup for V3 of the APICreate acertsdirectory inside your project folder, or create a different certs directory and specify it using thecertificates_dir_pathargument.fromsearchads_apiimportSearchAdsAPIapi=SearchAdsAPI(org_id=123456,pem="cert.pem",key="cert.key",certificates_dir_path="certs/",verbose=False)Setup for v4 of the APICreate acertsdirectory inside your project folder, or create a different certs directory and specify it using thecertificates_dir_pathargument.fromsearchads_apiimportSearchAdsAPIapi=SearchAdsAPI(org_id=123456,pem="",# Only needed for v3 of the APIkey="private.key",client_id="SEARCHADS.07875add-f6cd-4111-9c38-b84501d557c8",team_id="SEARCHADS.07879add-d6cd-4111-9c38-b84501d527c8",key_id="78a167b1-e423-4ab4-bcd1-8be75a4d7b7e",verbose=True)Available MethodsCampaign MethodsCreate a new campaignres = api.create_campaign(1433439534, ['AU'], "test", 1, 1, "EUR")Find campaigns using a conditions listres = api.find_campaigns(conditions=[{"field": "countriesOrRegions","operator": "CONTAINS_ALL","values": ["US", "CA"]}])Get a specific campaignres = api.get_campaign(283767149)Get all campaignsres = api.get_campaigns(limit=0)Update a campaignres = update_campaign(campaign_id, countries=None, campaign_name="Christmas Campaign 2019", budget=None, daily_budget=None, curruncy=None, status=None, adamId=None)Delete campaignres = api.delete_campaign(283767149)Adgroup MethodsCreate a new adGroup inside of a campaignres = api.create_adgroup(186370637, "test", "EUR",1, datetime.datetime.utcnow())
  
  res = api.create_adgroup(186370637, "test", "EUR",1, datetime.datetime.utcnow(), localities=["US|NY|New York"], adminAreas=["US|NY"])

   res = api.create_adgroup(campaign_id, adgroup_name, currency,
                 cpc_bid,  start_time, end_time=None, cpa_goal=None,  automated_keywords_opt_in=False, age=None, gender=None, device_class=None, day_part=None, adminArea=None, locality=None, appDownloaders=None)Fetch ad groups within a campaign.res = api.find_adgroups(campaign_id, limit=1000, offset=0, sort_field="id", sort_order="ASCENDING", conditions=[], fields=[])Get all adGroupsres = api.get_adgroups(290916652)Get a specific adGroupres = api.get_adgroups(290916652, 21321323)Update an Adgroupres = update_adgroup(campaign_id, adgroup_id, adgroup_name=None,                             cpa_goal=None, currency=None,
                 cpc_bid=None, start_time=None, end_time=None, automated_keywords_opt_in=False, age=None, gender=None, device_class=None,
                 day_part=None, adminArea=None, locality=None, appDownloaders=None)Delete an Adgroupres = delete_adgroup(campaign_id, adgroup_id)Targeting Keyword MethodsAdd new targeting keywords to an AdGroupkeywords = [{
           "text": "keyword",
           "matchType": "BROAD",
           "status" : "PAUSED",
           "bidAmount": {
               "amount": "1",
               "currency": "EUR"
           }
       }, {
           "text": "keyword 5",
           "matchType": "EXACT",
           "status" : "PAUSED",
           "bidAmount": {
               "amount": "1",
               "currency": "EUR"
           }
       }]
   res = api.add_targeting_keywords(290916652,291017295,keywords)Fetch keywords used in ad groups.res = find_targeting_keywords(campaign_id, adgroup_id, sort_field="id", sort_order="ASCENDING", conditions=[], offset=0, limit=1000)Get one targeting keywordres = api.get_targeting_keyword(290916652,291017295, 213213213)Get all targeting keywordsres = api.get_targeting_keywords(290916652,291017295)Update targeting keywords in an adGroupkeywords = [{
               "id": 291202529,
               "status": "PAUSED",
               "bidAmount": {
                   "amount": "0.5",
                   "currency": "EUR"
               }
               },
               {
               "id": 291202530,
               "status": "PAUSED",
               "bidAmount": {
                   "amount": "0.5",
                   "currency": "EUR"
               }
               }
               ]
   res = api.update_targeting_keywords(290916652, 291017295, keywords)Campaign Negative Keyword MethodsAdd new campaign negative keywordskeywords = [{
           "text": "keyword",
           "matchType": "BROAD",
           "status" : "PAUSED",
       }, {
           "text": "keyword 5",
           "matchType": "EXACT",
           "status" : "PAUSED",
       }]
   res = api.add_campaign_negative_keywords(290916652, keywords)Get a specific campaign negative keywordres = api.get_campaign_negative_keyword(290916652, 291225104)Get all campaign negative keywordsres = api.get_campaign_negative_keywords(290916652)Update campaign negative keywordskeywords = [{
           "id": "291225104",
           "status" : "PAUSED",
       }]
   res = api.update_campaign_negative_keywords(290916652, keywords)Delete campaign negative keywordskeywords = [291225104]
   res = api.delete_campaign_negative_keywords(290916652, keywords)Adgroup Negative Keyword MethodsAdd new adgroup negative keywordskeywords = [{
           "text": "keyword",
           "matchType": "BROAD",
           "status" : "PAUSED",
       }, {
           "text": "keyword 5",
           "matchType": "EXACT",
           "status" : "PAUSED",
       }]
   res = api.add_adgroup_negative_keywords(290916652, 291017295, keywords)Get a specific adGroup negative keywordres = api.get_adgroup_negative_keyword(290916652, 291017295, 291227741)Get all adgroup negative keywordsres = api.get_adgroup_negative_keywords(290916652,291017295)Update adGroup negative keywordskeywords = [{
       "id": "123456789",
       "status": "PAUSED",
   }]
   res = api.update_adgroup_negative_keywords(123456789, 291017295, keywords)Update a list of adGroup negative Keywordskeywords = [{
               "id": 0000000,
               "adGroupId": 291017295,
               "text": "test",
               "status": "PAUSED",
               "matchType": "EXACT",
               "bidAmount": {
                   "amount": "0.5",
                   "currency": "EUR"
               },
               "deleted": False
           }]
   res = api.update_targeting_keywords(290916652,291017295,keywords)Delete a list of AdGroup negative keywordskeyword_ids = [123456789]
   res = api.delete_adgroup_negative_keywords(290916652, 291017295, keyword_ids)Creativeset MethodsFetch assets used with Creative Sets.res = api.get_creativesets_assets(adam_id, countries_or_regions, assets_gen_ids=[])Fetch supported app preview device size mappings.res = api.get_app_preview_device_sizes()Create a new creativesetres = api.create_creativeset(campaign_id, adgroup_id, adamId, name, languageCode, assetsGenIds)Get all Creativesetsres = api.get_creativeset(campaign_id, adgroup_id=None, limit=1000, offset=0))Get a specific Creativesetsres = api.get_creativeset(creativeset_id, include_deleted_creative_set_assets=False)Update an Adgroup Creativesetres = api.update_creativeset(campaign_id, adgroup_id, creativeset_id, status)Assign a Creativeset to an Adgroupres = api.assign_creativeset_to_adgroup(campaign_id, adgroup_id, creativeset_id)Fetch all Creative Sets assigned to ad groups.conditions = [{
      "field": "id",
      "operator": "EQUALS",
      "values": [
      "11111111"
          ]
      }]
   res = api.find_adgroup_creativesets(campaign_id,conditions=conditions,         sort_field="id", sort_order="ASCENDING")Fetch all Creative Sets assigned to an organization.res = api.find_creativesets(conditions=[], limit=1000, offset=0)Fetch asset details of a Creative Set.res = api.get_creativeset(creativeset_id, include_deleted_creative_set_assets=False)Update a creativeset nameres = api.update_adgroup_creativeset_name(creativeset_id, name)Delete creative sets from a specified Adgroup
res = api.delete_creativesets(campaign_id, adgroup_id, ids)Reporting MethodsGet reports on campaigns within a specific org.res = api.get_adgroups_report_by_date("2019-04-01", "2019-04-10", 123456789, limit=5)Get reports on adgroups within a specific org.row, grandTotals = api.get_adgroups_report_by_date(123456789, "2019-02-20", "2019-02-28",limit=0)Get reports on creativeset level. limit 0 gets all results instead of just 1000row, grandTotals= api.get_creativesets_report_by_date(123456789, "2019-06-01", "2019-06-10")Get reports on keywords level. limit 0 gets all results instead of just 1000row, grandTotals = api.get_keywords_report_by_date(123456789, "2019-02-20", "2019-02-28",limit=0)Get reports on searchterms levelrow, grandTotals = api.get_searcherms_report_by_date(123456789,"2019-05-01", "2019-05-07",limit=0)Get reports on ads level with grand totals (without granularity):row,grandTotals=api.get_ads_report_by_date(123456789,"2019-05-01","2019-05-07",limit=0)Get reports on ads level with granularity set toDAILY:rows=api.get_ads_report_by_date(123456789,"2019-05-01","2019-05-07",return_row_totals=False,return_grand_totals=False,granularity="DAILY",limit=0)Geo SearchSearch Adminareasres = api.geo_search("New York", entity="AdminArea", country_code="US")Search Localitiesres = api.geo_search("New York", entity="Locality", country_code="US")Returns a list of admin areas in a country.res = api.get_admin_areas(country_code="US")Returns a list of localities in a country.res = api.get_localities(country_code)Gets geo location details based on geo identifier.res = api.get_geo_locations_list(geo_id,
                         entity,
                         limit=1000, offset=0)