DocsSupported query contract
Docs
Supported query contract
How to write Compass Search requests so agents get predictable, evidence-backed restaurant results.
Supported search shapes
| Field | Type | Notes |
|---|---|---|
| Discovery | query | Cuisine, dish, dietary, neighborhood, city, and general discovery phrases such as vegan ramen in Brooklyn or vegan pizza in Portland. |
| Named restaurants | query | Known restaurant or chain names can be searched when the restaurant is present in the current Compass corpus. Ordinary names retain their full spelling before a trailing locality fallback; confirmed eligible named targets stay ahead of unrelated recommendations. Unquoted text that matches no stored restaurant name runs as ordinary discovery, not an invented match. Quote the name or send restaurant= to get an explicit named_match no_confident_match. |
| Location | location | Use structured location.lat, location.lng, and optional location.radius_m for near me, nearby, around me, or radius-sensitive workflows. |
| Dish | dish | Optional explicit dish, maximum 120 characters. Compass returns the vegan dishes relevant to that request, not a complete menu. |
| Profile fit | user_profile | Use user_profile.diet, exclude_cross_contamination, and dietary_rules to request conservative per-result fit guidance. Religious and medical diets do not establish a supported vegan verdict. |
| Evidence depth | X-Compass-Mode | Use fast for compact result lists and rich for fuller evidence, query interpretation, and metadata. Both modes return the same v5 score components. |
Dishes
Search and Enrich return complete food menus with stored prices and ingredients. Matching dish lists remain request-specific.
Boundaries
| Field | Type | Notes |
|---|---|---|
| No location guessing | contract | Queries like near me require structured coordinates. Compass does not infer a user location from text alone. |
| No universal natural-language promise | contract | Compass supports common restaurant-agent phrasing, but free-form instructions should be converted into the documented request fields when possible. |
| No price or exclusion language | contract | under $20, open at 7, and without mushrooms are not supported query constraints. An explicit dish combined with one of those clauses is HTTP 400 unsupported_query_constraint. |
| No certification facts | contract | Accepted religious and medical diets do not establish a supported vegan verdict. Compass judges strict_vegan (and its alias vegan_options) from dishes, and vegetarian only from vegan evidence. pescatarian, halal, kosher, and low_fodmap are accepted but always return unknown with reason code DIET_NOT_SUPPORTED. Public responses do not expose halal-certified, kosher-certified, or free-from facts. Compass is not an allergen or safety service. |
| Unknown is valid | decision | When evidence is insufficient, stale, conflicting, or safety-sensitive, Compass returns conservative unknown guidance instead of pretending certainty. |
| Current corpus limits | coverage | If a named restaurant is absent from the current corpus, Search cannot invent it. Treat this as a coverage gap, not a formatting error. |
Recommended agent pattern
| Field | Type | Notes |
|---|---|---|
| 1 | parse | Extract cuisine, dish, named restaurant, city, coordinates, radius, and user profile from the user request. |
| 2 | structure | Send coordinates and radius in location, not only inside the query string, whenever the result set must be geographically bounded. |
| 3 | call | Use Search for discovery, Enrich for a known restaurant record, and Decision for profile-specific fit on a known compass_id. |
| 4 | explain | Show confidence, reason codes, source freshness, and verification guidance when the answer is safety-sensitive or evidence is incomplete. |