POI Audiences

This article describes resources and services that enable you to read, create, and update POI audiences.

Overview

POI location audiences enable you to to identify and to target consumers who have visited points of interests on specific dates and build custom audiences such as holiday shoppers, vacation travelers, sporting event attendees, and so on.

Targeting POI audiences enable you to reach people when and where ads will have the most impact, increase consideration, and maximize revenue potential.

POI audiences can be created at the seat level or at the advertiser level.

Hierarchy

You can define a POI audience at the seat level or the advertiser level.

  • Seat-level audiences are shared by every advertiser in the seat.

  • Advertiser-level audiences are specific to a single advertiser.

Endpoint

You can use this endpoint to read, create, and update POI location audiences:

/traffic/audiences/poi/

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to retrieve information about POI locations and POI audiences. Distinct endpoints enable you to view information about POI audiences or POI locations by location ID.

  • Use the POST method to create POI audiences.

  • Use the PUT method to update existing POI audiences.

Resources

The platform provides several objects for defining and managing POI audiences: the POI audience, POI location, excludes, includes, and customDateRange objects.

POI Audience Object

The POI audience resource identifies a custom audience based on consumer visits to point-of-interest locations. Consumers may be included in an audience by inclusion in or exclusion from visits to specified POI locations.

Parameter

Description

Data Type

Create

Update

id

Specifies the audience ID.

integer

N/A

Required

name

Specifies the name of the POI audience.

string

Required

Optional

includes

Specifies the audience targeting rule that identifies one or more POI locations visited by the consumer. The consumer is included in the audience if the consumer has visited the POI location.

At least one includes audience targeting rule is required for each POI audience.

To learn more, refer to Audience Targeting Rules.

object

Required

Optional

excludes

Specifies an audience targeting rule that identifies one or more POI locations not visited by the consumer. The consumer is excluded from the audience if the consumer has not visited the POI.

To learn more, refer to Audience Targeting Rules.

object

Optional

Optional

numberOfVisits

Specifies the number of times that a consumer must visit a POI location to be included in the POI audience. Defaults to 1 if you don’t specify a value.

integer

Optional

Optional

retentionDays

Specifies the age of the data used to identify the POI audience. The platform retains POI location data for the specified “lookback window” and consumers are included or excluded in the POI audience based on behavior identified in this period.

Valid values include:

  • SEVEN

  • FOURTEEN

  • THIRTY

  • SIXTY

  • NINETY (Default)

  • ONE_HUNDRED_EIGHTY

  • CUSTOM_DATES (If specified, a customDateRange must be specified.)

string

Optional

Optional

customDateRange

Specifies the age of the data used to identify the POI audience if the retentionDays value is CUSTOM_DATES.

To learn more, refer to Custom Date Range.

array

Optional

Optional

status

Specifies the status of the audience. Defaults to ACTIVE.

  • ACTIVE

  • INACTIVE

string

Optional

Optional

accountId

Specifies the advertiser ID.

POI audiences can be defined at the seat level or the advertiser level. If specified, the POI audience is an advertiser-level audience. Otherwise, the audience is a seat-level audience.

number

Required for advertiser-level audiences; do not use for seat-level audiences.

Required for advertiser-level audiences; do not use for seat-level audiences.

POI Location Object

The POI location object defines a point-of-interest location.

You can retrieve POI location data using the Read POI Locations APIs.

Field

Description

Data Type

id

Specifies the POI location ID.

integer

name

Specifies the POI location name.

string

type

Specifies the POI location type.

  • Category

  • Chain

  • Gid

  • Woe

string

hasChildren

Indicates whether the POI location has children POI locations.

  • If true, the POI location has children.

  • If false, the POI location has no children.

boolean

breadcrumbs

Specifies an array of POI location objects that show the hierarchy of POI location objects. Each object is identified by a unique id and name.

array

Audience Targeting Rules

The includes and excludes objects define an audience targeting rule that enables the client to identify consumers based on their behaviors.

These objects identify chain stores (chains), group of chain stores (categories), store addresses (gids), and venue addresses (woeids) that the consumer has either visited (in the case of the includes object) or not visited (in the case of the excludes object) .

Field

Description

Data Type

chains

Specifies an array of chain IDs. A chain is a chain store. For example, Old Navy.

To retrieve chain store IDs use the Read POI Locations resource.

