# Pizza Finder — agent instructions

Service ID: `nb:pizza-finder` · version 0.4.0 · status **Beta** · consumable: **true**

Beta live pizza discovery for the UK and US: search near a postcode or ZIP code, compare transparent distance and ranking evidence, and inspect date-stamped FSA hygiene ratings for exact matches in the UK.

> **Public beta.** Live discovery supports the United Kingdom (`country=GB`, UK postcode) and the United States (`country=US`, ZIP code). Call `GET https://api.niftibot.com/v1/search?postcode=SW1A%201AA&country=GB&mode=balanced&max_results=5&payment=false` for a free preview (five requests/minute/client IP). Stripe test checkout is $5 for 1,000 credits; only successful searches consume a credit. No live payments are enabled.

## Free REST demo workflow
1. Call `/v1/search` with a complete postcode/ZIP and `country=GB` or `country=US` plus `payment=false`; no key or payment is needed for the preview. `country` defaults to `GB` for compatibility.
2. Verify the country and postcode/ZIP before querying. A successfully completed paid search is not refundable for an input mistake.
3. Preserve Geoapify and OpenStreetMap attribution and any GB FSA rating date. A hygiene rating is not a customer review; FSA evidence is not provided for US results.
4. Treat missing price, fees, menu, delivery ETA and availability as unknown. Distance is straight-line from the postcode/ZIP centroid; ranking is a heuristic.
5. The service discovers venues only. It does not place orders, reserve tables, provide allergen advice or guarantee safety or fulfilment.
6. If the endpoint fails or the free demo is rate limited, report that and stop; do not substitute general search or memory.
7. Stripe credits are test mode only. Do not describe them as live payment or approved commercial pricing.

## Does not do
- food ordering or reservations
- menus, prices or delivery fees
- delivery ETA or current availability
- customer review ratings
- dietary suitability or allergen advice

## Connection
- Endpoint: https://api.niftibot.com
- Transport: http-rest
- Auth: none
- Manifest: /manifests/pizza-finder/0.4.0.json

## Tools

| Tool | Built | Read-only | Price |
|---|---|---|---|
| `pizza_search` | yes | yes | 0.01 USDC per call [x402-exact, not approved] |

## Data
- Coverage: Live, country-filtered pizza venue discovery for the United Kingdom (GB) and the United States (US) using Geoapify geocoding and Places search. Food Standards Agency hygiene data is available for the UK only and is attached only for a unique normalized venue-name and postcode match.
- Freshness: Places are queried live; FSA ratings include the source inspection/rating date and retrieval timestamp. A rating can be older than the query and may have changed since inspection.
- Supported countries (ISO 3166-1 alpha-2): GB, US
- Sources:
  - Geoapify Places and Geocoding (Geoapify service terms; attribute Geoapify and OpenStreetMap contributors)
  - OpenStreetMap (ODbL 1.0)
  - Food Standards Agency FHRS/FHIS API (Open Government Licence v3.0)

## Limitations
- Distance is straight-line from the postcode centroid, not road, walking or delivery distance
- Price, delivery fees, ETA, menus, customer reviews and availability stay unknown unless an authorized source supplies them
- Ranking scores express configured discovery preferences, not probability, quality assurance or fulfillment guarantees
- FSA data attaches only for unique exact normalized name/postcode matches; no match does not mean a venue lacks a rating
- Food Standards Agency hygiene evidence is UK-only; United States results do not include an equivalent official hygiene-rating source
- Specify the correct country with the postcode/ZIP. Successfully completed paid calls are not refundable for customer input mistakes
- The service does not place orders, reserve tables, or provide food-safety, allergen or dietary advice
- Public free preview is limited to five requests per minute per client IP; Stripe prepaid credits are test-only at $5 for 1,000 successful requests

## Rights
- Status: open_data
- Attribution: Powered by Geoapify
- Attribution: © OpenStreetMap contributors (ODbL)
- Attribution: Food Standards Agency open data (OGL v3.0)

## Open readiness blockers
- Public beta uses live Geoapify requests and optional FSA lookups; operator must monitor provider plan quotas and rate limits
- Stripe prepaid checkout is test mode only; live payments and commercial pricing are not enabled
- Search ranking is a discovery heuristic; prices, delivery, ETA, availability and consumer ratings are generally unknown

See also: /agents/payments.md · /agents/security.md · /agents/licensing.md