# Catalog group classification

> Filter and read canonical group classifications through the SDK, and keep classification separate from grouping behavior and pricing eligibility.


Use catalog groups to share one building and neighborhood structure across your
directory, search controls, map, and property pages. Do not infer a building from
its name, URL slug, or marketing region.

## Read classifications

The [group list](https://developers.kismet.travel/api/reference/list-bookable-product-groups.md) and
[group detail](https://developers.kismet.travel/api/reference/get-bookable-product-group.md) operations expose
`classification.semanticType`:

| Value | Meaning |
| --- | --- |
| `BUILDING` | A building and its explicitly associated inventory |
| `NEIGHBORHOOD` | A top-level neighborhood that can contain building groups |
| `UNCLASSIFIED` | An ordinary or not-yet-classified group |

This is separate from `STANDARD` / `DROP`, which controls group behavior. Existing
groups are not automatically classified. An omitted or unfamiliar semantic type
does not prove eligibility for a building-specific interface; preserve that value
rather than relabelling it as `UNCLASSIFIED`.

## Filter catalog groups

```http
GET /v1/developer/collections/{collection}/bookable-product-groups?semanticType=BUILDING&limit=20
Authorization: Bearer YOUR_DEVELOPER_KEY
```

```ts
const buildings = await kismet.bookableProductGroup.list({
  semanticType: 'BUILDING',
  limit: 20,
});
const neighborhoods = await kismet.bookableProductGroup.list({
  semanticType: 'NEIGHBORHOOD',
});
```

The optional `semanticType` filter accepts the three canonical values above.
Omit it to read all authorized, published classifications. The server filters
before pagination; do not filter a single page locally and mistake it for the
complete catalog. Keep the same filter when following `page.nextCursor`. A cursor
outside that filtered set returns `INVALID_CURSOR`. Unsupported values, including
`STANDARD` and `DROP`, return `VALIDATION_ERROR`.

Each result returns `classification.semanticType`. Group pricing returns the
same field beside `groupId` and `groupSlug`, so the consumer does not need another
catalog lookup to identify the priced group. Older deployments can omit the field;
the SDK preserves absence rather than inventing a classification.

The pricing filter retains its existing name and value, `groupType=building`
(`groupType: 'building'` in the SDK). It selects `BUILDING` classification, not
internal grouping behavior. It does not enable neighborhood aggregate pricing.

The existing `parentVrGroupId` is the canonical management relationship. A
building can have one neighborhood parent in the same collection, or no parent.
A building cannot have children; a neighborhood is top-level. Use the published
group contract's parent relationship when composing public reads, rather than
inventing another taxonomy in frontend code.

## Manage through the User MCP

Catalog writes require an authenticated Kismet account with management permission
for the collection. A Developer API read key does not grant catalog management.
The public build-time [Developer MCP](https://developers.kismet.travel/mcp.md) supplies integration guidance; use
the authenticated **User MCP** to change catalog records.

1. Call `list_my_collections` to establish collection access and role.
2. Read `describe_schema` and the catalog guide, then `list_groups` and `get_group`.
   Inspect IDs, existing parents, classifications, and inventory membership.
3. Preview `update_group` with `semantic_type: "NEIGHBORHOOD"` for an existing,
   verified neighborhood. Review and approve the exact preview before confirming.
4. Preview each building with `semantic_type: "BUILDING"` and `parent_group_id`
   set to the verified neighborhood ID. Confirm only the approved change.
5. Re-read the groups to verify the resulting relationship and membership.

`create_group` accepts the same classification fields. Create missing groups as
drafts and explicitly associate their inventory; classification does not create
inventory associations or publish a group. To detach a building, set
`parent_group_id: null`. Omitted fields retain their current values.

Reassign or detach building children before changing their neighborhood to
another classification. Cross-collection parents are rejected. If a current
parent differs from your proposed mapping, resolve that discrepancy before
writing; do not silently overwrite it.

Authorized management REST clients use `semanticType` and `parentVrGroupId` on
the existing group create/update operations. Management lists accept a
`semanticType` filter. These are management operations, not public read-key
operations.

## Combine selections

For a Where multiselect, neighborhoods and individual buildings form a **union**:
expand each selected neighborhood through canonical parent IDs, then add the
explicitly selected buildings. A selected building outside the selected
neighborhood remains selected. Deduplicate by group ID, not display name.

## Availability and prices

Classification does not itself provide a building's lowest stay price. The
dated and rolling-90-day group pricing reads are described in
[Building availability and stay prices](https://developers.kismet.travel/guides/group-stay-pricing.md). Retain
your current fixture integration until the deployed API meets your coverage and
live verification requirements; a base-calendar estimate is not an all-plan minimum.

Do not compare undated nightly floors as if they were qualifying stay totals.
For a single “from” price, currencies and fee/tax inclusion bases must be
comparable and supplier rate-plan coverage must be complete. Otherwise show
**Check availability**, not zero or “sold out.” Missing evidence means unknown.

Keep the requested dates and guest count consistent across directory buttons,
map popups, and building pages. Use declared serving URLs for the requesting
host; staging navigation must stay on staging. TEST/LIVE credentials and
serving-host selection are separate concerns.

For an unpublished catalog preview, see [Staging catalog previews](https://developers.kismet.travel/guides/staging-catalog.md).