array

categories

Specifies an array of category IDs. A category is a group of chain stores. For example, convenience stores.

To retrieve category IDs use the Read POI Locations resource.

array

gids

Specifies an array of store addresses identified by their GIDs.

To retrieve GIDs use the Read POI Locations resource.

array

woeids

Specifies an array of “where on earth” venue addresses.

To retrieve woeids objects use the Read POI Locations resource.

array

Custom Date Range

The customDateRange object defines the start and end date of a custom data retention period.

Field

Description

Data Type

start

Specifies the start date in YYYY-MM-DD format.

string

end

Specifies the start date in YYYY-MM-DD format.

string

Read POI Locations

Read POI location data. If the optional location ID parameter is specified only the specified POI location is returned.

GET /traffic/audiences/poi/search?parentId={locationId}&query={query}&page={page}&limit={limit}

The resource returns information about the specified POI location and its children.

Note

The parentId is an optional parameter. If not specified, the platform returns root-level categories. The locationId is the id field from the response of this API.

Parameters

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

Parameter

Parameter Type

Description

Data Type

Required

locationId

query

Specifies a POI location id.

If specified, the resource returns data about the specified POI location and its children.

integer

Optional

query

query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string

Optional

page

query

Specifies the page number.

integer

Optional

limit

query

Specifies the total number of items to return. Maximum allowed value is 100.

integer

Optional

Example Request URL

GET /traffic/audiences/poi/search?parentId=17

Example Response

{
  "response": [
    {
      "id": 96925947,
      "name": "Banks",
      "type": "Category",
      "hasChildren": true,
      "breadcrumbs": [
        {
          "id": 17,
          "name": "Legal & Financial Services"
        }
      ]
    },
    {
      "id": 96925933,
      "name": "Currency Exchanges",
      "type": "Category",
      "hasChildren": true,
      "breadcrumbs": [
        {
          "id": 17,
          "name": "Legal & Financial Services"
        }
      ]
    },
    {
      "id": 96928014,
      "name": "Investment Brokerages",
      "type": "Category",
      "hasChildren": true,
      "breadcrumbs": [
        {
          "id": 17,
          "name": "Legal & Financial Services"
        }
      ]
    }
  ],
  "errors": null,
  "timeStamp": "2018-03-14T20:14:11Z"
}

Read Audience

Read a specific POI audience.

GET /traffic/audiences/poi/{id}

Parameters

Parameter

Parameter Type

Description

Data Type

Required

id

path

Specifies the audience ID.

string

Y

Example Request URL

GET /traffic/audiences/poi/1406321

Example Response

{
  "response": {
    "includes": {
      "chains": [
        389,
        403,
        2644,
        3091,
        3287
      ],
      "woeids": [
        2376915,
        12518526,
        12518554
      ]
    },
    "excludes": {},
    "id": 50434389,
    "name": "test-poi-audience",
    "numberOfVisits": 1,
    "accountId": 1406321,
    "status": "ACTIVE",
    "retentionDays": "THIRTY"
  },
  "errors": null,
  "timeStamp": "2018-01-31T21:51:09Z"
}

Read Audience Size

Get the total number (totalCount) of consumers in a specified poi audience.

POST /traffic/audiences/poi/size

The resource enables you to identify the size of a prospective audience.

Parameters

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

Parameter

Parameter Type

Description

Data Type

Required

includes

body

Specifies an audience targeting rule that identifies one or more POI locations visited by the consumer. The consumer is included in the audience if the consumer has visited the POI.

To learn more, refer to Audience Targeting Rules.

object

Y

excludes

body

Specifies an audience targeting rule that identifies one or more POI locations not visited by the consumer. The consumer is excluded from the audience if the consumer has not visited the POI.

To learn more, refer to Audience Targeting Rules.

object

N

numberOfVisits

body

Specifies the number of times that a consumer must visit a POI location to be included in the POI audience.

integer

N

retentionDays

body

Specifies the age of the data used to identify the POI audience. The platform retains POI location data for the specified “lookback window” and consumers are included or excluded in the POI audience based on behavior identified in this period.

Valid values include:

  • SEVEN

  • FOURTEEN

  • THIRTY

  • SIXTY

  • NINETY

  • ONE_HUNDRED_EIGHTY

  • CUSTOM_DATES (If specified, a customDateRange value must be specified.)

