# POIs


Read your company's POI locations with **full detail** per location - address,
geography, geometry presence, brand, taxonomy and verification state. This is
your own POI data (everything imported through submissions), not the read-only
audience-building catalog under
[Dataset Types - POI]({{< relref "/api/v2/reference/poi" >}}). Both reads are
authenticated and JSON-only (bearer token + `Accept: application/json`) and use
the read rate bucket (120 requests/min per caller).

## List POIs

`GET /api/v2/my-data/pois/index`

The company's POI locations, most recent first, **paginated** and searchable.
Optional filters narrow by your own brand ids, country codes, or geometry
(`polygon` = locations that carry a polygon, `coordinates` = locations that
carry a lat/lon point).

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | No | Page to fetch. Defaults to 1. |
| `per_page` | integer | No | Items per page. Defaults to 25, capped at 500. |
| `search` | string | No | Free-text search on name, address, city, state, zip, DMA, external id and placekey (case-insensitive contains). |
| `brands` | integer[] | No | Own brand ids to filter by (from [Get Brands]({{< relref "/api/v2/poi/brands" >}})). |
| `countries` | string[] | No | Country codes to filter by (e.g. `["USA"]`). |
| `type` | string | No | Geometry filter: `polygon` or `coordinates`. Omit for all locations. |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl "https://console.intuizi.com/api/v2/my-data/pois/index?search=main+st&type=coordinates" \
    -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/my-data/pois/index",
      headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
      params={"search": "main st", "type": "coordinates"},
  )
  page = res.json()["data"]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/my-data/pois/index?search=main+st&type=coordinates",
    { 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/my-data/pois/index', [
          'search' => 'main st', 'type' => 'coordinates',
      ]);
  $page = $res->json('data');
  ```
  {{< /tab >}}

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": {
    "items": [
      {
        "id": 9001,
        "store_id": "S-100",
        "name": "Acme Coffee - Main St",
        "address1": "100 Main St",
        "address2": null,
        "city": "New York",
        "state": "NY",
        "zip_code": "10001",
        "dma_desc": "NEW YORK",
        "country": "USA",
        "lat": 40.7128,
        "lon": -74.006,
        "sqft": "1200",
        "max_trade_area": "5",
        "is_verified": true,
        "external_id": "ext-100",
        "placekey": "223-222@627-wc8-xyz",
        "time_zone": "EST",
        "category_taxonomy": "Food and Beverage",
        "sub_category_taxonomy": "Coffee Shops",
        "has_polygon": false,
        "brand": { "id": 55, "name": "Acme Coffee" },
        "created_at": "2026-07-01 10:00:00",
        "updated_at": "2026-07-01 10:00:00"
      }
    ],
    "pagination": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
  }
}
```

`has_polygon` reports whether the location carries polygon geometry; the raw
geometry itself is not exposed. `lat` / `lon` are `null` for polygon-only
locations.

## Get POI

`GET /api/v2/my-data/pois/{id}`

A single POI location by id, with the same full-detail shape as the list read.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | The POI location id (from [List POIs](#list-pois)). |

{{< tabs >}}

  {{< tab name="cURL" >}}
  ```bash
  curl "https://console.intuizi.com/api/v2/my-data/pois/9001" \
    -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/my-data/pois/9001",
      headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
  )
  poi = res.json()["data"][0]
  ```
  {{< /tab >}}

  {{< tab name="JavaScript" >}}
  ```javascript
  const res = await fetch(
    "https://console.intuizi.com/api/v2/my-data/pois/9001",
    { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
  );
  const poi = (await res.json()).data[0];
  ```
  {{< /tab >}}

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

{{< /tabs >}}

### Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "id": 9001,
      "store_id": "S-100",
      "name": "Acme Coffee - Main St",
      "address1": "100 Main St",
      "address2": null,
      "city": "New York",
      "state": "NY",
      "zip_code": "10001",
      "dma_desc": "NEW YORK",
      "country": "USA",
      "lat": 40.7128,
      "lon": -74.006,
      "sqft": "1200",
      "max_trade_area": "5",
      "is_verified": true,
      "external_id": "ext-100",
      "placekey": "223-222@627-wc8-xyz",
      "time_zone": "EST",
      "category_taxonomy": "Food and Beverage",
      "sub_category_taxonomy": "Coffee Shops",
      "has_polygon": false,
      "brand": { "id": 55, "name": "Acme Coffee" },
      "created_at": "2026-07-01 10:00:00",
      "updated_at": "2026-07-01 10:00:00"
    }
  ]
}
```