# POI


Read-only reference catalogs for the `POI` dataset - the values you pick from
**while building an audience**. Creating and managing the underlying POI data
itself (segments, categories, brands, submissions) is the separate
[My POI Data]({{< relref "/api/v2/poi" >}}) surface under `/my-data/pois/*` -
do not mix the two. Every read here is authenticated and JSON-only (bearer
token + `Accept: application/json`) and uses the read rate bucket (120
requests/min per caller).

The POI catalogs form a **cascade**: pick segments, use them to read categories,
use categories to read brands, and use brands to read the individual locations.
The catalogs combine Intuizi's public POI catalog with your company's own POI
data, and each level is scoped to your account's POI permissions (segment,
category, brand and DMA allow-lists) when one is set.

```
segments -> categories (?segments[]) -> brands (?categories[]) -> locations (?brands[])
```

## Get Segments {#get-apiv2analysesreferencepoisegments}

`GET /api/v2/analyses/reference/poi/segments`

POI segments available to you, scoped to your account's POI segment allow-list
when one is set. Flat list of `{ value, text }` pairs where `value` is the
segment id.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Optional free-text filter on the item label (case-insensitive contains). |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl "https://console.intuizi.com/api/v2/analyses/reference/poi/segments" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Accept: application/json"
  ```
  {{< /tab >}}

  {{< tab name="Python" >}}
  ```python
  import requests

  res = requests.get(
      "https://console.intuizi.com/api/v2/analyses/reference/poi/segments",
      headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
  )
  segments = res.json()["data"]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/analyses/reference/poi/segments",
    { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
  );
  const segments = (await res.json()).data;
  ```
  {{< /tab >}}

  {{< tab name="PHP" >}}
  ```php
  $res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
      ->get('https://console.intuizi.com/api/v2/analyses/reference/poi/segments');
  $segments = $res->json('data');
  ```
  {{< /tab >}}

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": [
    { "value": 1, "text": "Retail" }
  ]
}
```

## Get Categories {#get-apiv2analysesreferencepoicategories}

`GET /api/v2/analyses/reference/poi/categories`

POI categories, cascading from the selected segment ids and scoped to your
account's POI category allow-list when one is set. Flat list of `{ value, text }`
pairs where `value` is the category id.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `segments` | integer[] | No | Segment ids to cascade the categories from (e.g. `[1, 2]`). |
| `search` | string | No | Optional free-text filter on the item label (case-insensitive contains). |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl "https://console.intuizi.com/api/v2/analyses/reference/poi/categories?segments[]=1" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Accept: application/json"
  ```
  {{< /tab >}}

  {{< tab name="Python" >}}
  ```python
  import requests

  res = requests.get(
      "https://console.intuizi.com/api/v2/analyses/reference/poi/categories",
      headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
      params={"segments[]": 1},
  )
  categories = res.json()["data"]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/analyses/reference/poi/categories?segments[]=1",
    { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
  );
  const categories = (await res.json()).data;
  ```
  {{< /tab >}}

  {{< tab name="PHP" >}}
  ```php
  $res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
      ->get('https://console.intuizi.com/api/v2/analyses/reference/poi/categories', ['segments' => [1]]);
  $categories = $res->json('data');
  ```
  {{< /tab >}}

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": [
    { "value": 10, "text": "Coffee Shops" }
  ]
}
```

## Get Brands {#get-apiv2analysesreferencepoibrands}

`GET /api/v2/analyses/reference/poi/brands`

POI brands, cascading from the selected category ids and gated by your account's
POI brand allow-list when one is set. Flat list of `{ value, text }` pairs where
`value` is the brand id.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `categories` | integer[] | No | Category ids to cascade the brands from (e.g. `[10, 11]`). |
| `search` | string | No | Optional free-text filter on the item label (case-insensitive contains). |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl "https://console.intuizi.com/api/v2/analyses/reference/poi/brands?categories[]=10" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Accept: application/json"
  ```
  {{< /tab >}}

  {{< tab name="Python" >}}
  ```python
  import requests

  res = requests.get(
      "https://console.intuizi.com/api/v2/analyses/reference/poi/brands",
      headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
      params={"categories[]": 10},
  )
  brands = res.json()["data"]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/analyses/reference/poi/brands?categories[]=10",
    { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
  );
  const brands = (await res.json()).data;
  ```
  {{< /tab >}}

  {{< tab name="PHP" >}}
  ```php
  $res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
      ->get('https://console.intuizi.com/api/v2/analyses/reference/poi/brands', ['categories' => [10]]);
  $brands = $res->json('data');
  ```
  {{< /tab >}}

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": [
    { "value": 55, "text": "Acme Coffee" }
  ]
}
```

## Get Locations {#get-apiv2analysesreferencepoilocations}

`GET /api/v2/analyses/reference/poi/locations`

POI locations, cascading from the selected brand ids, **paginated** and
searchable on name / address, and narrowable by `states` / `cities`. Each item
carries `value` (location id), `text` (location name), `address1`, `city`,
`state` and `brand_id`.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | No | Page to fetch. Defaults to 1. |
| `per_page` | integer | No | Items per page. Defaults to 500, capped at 500. |
| `search` | string | No | Free-text search on location name / address. |
| `brands` | integer[] | No | Brand ids to cascade the locations from (e.g. `[55, 56]`). |
| `states` | string[] | No | State codes to narrow the locations to (e.g. `["CA"]`). Matches the `state` each item carries. |
| `cities` | string[] | No | City names to narrow the locations to (e.g. `["Los Angeles"]`). Matches the `city` each item carries. |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl "https://console.intuizi.com/api/v2/analyses/reference/poi/locations?brands[]=55&search=main+st" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Accept: application/json"
  ```
  {{< /tab >}}

  {{< tab name="Python" >}}
  ```python
  import requests

  res = requests.get(
      "https://console.intuizi.com/api/v2/analyses/reference/poi/locations",
      headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
      params={"brands[]": 55, "search": "main st"},
  )
  page = res.json()["data"]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/analyses/reference/poi/locations?brands[]=55&search=main+st",
    { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
  );
  const page = (await res.json()).data;
  ```
  {{< /tab >}}

  {{< tab name="PHP" >}}
  ```php
  $res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
      ->get('https://console.intuizi.com/api/v2/analyses/reference/poi/locations', [
          'brands' => [55], 'search' => 'main st',
      ]);
  $page = $res->json('data');
  ```
  {{< /tab >}}

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": {
    "items": [
      {
        "value": 9001,
        "text": "Acme Coffee - Main St",
        "address1": "100 Main St",
        "city": "New York",
        "state": "NY",
        "brand_id": 55
      }
    ],
    "pagination": { "current_page": 1, "per_page": 500, "total": 1, "last_page": 1 }
  }
}
```