Geography Targeting

This article describes resources that enable you to read and define geographic location targeting.

Overview

Use geography targeting to target specific areas by geographic locations (geos) and points of interest (pois) or by defining a virtual fence of given radius around a set of addresses (geoFencings). If targeting specific areas is not ideal, however, geography targeting also offers the option to target every country in the world (isAllCountriesTargeted).

The Yahoo DSP supports GEOGRAPHY targeting for lines serving display, video, and native ads participating in Exchanges and Private Marketplace.

• Lines participating in Exchanges and Private Marketplace (supplyType = THIRD_PARTY) can target consumers by geos of type country, state, city, metro area, sub region, region, DMA, zip/postal code and postcode prefix, or by geofencings.

Important

• A line can be activated only if at least one geography targeting option such as geos, geoFencings or pois is enabled. Alternatively, the isAllCountriesTargeted field can be set to true to specify that the line is intended to serve across the world.

• Only one targeting option can be used on a line. Choose between geos and pois, geoFencings, or isAllCountriesTargeted as options.

Endpoint

/traffic/lines/{id}/targeting

• A GET request enables you to view geos targeted by the specified line.

• A POST request enables you to target geos with the specified line.

Resources

The targeting resource is the standard Yahoo DSP resource for targeting consumers based on their profiles, behaviors, and ad content.

The targeting resource is defined by the following GEOGRAPHY targeting type-specific fields:

Note

For a complete list of targeting resource fields, refer to Targeting Object.

Geo

The geo payload object specifies the Geographic (Country/State/DMA/City/Metro Area/Sub Region/Region, Zip, PostCode Prefix) resources to add, remove, or clear from line targeting.

Geos Included Object

The geosIncluded object contains included geographic locations.

Geos Excluded Object

The geosExcluded objects contains excluded geographic locations.

Geo Fencing

The geoFencing payload object specifies the Geo Fencing resources to add, remove, or clear from line targeting.

Points of Interest (POI)

The pois payload object specifies the Points of Interest resources to add, remove, or clear from line targeting.

Read Geos to Target

Returns a list of geo objects that may be targeted.

GET /traffic/targeting/geos?query={query}&countryCode={countryCode}&sort={sort}&dir={dir}

All of the accepted parameters are query parameters.

Parameters

Response Fields

The response contains the following fields of interest:

Sample Request URL (Without Country)

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/geos?query=san+francisco&sort=name&dir=desc

Sample Response (Partial)

{
  "response": [
    {
      "id": "###san francisco####zac#mex",
      "name": "San Francisco, Zacatecas, Mexico",
      "description": "san francisco, zac",
      "level": "City",
      "key": "san francisco_zacatecas_9786",
      "code": "157937",
      "woeid": "132570",
      "countryISO3": "mex",
      "geoLookupContext": {
        "country": "mex",
        "state": "zac",
        "subLocality": null,
        "locality": null,
        "majorMetroArea": null,
        "city": "san francisco",
        "postcode": null,
        "postcodePrefix": null,
        "dma": null,
        "dmaLong": null
      }
    },
    {
      "id": "807########usa",
      "name": "San Francisco-oakland-san Jose",
      "description": "san francisco-oakland-san jose",
      "level": "Dma",
      "key": "807",
      "code": "807",
      "woeid": "24701119",
      "countryISO3": "usa",
      "geoLookupContext": {
        "country": "usa",
        "state": null,
        "subLocality": null,
        "locality": null,
        "majorMetroArea": null,
        "city": null,
        "postcode": null,
        "postcodePrefix": null,
        "dma": "807",
        "dmaLong": 807
      }
    }
  ],
  "errors": null,
  "timeStamp": "2017-10-17T18:21:26Z"
}

Sample Request URL (USA)

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/geos?countryCode=usa&query=9512

Sample Response (Partial)

{
  "response": [
    {
      "id": "#95123##san jose####ca#usa",
      "name": "95123",
      "level": "Zip",
      "key": "#95123#######usa",
      "code": "12797574",
      "woeid": "12797574",
      "countryISO3": "usa",
      "geoLookupContext": {
        "country": "usa",
        "state": "ca",
        "subLocality": "",
        "locality": "",
        "majorMetroArea": "",
        "city": "san jose",
        "postcode": "95123",
        "postcodePrefix": "",
        "dma": "",
        "dmaLong": null
      }
    },
    {
      "id": "#79512##colorado city####tx#usa",
      "name": "79512",
      "level": "Zip",
      "key": "#79512#######usa",
      "code": "12792659",
      "woeid": "12792659",
      "countryISO3": "usa",
      "geoLookupContext": {
        "country": "usa",
        "state": "tx",
        "subLocality": "",
        "locality": "",
        "majorMetroArea": "",
        "city": "colorado city",
        "postcode": "79512",
        "postcodePrefix": "",
        "dma": "",
        "dmaLong": null
      }
    }
  ],
  "errors": null,
  "timeStamp": "2017-10-18T04:31:49Z"
}

