---
title: "Parse User Query"
method: POST
path: "/api/v1/query/parse"
tags: ["query"]
---

# Parse User Query

`POST /api/v1/query/parse`

Parse a user query in real-time, returning structured layer identification.

This is a lightweight, stateless endpoint designed for debounced calls
as the user types, powering the live preview chips on the Canvas empty state.

## Request body

- QueryParseRequest — Request body for the real-time query parse endpoint.
  - `query_text` string, required — The user's natural language query to parse

## Response `200`

Successful Response

- QueryParseResponse — Lightweight real-time parse of a user query, used for live preview chips.
  - `items` QueryParseItem[] — Layers and enrichments identified from the query
    - `kind` 'layer' | 'enrichment', required — Whether a parsed item is a layer (from core dataset) or an enrichment.
    - `type` string, required — For layers: Overture Maps table name (e.g., 'division_area', 'building', 'place', 'segment', 'parcel'). For enrichments: enrichment tool name (e.g., 'General', 'Contacts', 'OwnerOccupied', 'TenantInfo').
    - `name` string, required — Human-readable name (e.g., 'Adams County Boundary', 'Commercial Buildings', 'Solar Potential')
    - `source_text` string, nullable — The exact substring from the user's query that this item was identified from
  - `requirements_met` RequirementsCheck, required — Tracks which key requirements from the query are satisfiable.
    - `location` boolean, required — Whether the query specifies a geographic location
    - `size_range` boolean, required — Whether any size/area criteria can be satisfied (building roof area, parcel lot size, etc.)
    - `use_type` boolean, required — Whether property type, use type, or zoning criteria can be satisfied (from buildings, parcels, or places)
    - `contextual_data` boolean, required — Whether contextual data needs (enrichments, POIs) can be satisfied
  - `warnings` string[] — Warnings for the user about the parsed geography.
  - `multi_geography_error` string, nullable — Error when the query targets multiple separate geographies (only one is supported per project)

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.net/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia-analytics/maia-api/versions/ba2b8d962161/schema)