- 15 Minutes to read
Geography Targeting
- 15 Minutes to read
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 bygeos
of type country, state, city, metro area, sub region, region, DMA, zip/postal code and postcode prefix, or bygeofencings
.
Important
A line can be activated only if at least one geography targeting option such as
geos
,geoFencings
orpois
is enabled. Alternatively, theisAllCountriesTargeted
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
andpois
,geoFencings
, orisAllCountriesTargeted
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:
Field | Description | Data Type |
---|---|---|
| Specifies the line ID. |
|
| Specifies geographic locations (Country/State/DMA/City/Metro Area/Sub Region/Region, Zip, PostCode Prefix) to target or block from targeting.
Note: You cannot target both geographic locations and geofencing locations at the same time. |
|
| Specifies geo fencing locations to target or block from targeting. To create or update targeted geo fencing locations, refer to Geo Fencing. Note: You cannot target both geographic locations and geofencing locations at the same time. |
|
| Specifies points of interest resources to target within the set geographic locations.
Note: You cannot target both points of interest resources and geofencing locations at the same time. POI is only supported in the United States. |
|
| Specifies the option to target every country in the world. When this field is set to
|
|
| A read-only array of targeted geo locations which are marked as Included. Refer to Geo Payload. |
|
| A read-only array of targeted geo locations which are marked as Excluded. Refer to Geo Payload. |
|
| A read-only array of targeted geofencing locations. |
|
| A read-only array of targeted POI locations. |
|
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.
Field | Description | Data Type |
---|---|---|
| An array of geos to target. This is an array of objects containing the following required fields:
|
|
| An array of unique Geo location names to be removed from targeting. |
|
| Indicates if all existing Geo locations should be removed.
|
|
Geos Included Object
The geosIncluded
object contains included geographic locations.
Field | Description | Data Type |
---|---|---|
| Unique ID of the location. |
|
| Specifies the geofencing country name. |
|
| Specifies the radius of the geo fence. |
|
| Specifies the units used to measure the radius. Options include:
|
|
Geos Excluded Object
The geosExcluded
objects contains excluded geographic locations.
Field | Description | Data Type |
---|---|---|
| Unique ID of the location. |
|
| Specifies the geofencing country name. |
|
| Specifies the radius of the geo fence. |
|
| Specifies the units used to measure the radius. Options include:
|
|
Geo Fencing
The geoFencing
payload object specifies the Geo Fencing resources to add, remove, or clear from line targeting.
Field | Description | Data Type |
---|---|---|
| An array of geofencing addresses to target. This is an array of objects containing the following required fields:
|
|
| An array of unique geofencing IDs to remove from targeting. |
|
| Indicates if all existing geofencing locations should be removed.
|
|
| Specifies the radius of the geo fence. This is how far away a user can be from each address and still be targeted. |
|
| Specifies the unit of the
|
|
Points of Interest (POI)
The pois
payload object specifies the Points of Interest resources to add, remove, or clear from line targeting.
Field | Description | Data Type |
---|---|---|
| An array of POI resources to target. To retrieve the supported locations or types containing the required fields below, refer to Read POI Locations.
|
|
| An array of unique POI IDs to remove from targeting. |
|
| Indicates if all existing targeted POI resources should be removed.
|
|
| Specifies the target radius type. A user must be less than the specified distance to a location to be served. Valid values include:
|
|
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
Parameter | Description | Data Type | Required |
---|---|---|---|
| Specifies the sort column. Valid value:
|
| N |
| Specifies the sort direction. Valid values:
|
| N |
| Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
| Y |
| Specifies the country code to use when searching for postal codes. Use the |
| N |
Response Fields
The response contains the following fields of interest:
Name | Description |
---|---|
| Unique ID of the location. This value will be used for Geo targeting. |
| Specifies the location name. |
|
|
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
Parameter | Description | Data Type | Required |
---|---|---|---|
| Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
| Y |
Response Fields
The response contains the following fields of interest:
Name | Description |
---|---|
| Value to use for |
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.
Parameter | Parameter Type | Description | Data Type | Required |
---|---|---|---|---|
| path | Specifies the line ID. |
| Y |
| body | Specifies the geo resources to add, remove, or clear from targeting. |
| Y |
| body | Specifies an array of targeting types to update, enable, or disable.
To learn more, refer to Targeting Types. |
| Y |
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:
Parameter | Parameter Type | Description | Data Type | Required |
---|---|---|---|---|
| path | Specifies the line ID. |
| Y |
| body | Specifies an array of targeting types to update, enable, or disable.
To learn more, refer to Targeting Types. |
| Y |
| body | The |
| Y |
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
Parameter | Parameter Type | Description | Data Type | Required |
---|---|---|---|---|
| path | Specifies the line ID. |
| Y |
| body | Specifies the POI resources to add, remove, or clear from targeting. Refer to Points of Interest (POI) for required fields. |
| Y |
| body | Specifies an array of targeting types to update, enable, or disable.
To learn more, refer to Targeting Types. |
| Y |
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"
}