Catalog group classification

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 and group detail 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

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

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