- 9 Minutes to read
Point of Interest Audiences
- 9 Minutes to read
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 |
---|---|---|---|---|
| Specifies the audience ID. |
| N/A | Required |
| Specifies the name of the POI audience. |
| Required | Optional |
| 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 To learn more, refer to Audience Targeting Rules. |
| Required | Optional |
| 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. |
| Optional | Optional |
| Specifies the number of times that a consumer must visit a POI location to be included in the POI audience. Defaults to |
| Optional | Optional |
| 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:
|
| Optional | Optional |
| Specifies the age of the data used to identify the POI audience if the To learn more, refer to Custom Date Range. |
| Optional | Optional |
| Specifies the status of the audience. Defaults to
|
| Optional | Optional |
| 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. |
| 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 |
---|---|---|
| Specifies the POI location ID. |
|
| Specifies the POI location name. |
|
| Specifies the POI location type.
|
|
| Indicates whether the POI location has children POI locations.
|
|
| Specifies an array of POI location objects that show the hierarchy of POI location objects. Each object is identified by a unique |
|
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 |
---|---|---|
| Specifies an array of To retrieve chain store IDs use the Read POI Locations resource. |
|
| Specifies an array of To retrieve category IDs use the Read POI Locations resource. |
|
| Specifies an array of store addresses identified by their GIDs. To retrieve GIDs use the Read POI Locations resource. |
|
| Specifies an array of “where on earth” venue addresses. To retrieve |
|
Custom Date Range
The customDateRange
object defines the start and end date of a custom data retention period.
Field | Description | Data Type |
---|---|---|
| Specifies the start date in YYYY-MM-DD format. |
|
| Specifies the start date in YYYY-MM-DD format. |
|
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. ThelocationId
is theid
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 |
---|---|---|---|---|
| query | Specifies a POI location If specified, the resource returns data about the specified POI location and its children. |
| Optional |
| query | Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
| Optional |
| query | Specifies the page number. |
| Optional |
| query | Specifies the total number of items to return. Maximum allowed value is |
| 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 |
---|---|---|---|---|
| path | Specifies the audience ID. |
| 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 |
---|---|---|---|---|
| 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. |
| Y |
| 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. |
| N |
| body | Specifies the number of times that a consumer must visit a POI location to be included in the POI audience. |
| N |
| 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:
|
| N |
| body | Specifies the number of days that the POI audience is retained if the Required if the |
| 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.