string

N

customDateRange

body

Specifies the number of days that the POI audience is retained if the retentionDays value is CUSTOM_DATES. To learn more, refer to Custom Date Range.

array

N [1]

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/poi/size

Example Request Body

{
  "retentionDays": "THIRTY",
  "numberOfVisits": 1,
  "includes": {
    "chains": [
      1573,
      1873,
      2348
    ],
    "woeids": [
      12518554
    ]
  },
  "excludes": {
    "chains": [],
    "woeids": []
  },
  "customDateRange": []
}

Example Response

{
  "response": {
    "totalCount": 571440
  },
  "errors": null,
  "timeStamp": "2018-02-27T23:44:40Z"
}

Create Audience

Create a new POI audience.

POST /traffic/audiences/poi

Parameters

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

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/poi

Example Request Body

{
  "name": "test-seatlevel-poi",
  "includes": {
    "chains": [
      1573,
      1873,
      2348
    ],
    "categories": [],
    "gids": [],
    "woeids": [
      12518554
    ]
  },
  "excludes": {
    "chains": [],
    "categories": [],
    "gids": [],
    "woeids": [
      12522451
    ]
  },
  "numberOfVisits": 1,
  "accountId": null,
  "retentionDays": "THIRTY",
  "customDateRange": [],
  "status": "ACTIVE"
}

Example Response

{
  "response": {
    "id": 50434389,
    "name": "test-seatlevel-poi",
    "includes": {
      "chains": [
        1573,
        1873,
        2348
      ],
      "categories": [],
      "gids": [],
      "woeids": [
        12518554
      ]
    },
    "excludes": {
      "chains": [],
      "categories": [],
      "gids": [],
      "woeids": [
        12522451
      ]
    },
    "numberOfVisits": 1,
    "retentionDays": "THIRTY",
    "customDateRange": [],
    "status": "ACTIVE"
  },
  "errors": null,
  "timeStamp": "2018-01-31T21:51:09Z"
}

Example Request Body (Custom Dates)

{
  "name": "poi-adv",
  "includes": {
    "chains": [
      1573,
      1873,
      2348
    ],
    "categories": [],
    "gids": [],
    "woeids": [
      12518554
    ]
  },
  "excludes": {
    "chains": [],
    "categories": [],
    "gids": [],
    "woeids": [
      12522451
    ]
  },
  "numberOfVisits": 1,
  "accountId": 1382393,
  "retentionDays": "CUSTOM_DATES",
  "customDateRange": [
    {
      "start": "2020-01-29",
      "end": "2020-03-28"
    }
  ],
  "status": "ACTIVE"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "includes": {
      "chains": [
        1573,
        1873,
        2348
      ],
      "woeids": [
        12518554
      ]
    },
    "excludes": {
      "woeids": [
        12522451
      ]
    },
    "id": 51683496,
    "name": "poi-adv",
    "accountId": 1382393,
    "customDateRange": [
      {
        "start": "2020-01-29",
        "end": "2020-03-28"
      }
    ],
    "retentionDays": "CUSTOM_DATES",
    "numberOfVisits": 1
  },
  "errors": null,
  "timeStamp": "2020-02-28T23:05:39.014Z"
}

Update Audience

Update an existing POI audience.

PUT /traffic/audiences/poi/{id}

Partial updates are supported; values of supported fields that are not in the payload remain unchanged.

Parameters

The audience id is specified in the endpoint path. All other fields are specified in the body of the application/json payload.

Example Request URL

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/poi/50434389

Example Request Body

{
  "name": "audience4-545",
  "status": "ACTIVE",
  "includes": {
    "chains": [
      1573
    ]
  }
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "includes": {
      "chains": [
        1573
      ]
    },
    "excludes": {
      "chains": [
        4624
      ],
      "woeids": [
        12522451,
        23533639
      ]
    },
    "id": 51682810,
    "name": "audience4-545",
    "customDateRange": [
      {
        "start": "2020-01-29",
        "end": "2020-03-28"
      }
    ],
    "retentionDays": "CUSTOM_DATES",
    "numberOfVisits": 1
  },
  "errors": null,
  "timeStamp": "2020-02-28T23:19:40.455Z"
}

Delete Audience

The DSP Traffic API does not support deletion of poi audiences.