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, metro area, sub region, region, DMA, zip or postal code, postcode prefix) or geofencing 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
`id`	Specifies the line ID.	`integer`
`geos`	Specifies geographic locations (Country/State/DMA/City/Metro Area/Sub Region/Region, Zip, PostCode Prefix) to target or block from targeting. - Supported locations can be retrieved using the geos resource. To create or update targeted geographic locations, see Geos Payload. To read geographic locations that can be targeted, see Read Targeting Geos. Note: You cannot target both geographic locations and geofencing locations at the same time.	`array`
`geoFencings`	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.	`array`
`pois`	Specifies points of interest resources to target within the set geographic locations. - To retrieve the supported locations or types, see Read POI Locations. To create or update targeted points of interest resources, see Points of Interest (POI). Note: POI is only supported in United States. Note: You cannot target both points of interest resources and geofencing locations at the same time.	`array`
`geosIncluded`	A read-only array of targeted geo locations which are marked as Included. Refer to Geo Payload.	`array`
`geosExcluded`	A read-only array of targeted geo locations which are marked as Excluded. Refer to Geo Payload.	`array`
`geoFencingsIncluded`	A read-only array of targeted geofencing locations.	`array`
`poisIncluded`	A read-only array of targeted POI locations.	`array`

Note

For a complete list of targeting resource fields, see 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
`added`	An array of geos to target. This is an array of objects containing the following required fields: `entityId` - ID of the Geo to be added. `excluded` - Indicates if the added IDs are to be excluded or included. `true` - exclude from targeting; `false` - include in targeting.	`array`
`removedNames`	An array of unique Geo location names to be removed from targeting.	`array`
`clearAll`	Indicates if all existing Geo locations should be removed. `true` - remove all targeted Geo locations. `false` - (Default Value) do not remove any targeted Geo locations.	`boolean`

Field

Description

Data Type

added

An array of geos to target. This is an array of objects containing the following required fields:

entityId - ID of the Geo to be added.
excluded - Indicates if the added IDs are to be excluded or included. true - exclude from targeting; false - include in targeting.

array

removedNames

An array of unique Geo location names to be removed from targeting.

array

clearAll

Indicates if all existing Geo locations should be removed.

true - remove all targeted Geo locations.
false - (Default Value) do not remove any targeted Geo locations.

boolean

Geos Included Object¶

The geosIncluded object contains included geographic locations.

Field	Description	Data Type
`id`	Unique ID of the location.	`integer`
`country`	Specifies the geofencing country name.	`string`
`radius`	Specifies the radius of the geo fence.	`integer`
`radiusUnit`	Specifies the units used to measure the radius. Options include: `MILES` `FEET` `METERS`	`string`

Geos Excluded Object¶

The geosExcluded objects contains excluded geographic locations.

Field	Description	Data Type
`id`	Unique ID of the location.	`integer`
`country`	Specifies the geofencing country name.	`string`
`radius`	Specifies the radius of the geo fence.	`integer`
`radiusUnit`	Specifies the units used to measure the radius. Options include: `MILES` `FEET` `METERS`	`string`

Geo Fencing¶

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

Field	Description	Data Type
`added`	An array of geofencing addresses to target. This is an array of objects containing the following required fields: `location` - Addresses to target for geo fencing. Geo fencing will target users whose current location is within the specified distance from this addresses. The address must be in the following format: [Number] Address City State Zip. Note: The Zip code / Postal code is optional.	`array`
`removed`	An array of unique geofencing IDs to remove from targeting.	`array`
`clearAll`	Indicates if all existing geofencing locations should be removed. `true` - remove all targeted geofencing locations. `false` - (Default Value) do not remove any targeted geofencing locations.	`boolean`
`radius`	Specifies the radius of the geo fence. This is how far away a user can be from each addresses and still be targeted.	`integer`
`radiusUnit`	Specifies the unit of the `radius`. Valid values include: `MILES` `FEET` `METERS`	`string`

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
`added`	An array of POI resources to target. To retrieve the supported locations or types containing the required fields below, see Read POI Locations. `entityId` - ID of the POI category to be added. `poiLocationType` - Location type of the POI category. Possible values include: `Category`, `Chain`, `Woe`, `Venue`	`array`
`removed`	An array of unique POI IDs to remove from targeting.	`array`
`clearAll`	Indicates if all existing targeted POI resources should be removed. `true` - remove all targeted POI resources. `false` - (Default Value) do not remove any targeted POI resources.	`boolean`
`radiusType`	Specifies the target radius type. A user must be less than the specified distance to a location to be served. Valid values include: `METERS_100`: 100+ Meters (Default Value) `METERS_200`: 200+ Meters `METERS_500`: 500+ Meters `MILE_1`: 1+ Mile `MILES_2`: 2+ Miles `MILES_5`: 5+ Miles `MILES_10`: 10+ Miles	`string`

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
`sort`	Specifies the sort column. Valid value: `name`	`string`	N
`dir`	Specifies the sort direction. Valid values: `asc` `desc`	`string`	N
`query`	Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a `+` or `%20`). Provide a partial search string or leave it empty to get all results.	`string`	N
`countryCode`	Specifies the country code to use when searching for postal codes. Use the `key` field from Targeting Countries response.	`string`	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
`id`	Unique ID of the location. This value will be used for Geo targeting.
`name`	Specifies the location name.
`level`	`City` `State` `Country` `Dma` `Metro Area` `Sub Region` `Region` `Zip` `PostCode Prefix`

