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) 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, Zip) 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.

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, Zip) 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

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

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

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

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

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

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

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

About Targeting