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, and native ads participating in Yahoo Preferred Network.

  • 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.

  • Lines participating in Yahoo Preferred Network (supplyType = YAHOO) can target consumers by country, state, city, or DMA geo location.

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:

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, refer to Geos Payload.

  • To read geographic locations that can be targeted, refer to 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, refer to 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, refer to Read POI 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.

array

isAllCountriesTargeted
Specifies the option to target every country in the world. When this field is set to true, all other geography targeting settings are cleared and the line becomes eligible to serve across the world. Keep in mind, however, that the field cannot be set to true if other targeting settings such as geos, geoFencings or pois are set in the same request.

Important

If no location targeting is required, this field must be set to true. This is a prerequisite for activating the line. Note: Targeting all countries can cause rapid spend, especially if other targeting settings of the line cover a broad spectrum of consumers. Use this targeting option with caution to avoid over-delivering budgets.

boolean

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

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 these 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 address 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, refer to 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). Partial search string is accepted.

string

Y

countryCode

Specifies the country code to use when searching for postal codes. Use the key field from Targeting Countries response.

string

N

Response Fields

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

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

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

Response Fields

The response contains the following fields of interest:

Name

Description

key

Value to use for countryCode parameter when retrieving supported geos.

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

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, refer to Targeting Types.

array

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

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, refer to Targeting Types.

array

Y

geoFencings

body

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

object

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

id

path

Specifies the line ID.

integer

Y

pois

body

Specifies the POI resources to add, remove, or clear from targeting. Refer to 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, refer to Targeting Types.

array

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

Additional Resources

About Targeting