Geography Targeting
  • 15 Minutes to read

    Geography Targeting


      Article summary

      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 by geos of type country, state, city, metro area, sub region, region, DMA, zip/postal code and postcode prefix, or by geofencings.

      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.  

      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


      Was this article helpful?