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) 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 th 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.

This resource comprises multiple fields that enable you to specify line targeting across many types of targets including the GEOGRAPHY target type.

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 to target or exclude from targeting.

  • 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 exclude 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
geosIncluded Targeted geo locations which are marked as Included. Refer to Geo Payload. array
geosExcluded Targeted geo locations which are marked as Excluded. Refer to Geo Payload. array
geoFencingsIncluded Targeted geo fencing locations. To learn more, see Geo Fencing. array

Note

For a complete list of targeting resource fields, see Targeting Object.

Geo

The geo payload object specifies the geo 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.

  • If true, remove all targeted Geo locations.
  • If false (the default value), do not remove any targeted Geo locations.
 boolean

Geos Included Object

The geosExcluded 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

Example Response (Partial)¶

{
  "geoFencingsIncluded": [
    {
      "id": 138745,
      "country": "United States",
      "location": "328 Lomita Dr, Stanford, CA 94305",
      "latitude": 37.43249,
      "longitude": -122.17034,
      "radius": 5,
      "radiusUnit": "MILES"
    },
    {
      "id": 138746,
      "country": "United States",
      "location": "1600 Amphitheatre Pkwy, Mountain View, CA 94043",
      "latitude": 37.42307,
      "longitude": -122.08414,
      "radius": 5,
      "radiusUnit": "MILES"
    }
  ]
}

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

  • If true, remove all targeted geofencing locations.
  • If false (the 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

Read Geos to Target

Returns a list of geo objects that may be targeted.

GET /traffic/targeting/geos?page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}&countryCode={countryCode}

All parameters are specified in a query that is appended to the resource endpoint.

Parameters

The resource accepts the following parameters:

Parameter Parameter Type Description Data Type Required?
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum allowed value is 100. integer N
sort query Specifies the sort column. string N
dir query

Specifies the sort direction. Valid values:

  • asc
  • desc
 string N
query 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 query Specifies the country code to use when searching for postal codes. Use the key field from Targeting Countries response. string N

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/geos?dir=desc&limit=20&page=1&query=san+francisco&sort=name

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

Example Response (Partial)

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

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

Example Response (Partial)

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

Parameters

The resource takes the following parameters:

Parameter Parameter Type Description Data Type Required?
query 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

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 Targets

Adds new geo targets or updates existing geo targets 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 target.

To target geos or geoFencings, the GEOGRAPHY targeting type must be enabled.

To learn more, see Targeting Types.

 array Y

Example Request

The line ID is specified in the path of the resource endpoint:

POST traffic/lines/365277/targeting/

All other parameters are specified in the body of the application/json payload.

{
  "geos": {
    "removedNames": [],
    "clearAll": false,
    "added": [
      {
        "excluded": false,
        "name": "###15#nor"
      },
      {
        "excluded": true,
        "name": "##callahan#fl#usa"
      }
    ]
  },
  "types": [
    {
      "name": "GEOGRAPHY",
      "isTargeted": true
    }
  ]
}

Add/Update Geofencing Targets

Adds new geoFencings targets or updates existing geoFencings targets for the specified lines.

POST /traffic/lines/{id}/targeting

The POST method enables you to add, update, remove, or clearall geoFencing resources targeted by a line.

The targeting type and all changes are specified in the body of the application/json payload.

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 the targeting types to enable or modify.

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

See also

About Targeting