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.

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 customDate Range 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.

Table 63 POI Audience Object
Parameter Description Data Type
segmentId Specifies the POI audience ID. integer
name Specifies the name of the POI audience. string
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, see Audience Targeting Rules.

object
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, see Audience Targeting Rules.

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

Specifies the age of the data used to identify the POI audience. The patform 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 must be specified.)
string
customDateRange

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

To learn more, see Custom Date Range.

array
status

Specifies the status of the audience. By default, ACTIVE.

  • ACTIVE
  • INACTIVE
string
accountId

Specifies the advertiser account 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 on seat-level audience.

number

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.

Table 64 POI Location Object
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 lcoation 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), 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
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.

To retrieve breadcrumbs 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

Returns an array 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}

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 path

Specifies a POI location id.

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

integer N

Example Request

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 POI Audience by Segment ID

Returns the specified POI audience as identified by its segment ID.

GET /traffic/audiences/poi/{segmentId}

Parameters

The API takes a single parameter that is specified in the path of the endpoint.

Table 65 Read POI Audience by Segment ID Parameters
Parameter Parameter Type Description Data Type Required?
segmentId path Specifies the ID of the POI audience. string Y

Example Request

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 POI Audience Size

Returns 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, see 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, see 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, see Custom Date Range.

[1]Required if the retentionDays value is CUSTOM_DATES
array N [1]

Example Request

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

Creates a POI audience that identifies consumers meeting the specified parameters.

POST /traffic/audiences/poi

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 during the specified date range. To learn more, see 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 during the specified date range. To learn more, see 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
accountId body

Specifies the advertiser account ID.

If specified, the POI audience is defined at the advertiser level. Otherwise, the audience is on seat level.

Note: Once specifed, the accountId cannot be changed.

number 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 (Only in this case customDateRange field is valid - in all other cases API will throw an error)
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, see Custom Date Range.

[2]Required if the retentionDays value is CUSTOM_DATES
array N [2]

Parameters

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

Example Request

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

Update POI Audiences

Updates a POI location audience with the specified ID.

PUT /traffic/audiences/poi/{segmentId}

The resource returns updated POI audience data.

Parameters

The POI audience ID is specified in the path of the resource endpoint. All other parameters are specified in the body of the application/json payload.

Parameter Parameter Type Description Data Type Required?
segmentId path Specifies the POI audience ID. integer Y
name body Specifies the name of the audience. string N
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 during the specified date range. To learn more, see Audience Targeting Rules. object N
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 during the specified date range. To learn more, see 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 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, see Custom Date Range. array N
status body

Specifies the status of the audience. By default, ACTIVE.

  • ACTIVE
  • INACTIVE
string N

Example Request

{
    "name": "test-seatlevel-poi",
    "includes": {
        "chains": [1573, 1873, 2348],
        "categories": [],
        "gids": [],
        "woeids": [12518554]
    },
    "excludes": {
        "chains": [],
        "categories": [],
        "gids": [],
        "woeids": [12522451]
    },
    "numberOfVisits": 1,
    "retentionDays": "SEVEN",
    "customDateRange": [],
    "accountId" : null,
    "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": "SEVEN",
        "customDateRange": [],
        "status": "ACTIVE"
    },
    "errors": null,
    "timeStamp": "2018-01-31T21:51:09Z"
}