Discover v201109: Filtering on Criterion type

We’ve noticed a popular question in the forum: “How do I retrieve criteria of a specific type via the API?”. Previously, there was no straightforward way to filter by the criterion type on the server side and the only workaround was to retrieve all criteria and process the list on the client side.

In v201109 we introduced a new filterable field called ‘CriteriaType’ to the Criterion object. For example, the following request will return criteria of types ‘KEYWORD’ and ‘PLACEMENT’ only:

<get>
  <serviceSelector>
    <fields>Id</fields>
    <fields>CriteriaType</fields>
    <predicates>
      <field>CriteriaType</field>
      <operator>IN</operator>
      <values>KEYWORD</values>
      <values>PLACEMENT</values>
    </predicates>
  </serviceSelector>
</get>

You can find out the list of available criteria types in the documentation.

We hope this enhancement will make it easier to work with criteria. Please visit the forum or join our Google+ Hangout today if you have any questions regarding this change.

Danial Klimkin, AdWords API Team.

Discovering v201109: How to target Campaigns

With the introduction of v201109 we’ve made some changes in the AdWords API with regards to targeting campaigns.  This blog post will discuss these changes in detail.

From CampaignTargets to Criterion

Targeting campaigns in v201109 is now accomplished via the CampaignCriterionService. Previously, the CampaignTargetService had a large number of CampaignTargets that could be used to better direct who saw your ads. For v201109, almost all of these targets have been transformed into Criterion objects and moved to the CampaignCriterionService.

Some of these criteria can only be targeted (CampaignCriterion) or only excluded (NegativeCampaignCriterion).  The individual criteria are documented as to whether they are targetable-only or excludable-only on their individual documentation pages.  The table below shows a comparison between the old CampaignTargets and their respective Criterion as well as whether they are Targetable-only, Excludable-only or both.

Campaign Target	Criterion	Criterion Source	Targetable, Excludable
AdScheduleTarget	No change, continue to use CampaignTargetService		No change
AgeTarget	AgeRange	reference list	Excludable only
GenderTarget	Gender	reference list	Excludable only
CityTarget, CountryTarget, MetroTarget, ProvinceTarget	Location	reference lists or LocationCriterionService	Targetable and Excludable
PolygonTarget	Polygon	GeoLocationService	Deprecated, cannot be added
ProximityTarget	Proximity	GeoLocationService	Targetable only
LanguageTarget	Language	reference list or ConstantDataService	Targetable only
MobileCarrierTarget	Carrier	reference list or ConstantDataService	Targetable only
MobilePlatformTarget	OperatingSystemVersion	reference list	Targetable only
PlatformTarget	Platform	reference list	Targetable only

A rose by any other name (or ID)

Please note that except for Proximity Criteria, we have changed all these targeting criteria to work with IDs instead of names.  This allows us to update the text of display values without requiring developers to change their applications.  Below is an example of the old and new ways to represent LanguageTarget/Language.

Old
<targets>
 <Target.Type>LanguageTarget</Target.Type>
 <languageCode>en</languageCode>
</targets>

New
<criterion xsi:type="Language">
 <id>1000</id>
 <type>LANGUAGE</type>
 <Criterion.Type>Language</Criterion.Type>
 <code>en</code>
</criterion>


Note that the “New” example shows the Language Criterion as it would be returned by the API.  When sending the value to the API, you only need to specify id and xsi:type, all other fields are ignored and read-only and documented as such.

We hope this blog post helps you as you update your application with the new Campaign Criteria.  If you have any questions about this service or how to use it, please post on the forum or try to attend our Google+ Hangouts with members of the AdWords API Developer Relations Team.

Kevin Winter, AdWords API Team

Discover v201109: Changes to accounts identification

The AdWords API allows you to manage a large number of accounts using a single login credential set. In order to determine which account to run a query against, a customer identifier is required.

Previously we allowed the use of either client email address or client customer ID as account identifier. Using email addresses does not handle a number of situations, though, such as address change, multiple accounts associated with one email and others. In addition, AdWords accounts created with no email address are just not accessible by this identifier.

In order to unify account identification we decided to remove support for email addresses as account identifiers starting with v201109. From this version onward only client customer IDs are supported by the AdWords API.

Migrating to client customer ID