{
  "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"
}

Example Request URL¶

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

Example Response¶

{
  "response": [
    {
      "id": "#k1b 4v4##gloucester####on#can",
      "name": "k1b 4v4",
      "level": "Zip",
      "key": "#k1b 4v4#######can",
      "code": "24003711",
      "woeid": "24003711"
    },
    {
      "id": "##k1b######can",
      "name": "k1b",
      "level": "Postcode Prefix",
      "key": "##k1b######can",
      "code": "k1b"
    }
  ],
  "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
`query`	Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a `+` or `%20`). Provide a partial search string or leave it empty to get all results.	`string`	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
`key`	Value to use for `countryCode` parameter when retrieving supported geos.

{
  "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
`id`	path	Specifies the line ID.	`integer`	Y
`geos`	body	Specifies the geo resources to add, remove, or clear from targeting.	`object`	Y
`types`	body	Specifies an array of targeting types to update, enable, or disable. `GEOGRAPHY` targeting type must be specified to apply the changes. To learn more, see Targeting Types.	`array`	Y

Parameter

Parameter Type

Description

Data Type

Required

id

path

Specifies the line ID.

integer

geos

body

Specifies the geo resources to add, remove, or clear from targeting.

object

types

body

Specifies an array of targeting types to update, enable, or disable.

GEOGRAPHY targeting type must be specified to apply the changes.

To learn more, see Targeting Types.

array

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"
      },
      {
        "excluded": false,
        "name": "##k2a######can"
      }
    ]
  },
  "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
      },
      {
        "id": "##k2a######can",
        "name": "k2a",
        "level": "Postcode Prefix",
        "key": "##k2a######can",
        "code": "k2a",
        "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
`id`	path	Specifies the line ID.	`integer`	Y
`types`	body	Specifies an array of targeting types to update, enable, or disable. `GEOGRAPHY` targeting type must be specified to apply the changes. To learn more, see Targeting Types.	`array`	Y
`geoFencings`	body	The `geoFencing` payload object specifies the `geoFencing` resources to add, remove, or clear from line targeting.	`object`	Y

Parameter

Parameter Type

Description

Data Type

Required

id

path

Specifies the line ID.

integer

types

body

Specifies an array of targeting types to update, enable, or disable.

GEOGRAPHY targeting type must be specified to apply the changes.

To learn more, see Targeting Types.

array

geoFencings

body

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

object

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
`id`	path	Specifies the line ID.	`integer`	Y
`pois`	body	Specifies the POI resources to add, remove, or clear from targeting. See Points of Interest (POI) for required fields.	`object`	Y
`types`	body	Specifies an array of targeting types to update, enable, or disable. `GEOGRAPHY` targeting type must be specified to apply the changes. To learn more, see Targeting Types.	`array`	Y

Parameter

Parameter Type

Description

Data Type

Required

id

path

Specifies the line ID.

integer

pois

body

Specifies the POI resources to add, remove, or clear from targeting. See Points of Interest (POI) for required fields.

object

types

body

Specifies an array of targeting types to update, enable, or disable.

GEOGRAPHY targeting type must be specified to apply the changes.

To learn more, see Targeting Types.

array

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"
}