--- title: "Point of Interest" slug: "point-of-interest" updated: 2024-02-29T15:57:50Z published: 2024-02-29T15:57:50Z canonical: "help.yahooinc.com/point-of-interest" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt > Use this file to discover all available pages before exploring further. # Point of Interest 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: ```plaintext /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](/dsp-api/docs/point-of-interest#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](/dsp-api/docs/point-of-interest#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](/dsp-api/docs/point-of-interest#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](/dsp-api/docs/point-of-interest#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](/dsp-api/docs/point-of-interest#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](/dsp-api/docs/point-of-interest#read-poi-locations) resource. | `array` | | `gids` | Specifies an array of store addresses identified by their GIDs. To retrieve GIDs use the [Read POI Locations](/dsp-api/docs/point-of-interest#read-poi-locations) resource. | `array` | | `woeids` | Specifies an array of “where on earth” venue addresses. To retrieve `woeids` objects use the [Read POI Locations](/dsp-api/docs/point-of-interest#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. ```plaintext 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] > 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 ```plaintext GET /traffic/audiences/poi/search?parentId=17 ``` ### Example Response ```plaintext {  "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. ```plaintext GET /traffic/audiences/poi/{id} ``` ### Parameters | **Parameter** | **Parameter Type** | **Description** | **Data Type** | **Required** | | --- | --- | --- | --- | --- | | `id` | path | Specifies the audience ID. | `string` | Y | ### Example Request URL ```plaintext GET /traffic/audiences/poi/1406321 ``` ### Example Response ```plaintext {  "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. ```plaintext 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](/dsp-api/docs/point-of-interest#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](/dsp-api/docs/point-of-interest#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](/dsp-api/docs/point-of-interest#custom-date-range). Required if the `retentionDays` value is `CUSTOM_DATES` | `array` | N [[1]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/poi-audience.html#id5) | ### Example Request URL ```plaintext POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/poi/size ``` ### Example Request Body ```plaintext {  "retentionDays": "THIRTY",  "numberOfVisits": 1,  "includes": {    "chains": [      1573,      1873,      2348    ],    "woeids": [      12518554    ]  },  "excludes": {    "chains": [],    "woeids": []  },  "customDateRange": [] } ``` ### Example Response ```plaintext {  "response": {    "totalCount": 571440  },  "errors": null,  "timeStamp": "2018-02-27T23:44:40Z" } ``` ## Create Audience Create a new POI audience. ```plaintext POST /traffic/audiences/poi ``` ### Parameters All fields are specified in the body of the `application/json` payload. ### Example Request URL ```plaintext POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/poi ``` ### Example Request Body ```plaintext {  "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 ```plaintext {  "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) ```plaintext {  "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 ```plaintext {  "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. ```plaintext 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 ```plaintext PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/poi/50434389 ``` ### Example Request Body ```plaintext {  "name": "audience4-545",  "status": "ACTIVE",  "includes": {    "chains": [      1573    ]  } } ``` ### Example Response ```plaintext {  "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.