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 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 /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).

curl "https://console.intuizi.com/api/v2/analyses/reference/poi/segments" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

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"]

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;

Response

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

Get Categories

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).

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

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"]

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;

Response

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

Get Brands

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).

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

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"]

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;

Response

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

Get Locations

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.

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"

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"]

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;

$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');

Response

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

Cohorts Transactions