# Mochi P.I.: instructions for AI agents

Mochi P.I. checks the records on NYC restaurants, bars and cafes: official licences, permits and inspections matched to each place, with dated evidence.

Use this site to pick an NYC restaurant, bar or cafe that satisfies a person's constraints. It covers 30,566 places. Every fact has a source, an observation date and an evidence snippet.

## Semantics
- A missing or null field means **unknown**, never "no" ("no matching license found in our snapshot"). Do not tell a user a place lacks something because the field is empty.
- Every fact has an `evidence_type`: `official_record` (NYC/NY State records), `business_claim` (the business's own website), `directory_category` (a listing category, e.g. "halal_restaurant"; not certification), or `extracted` (our inference).
- A liquor license means *licensed to serve*, not what is on the menu; an outdoor dining permit means *permission*, not that tables are out today.
- Health: `grade` is the **current** letter grade only; `status` may be Z (grade pending) or P, in which case `last_letter_grade` is older and not current.
- Dates on each fact: `observed_at` (source date), `valid_from`/`valid_until` (e.g. license term), `retrieved_at` (when we downloaded the source).
- Search constraints only match places with **positive evidence**. Few matches may mean thin evidence, not few places.
- `confidence` is our rough reliability estimate for a source/method, not a probability: public records ~1.0; website schema.org 0.8; website keyword mentions 0.6; chain-wide website facts scaled down. Prefer `evidence_type` when strictness matters.
- `all_known_matches_returned: true` means every place in our snapshot with evidence for all constraints is in the results.
- Nothing is paid placement.
- Confirm hours and availability on the linked website or booking page before acting.

## How to use it
No setup, keys or tools needed: everything is a plain GET URL.
Every page comes as HTML or JSON. For JSON, add `.json` to place/neighborhood URLs, add `format=json` to any URL, or send `Accept: application/json`.

## Search
`GET https://mochipi.com/search?...&format=json` (or `https://mochipi.com/api/search?...`, always JSON). Each result has `why`: the evidence for every constraint it matched. Parameters (all optional; repeat list params, e.g. `dietary=vegan&dietary=halal`):
- `query` (or `q`) - words matched against name, address, cuisine and neighborhood, e.g. `query=bean+post+pub+5th+avenue`
- `cuisine` - substring of a cuisine tag, e.g. `italian`, `sushi`, `cocktail bar`
- `type` - `restaurant` | `bar` | `cafe`
- `borough` - `Manhattan` | `Brooklyn` | `Queens` | `Bronx` | `Staten Island`
- `neighborhood` - NYC neighborhood, e.g. `West Village`, `Hell's Kitchen`, `Tribeca`; common names like `Koreatown`, `Nolita`, `FiDi`, `LIC`, `Bed-Stuy` also work
- `near_lat`, `near_lon`, `radius_m` (default 1000)
- `alcohol` - `any` | `full_bar`
- `outdoor_seating=1`, `reservations=1`
- `dietary` - vegan | vegetarian | gluten_free | halal | kosher
- `features` - private_dining | happy_hour | brunch | live_music | kids_menu | wheelchair_accessible | dog_friendly | byob | cash_only | walk_ins | catering | gift_cards
- `min_health_grade` - `A` | `B` (current letter grade; pending grades don't qualify)
- `evidence` - `any` (default) | `business` (official records + businesses' own claims) | `official` (public records only)
- `limit` - max 50

Example: `https://mochipi.com/api/search?cuisine=italian&neighborhood=West+Village&outdoor_seating=1&reservations=1&dietary=vegan`

## Pages
- Place: `https://mochipi.com/place/<slug>` and `https://mochipi.com/place/<slug>.json`: every fact with source, date, evidence, confidence.
- Neighborhood: `https://mochipi.com/n/<slug>` and `.json`: every place in it.
- Coverage, cuisine tags and neighborhood names: `https://mochipi.com/api/dataset`
- The same search in a browser: `https://mochipi.com/search`