Geography Targeting¶
This article describes resources that enable you to read and define geographic location targeting.
Overview¶
Geographic location targeting enables you to target specific geographical areas by geographic location (geo
) and points of interest (poi
) or geo fencing location (geoFencings
).
The Verizon Media DSP supports GEOGRAPHY
targeting for lines serving display, video, and native ads.
Display and video lines can target consumers by
geo
(country, state, city, DMA, zip or postal code) orgeofencing
location.Native lines can target consumers by country, state, city, or DMA
geo
location.
You can set up geofencing to target users within a specified radius of a given address.
Important
You cannot target both geographic locations (geos
) and geofencing locations (geoFencings
) at the same time.
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 Verizon Media 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, Zip) to target or block from targeting. - Supported locations can be retrieved using the geos resource.
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, see 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. - To retrieve the supported locations or types, see Read POI Locations.
Note: POI is only supported in United States. Note: You cannot target both points of interest resources and geofencing locations at the same time. |
|
|
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, see Targeting Object.
Geo¶
The geo
payload object specifies the Geographic (Country/State/DMA/City, Zip) 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 addresses 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, see 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 |
|
N |
|
Specifies the country code to use when searching for postal codes. Use the |
|
N |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/geos?query=san+francisco&sort=name&dir=desc
Example Response¶
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. |
|
|
{
"response": [
{
"id": "##south san francisco#ca#usa",
"name": "South San Francisco, California",
"description": "south san francisco, ca",
"level": "City",
"key": "south san francisco, california",
"code": "3555"
},
{
"id": "807####usa",
"name": "San Francisco-oak-san Jose",
"description": "san francisco-oak-san jose",
"level": "Dma",
"key": "807",
"code": "807"
}
],
"errors": null,
"timeStamp": "2017-10-17T18:21:26Z"
}
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/geos?countryCode=usa&query=9512
Example Response¶
{
"response": [
{
"id": "#49512###usa",
"name": "49512",
"level": "Zip",
"key": "#49512###usa",
"code": "12779404"
},
{
"id": "#95123###usa",
"name": "95123",
"level": "Zip",
"key": "#95123###usa",
"code": "12797574"
}
],
"errors": null,
"timeStamp": "2017-10-18T04:31:49Z"
}
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 |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/countries?query=usa
Example Response¶
The response contains the following fields of interest:
Name |
Description |
---|---|
|
Value to use for |
{
"response": [
{
"id": "####usa",
"name": "United States",
"description": "united states of america/usa",
"level": "Country",
"key": "usa",
"code": "840"
}
],
"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, see Targeting Types. |
|
Y |
Example Request URL¶
POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting/
Example Request Body¶
{
"geos": {
"removedNames": [],
"clearAll": false,
"added": [
{
"excluded": false,
"name": "###15#nor"
},
{
"excluded": true,
"name": "##callahan#fl#usa"
}
]
},
"types": [
{
"name": "GEOGRAPHY",
"isTargeted": true
}
]
}
Example 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",
"code": "840",
"excluded": false
},
{
"id": "###15#nor",
"name": "More Og Romsdal, Norway",
"description": "more og romsdal",
"level": "State",
"key": "15, nor",
"code": "11327",
"excluded": false
}
],
"geosExcluded": [
{
"id": "##callahan#fl#usa",
"name": "Callahan, Florida",
"description": "callahan, fl",
"level": "City",
"key": "callahan, florida",
"code": "16270",
"excluded": true
}
]
},
"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, see Targeting Types. |
|
Y |
|
body |
The |
|
Y |
Example Request¶
{
"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
}
]
}
Example 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"
}
]
},
"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. See Points of Interest (POI) for required fields. |
|
Y |
|
body |
Specifies an array of targeting types to update, enable, or disable.
To learn more, see Targeting Types. |
|
Y |
Example Request URL¶
POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting/
Example 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
}
]
}
Example 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"
}
]
},
"errors": null,
"timeStamp": "2019-10-20T04:42:46Z"
}
See also