Sample Request URL (Canada)

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/geos?countryCode=can&query=k1b

Sample Response (Partial)

{
  "response": [
    {
      "id": "#k1b 4g1##gloucester####on#can",
      "name": "k1b 4g1",
      "level": "Zip",
      "key": "#k1b 4g1#######can",
      "code": "24003609",
      "woeid": "24003609",
      "countryISO3": "can",
      "geoLookupContext": {
        "country": "can",
        "state": "on",
        "subLocality": "",
        "locality": "",
        "majorMetroArea": "",
        "city": "gloucester",
        "postcode": "k1b 4g1",
        "postcodePrefix": "",
        "dma": "",
        "dmaLong": null
      }
    },
    {
      "id": "##k1b######can",
      "name": "k1b",
      "level": "Postcode Prefix",
      "key": "##k1b######can",
      "code": "k1b",
      "woeid": "24003856",
      "countryISO3": "can",
      "geoLookupContext": {
        "country": "can",
        "state": null,
        "subLocality": null,
        "locality": null,
        "majorMetroArea": null,
        "city": null,
        "postcode": null,
        "postcodePrefix": "k1b",
        "dma": null,
        "dmaLong": null
      }
    }
  ],
  "errors": null,
  "timeStamp": "2020-11-10T08:11:26.028Z"
}

Read Countries to Target

Returns a list of countries that may be targeted by a line.

GET /traffic/targeting/countries?query={query}

All of the accepted parameters are query parameters.

Parameters

Response Fields

The response contains the following fields of interest:

Sample Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/countries?query=usa

Sample Response (Partial)

{
  "response": [
    {
      "id": "########usa",
      "name": "United States",
      "description": "united states of america/usa",
      "level": "Country",
      "key": "usa",
      "code": "840",
      "woeid": "23424977",
      "countryISO3": "usa",
      "geoLookupContext": {
        "country": "usa",
        "state": null,
        "subLocality": null,
        "locality": null,
        "majorMetroArea": null,
        "city": null,
        "postcode": null,
        "postcodePrefix": null,
        "dma": null,
        "dmaLong": null
      }
    }
  ],
  "errors": null,
  "timeStamp": "2017-10-18T04:03:17Z"
}

Add/Update Geo Targeting

Add new Geographic targeting for the specified line.

POST /traffic/lines/{id}/targeting

The targeting type and all changes are specified in the body of the application/json payload.

Parameters

The line ID is specified in the path of the URL. All other parameters are specified in the body of the application/json payload.

Sample Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting

Sample Request Body

{
  "geos": {
    "removedNames": [],
    "clearAll": false,
    "added": [
      {
        "excluded": false,
        "name": "#######15#nor"
      },
      {
        "excluded": true,
        "name": "###callahan####fl#usa"
      },
      {
        "excluded": false,
        "name": "##k2a######can"
      }
    ]
  },
  "types": [
    {
      "name": "GEOGRAPHY",
      "isTargeted": true
    }
  ]
}

Sample Response

{
  "response": {
    "types": [
      {
        "name": "GEOGRAPHY",
        "id": 4,
        "isTargeted": true
      }
    ],
    "geosIncluded": [
      {
        "id": "########usa",
        "name": "United States",
        "description": "united states of america/usa",
        "level": "Country",
        "key": "usa",
        "excluded": false
      },
      {
        "id": "#######15#nor",
        "name": "More Og Romsdal, Norway",
        "description": "more og romsdal",
        "level": "State",
        "key": "15, nor",
        "excluded": false
      },
      {
        "id": "##k2a######can",
        "name": "k2a",
        "level": "Postcode Prefix",
        "key": "##k2a######can",
        "excluded": false
      }
    ],
    "geosExcluded": [
      {
        "id": "###callahan####fl#usa",
        "name": "Callahan, Florida",
        "description": "callahan, fl",
        "level": "City",
        "key": "callahan, florida",
        "excluded": true
      }
    ]
  },
  "isAllCountriesTargeted": false,
  "errors": null,
  "timeStamp": "2019-10-20T04:42:46Z"
}

Add/Update Geofencing Targeting

Add or update Geo Fencing targeting for the specified line.

POST /traffic/lines/{id}/targeting

Parameters

All parameters are specified in the body of the application/json payload:

Sample Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting

Sample Request Body

{
  "id": 365277,
  "geoFencings": {
    "clearAll": false,
    "removed": [
    ],
    "added": [
      {
        "location": "328 Lomita Dr, Stanford, CA 94305"
      },
      {
        "location": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"
      }
    ],
    "radius": 5,
    "radiusUnit": "MILES"
  },
  "types": [
    {
      "name": "GEOGRAPHY",
      "isTargeted": true
    }
  ]
}

Sample Response

{
  "response": {
    "types": [
      {
        "name": "GEOGRAPHY",
        "id": 4,
        "isTargeted": true
      }
    ],
    "geoFencingsIncluded": [
      {
        "id": 1140763,
        "country": "United States",
        "location": "1600 Amphitheatre Pkwy, Mountain View, CA 94043",
        "latitude": 37.42307,
        "longitude": -122.08414,
        "radius": 5,
        "radiusUnit": "MILES"
      },
      {
        "id": 1140764,
        "country": "United States",
        "location": "328 Lomita Dr, Stanford, CA 94305",
        "latitude": 37.43249,
        "longitude": -122.17034,
        "radius": 5,
        "radiusUnit": "MILES"
      }
    ]
  },
  "isAllCountriesTargeted": false,
  "errors": null,
  "timeStamp": "2019-10-20T04:42:46Z"
}

Add/Update POI Targeting

Add or update Point of Interest targeting for the specified line.

POST /traffic/lines/{id}/targeting

The targeting type and all changes are specified in the body of the application/json payload.

Parameters

Sample Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting/

Sample Request Body

{
  "pois": {
    "clearAll": false,
    "removed": [],
    "added": [
      {
        "entityId": 1270,
        "poiLocationType": "Chain"
      },
      {
        "entityId": 2341,
        "poiLocationType": "Chain"
      },
      {
        "entityId": 96935912,
        "poiLocationType": "Category"
      },
      {
        "entityId": 91569812,
        "poiLocationType": "Venue"
      }
    ],
    "radiusType": "MILES_10"
  },
  "types": [
    {
      "name": "GEOGRAPHY",
      "isTargeted": true
    }
  ]
}

Sample Response

{
  "response": {
    "types": [
      {
        "name": "GEOGRAPHY",
        "id": 4,
        "isTargeted": true
      }
    ],
    "poisIncluded": [
      {
        "entityId": 1270,
        "radius": 16093,
        "name": "Starbucks Coffee",
        "poiLocationType": "Chain",
        "radiusType": "MILES_10"
      },
      {
        "entityId": 2341,
        "radius": 16093,
        "name": "Cinemark Theaters",
        "poiLocationType": "Chain",
        "radiusType": "MILES_10"
      },
      {
        "entityId": 91569812,
        "radius": 16093,
        "name": "Busch Gardens Tampa Bay",
        "poiLocationType": "Woe",
        "radiusType": "MILES_10"
      },
      {
        "entityId": 96935912,
        "radius": 16093,
        "name": "Baby Apparel",
        "poiLocationType": "Category",
        "radiusType": "MILES_10"
      }
    ]
  },
  "isAllCountriesTargeted": false,
  "errors": null,
  "timeStamp": "2019-10-20T04:42:46Z"
}

Target All Countries

To serve a line across the world, set the isAllCountriesTargeted field to true.

POST /traffic/lines/{id}/targeting

Sample Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/2294449/targeting/

Sample Request Body

{
    "isAllCountriesTargeted": true
}

Sample Response

{
  "response": {
    "types": [
      {
        "name": "GEOGRAPHY",
        "id": 4,
        "isTargeted": false
      }
    ],
    "isAllCountriesTargeted": true
  },
  "errors": null,
  "timeStamp": "2022-09-22T08:13:34.436Z"
}

Note

If you attempt to enable any other geography targeting along with isAllCountriesTargeted set to true, the request will fail.

Sample Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/2294449/targeting

Sample Request Body

{
  "isAllCountriesTargeted": true,
  "geos": {
    "removedNames": [],
    "clearAll": false,
    "added": [
      {
        "excluded": false,
        "name": "#######15#nor"
      }
    ]
  },
  "types": [
    {
      "name": "GEOGRAPHY",
      "isTargeted": true
    }
  ]
}

Sample Response

{
  "response": null,
  "errors": {
    "httpStatusCode": 422,
    "message": null,
    "validationErrors": [
      {
        "message": "Targeting 'All Countries' with other location targeting features is not allowed.",
        "propertyName": "isAllCountriesTargeted"
      }
    ]
  },
  "timeStamp": "2022-09-22T08:18:32.592Z"
}

Additional Resources

About Targeting