Point of Interest Audiences
  • 9 Minutes to read

    Point of Interest Audiences


      Article summary

      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.

      Required if the retentionDays value is CUSTOM_DATES

      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.


      Was this article helpful?