Most applications managing more than one AdWords account hold account identifiers in some form of a local storage. In case your application uses client email addresses as identifiers, you will need to convert those to client customer IDs, or add an extra field for the IDs.

In order to make this migration smoother, we’ve provided an example that demonstrates how to obtain a client ID for a given email address. This example is included in every client library and also available online.

It is easy to change how you identify a client account when making API requests if you use our client libraries. Depending on the language you use, you will need to update the configuration file or constructor parameter to include clientCustomerId instead of clientEmail. In case you construct your queries manually, please refer to the SOAP headers documentation page for more details.

We would like to remind you that all existing versions that support identification by email addresses are scheduled for shutdown in Feb 2012.


Please join us on forum or in our upcoming Google+ Hangouts if you have any questions regarding this change.

Danial Klimkin, AdWords API Team.

Discovering v201109: ConstantDataService

We’ve released the ConstantDataService as a new service with v201109.  This blog post will talk about what it is used for as well as suggest some best practices.

The ConstantDataService currently has two web service methods available: getCarrierCriterion and getLanguageCriterion.  These methods return Carrier and Language criteria respectively.  These criteria can be used with the CampaignCriterion to get more fine-grained control of the targeting of your campaigns.  This functionality replaces the CampaignTargetService’s LanguageTarget and MobileCarrierTarget.

Previously, we published lists of these targets/criteria in static files on code.google.com as the sole way to get a list of possible options.  With the ConstantDataService, we are now exposing these values programmatically via the AdWords API.  As a result, your application can now dynamically obtain a list of options for these criteria.  Let’s see how to get a list of Carriers in Python.

# Initialize client object.
client = AdWordsClient(path=os.path.join('..', '..', '..', '..'))

# Initialize appropriate service.
constant_data_service = client.GetConstantDataService(
   'https://adwords-sandbox.google.com', 'v201109')

# Get all carriers.
carriers = constant_data_service.GetCarrierCriterion()

# Display results.
for carrier in carriers:
 print ('Carrier with name \'%s\', ID \'%s\', and country code \'%s\''
        ' was found.' % (carrier['name'], carrier['id'], carrier['countryCode']))

Output from this script would look like this:

Carrier with name 'NTT DoCoMo', ID '70000', and country code 'JP' was found.
Carrier with name 'KDDI/au', ID '70001', and country code 'JP' was found.
Carrier with name 'Vodafone', ID '70002', and country code 'JP' was found.
Carrier with name 'EMOBILE', ID '70003', and country code 'JP' was found.
Carrier with name 'WILLCOM', ID '70004', and country code 'JP' was found.
Carrier with name 'T-Mobile', ID '70030', and country code 'DE' was found.
[snip]

The dataset that the ConstantDataService exposes can now be easily updated while allowing your applications to dynamically stay up-to-date.  We do not expect the dataset to change often and we expect most changes to be additive in nature.  As a result, we strongly encourage caching this information rather than looking it up on demand.  For example, in Python, you could store this information in a pickle or a database and reuse it as necessary.

We hope you have found this post discussing the ConstantDataService and its use in obtaining Carrier and Language criteria to be informative.  If you have any questions about this service or how to use it, please post on the forum or try to attend our Google+ Hangouts with members of the AdWords API Developer Relations Team.

Kevin Winter, AdWords API Team

120 days until deprecation deadline

As we announced last month, with the release of AdWords API v201109, we will be deprecating the following versions and services:

• API versions v13, v200909, v201003, v201008, v201101*
• API version v13 AccountService will only be available on a whitelist basis.

*Note: We are not supporting cross-client reports in this release, but we have released some sample code for single account reporting across many clients.

We will be sunsetting these versions and services on February 29, 2012.

To help with the migration, we’ll be running a “Discover v201109” blog series, as well as hosting Google+ Hangouts with members of the AdWords API Developer Relations Team.

In addition, as with every new version of the AdWords API, we encourage you to review the resources in the AdWords API client libraries. If you have any questions please post them on the AdWords API forum.

Finally, we may send out periodic service announcements via email on the deprecation timeline and resources to migrate to v201109. Please be sure that your contact information is up to date in your My Client Center account. Review this blog post for more details.
 
Posted by Katie Miller, AdWords API Team