We’ve heard some questions recently about the degree that geotargeting is supported through our API. Let’s explore how geotargeting can be managed through the DFA API.

First, here’s a reminder about how geotargeting works in the DoubleClick for Advertisers product. As explained in this help center article (DFA sign-in required), combining multiple locations even if they are within different geographic categories always results in an “OR” relationship between them. Targeting the countries Mexico and the United States alongside the Canadian province of Ontario will cause your ad to be displayed if the impression originates from the United States or Mexico or Ontario.

Let’s see how this example plays out through the API. We need to use the State and Country classes. These classes contain extra fields that are filled in with descriptions when the objects are returned from our server. You only need to fill in the id field when you send us an object that represents a target criterion for an ad. As explained on our best practices page, our ID numbers rarely change and caching them locally is always a good idea. If you have to retrieve them, reference our example code and the ad service documentation.

Once you have the numbers, you can retrieve your ad from our server and add the desired targets. For example, this Python code will add the United States, Mexico, and Ontario as desired targets to an ad:

# Get the ad that needs geotargeting added.
ad = ad_service.GetAd(targetable_ad_id)[0]

# Create and add country targeting criteria.
country_targeting_criteria = {
    'exclude': 'False',
    'countries': [{'id': UNITED_STATES_COUNTRY_ID}, 
                  {'id': MEXICO_COUNTRY_ID}]
ad['countryTargetingCriteria'] = country_targeting_criteria

# Add state targeting. Provinces are considered states.
ad['states'] = [{'id': ONTARIO_STATE_ID}]

# Save changes. This ad now serves only when an impression originates from 
# the United States, Mexico, or Ontario.
ad_save_result = ad_service.SaveAd(ad)[0]

Remember that only ad types that extend TargetableAdBase are targetable. If you run into any problems or have questions about targeting through the API, we’d be glad to help on our forum.