# DishPulse: full API documentation

DishPulse is a pay-per-call API for finding dishes at real restaurants: search a dish by name in a city or near a point, list nearby restaurants, and read a restaurant's menu, with the price returned only when it was verified against the restaurant's own menu. Verified coverage is listed live at /v1/coverage and grows as records pass the checks.

### GET /v1/dishes?q=butter+chicken&city=toronto
- Price: $0.01 (10000 atomic USDC, 1 credits)
- Find a dish by name in a city or near a point: the restaurant, its address, and the dish price when it was verified against the restaurant's own menu.
- Parameters:
  - q (required): Dish words, 2 to 60 characters, for example: butter chicken
  - city: City key from /v1/coverage, for example: toronto
  - lat: Latitude, with lon, to search near a point
  - lon: Longitude, with lat
  - radius_km: Search radius in km when lat and lon are given: 0.1 to 25, default 5
  - limit: Results to return, 1 to 50, default 20

### GET /v1/near?lat=43.6677&lon=-79.3948&radius_km=2
- Price: $0.01 (10000 atomic USDC, 1 credits)
- Restaurants within a radius of a latitude and longitude, nearest first, with address, cuisines and distance. Optional cuisine filter.
- Parameters:
  - lat (required): Latitude in decimal degrees
  - lon (required): Longitude in decimal degrees
  - radius_km: Radius in km, 0.1 to 25, default 2
  - cuisine: Keep only restaurants with this cuisine, for example indian
  - limit: Results to return, 1 to 50, default 20

### GET /v1/restaurant?id=toronto-butter-chicken-factory
- Price: $0.01 (10000 atomic USDC, 1 credits)
- One restaurant by id: address, coordinates, cuisines, official website and every served menu item with its verified price and source.
- Parameters:
  - id (required): Restaurant id from /v1/dishes or /v1/near results

### GET /v1/city-pack?city=toronto
- Price: $0.25 (250000 atomic USDC, 25 credits)
- Every served restaurant in one city with all of its menu items, prices where verified, and sources: one call for a whole city.
- Parameters:
  - city (required): City key from /v1/coverage, for example: toronto

### GET /health
- No payment. Service status, data freshness and store connectivity.

### GET /v1/coverage
- No payment. Cities covered, restaurant and dish counts, and the data date.

### GET /tryit
- No payment. Static sample responses generated from the production code path.

## Coverage
DishPulse serves 2,667 restaurants and 42,785 menu items in 348 cities in 82 countries, 21,251 of them with a price verified against the restaurant's own menu, data as of 2026-11-05. Largest cities: toronto (187), burlington (100), mississauga (81), hamilton (76), brampton (71), oakville (68), markham (44), vaughan (43), richmond-hill (34), caledon (30), milton (30), whitby (29). Live numbers: GET https://dishpulse.waltsoft.net/v1/coverage.

## AWS Marketplace, MCP and A2A
- AWS Marketplace: the listing is "Waltsoft DishPulse". A subscription is billed on the buyer's AWS bill at $0.01 per unit, one unit per successful call; /v1/city-pack uses 25 units ($0.25). The key (mp_...) goes in the X-API-Key header or as a Bearer token.
- MCP (Amazon Bedrock AgentCore Gateway): https://waltsoft-marketplace-gateway-xncyjgs1uh.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp. Tools: dishpulse___searchDishes(q, city or lat and lon, api_key), dishpulse___findNearbyRestaurants(lat, lon, api_key), dishpulse___getRestaurant(id, api_key). The city pack is REST only.
- A2A (Agent2Agent): agent card at https://dishpulse.waltsoft.net/.well-known/agent-card.json. The Agent Communication Protocol (ACP) merged into A2A in 2025.

## Data sources and what each field means
- Restaurants: name, street address, coordinates and cuisines come from each restaurant's own website and published menus. Coordinates are geocoded from the street address.
- Dishes: names come from the restaurant's published menu; every dish carries its source_url.
- Prices: a price is returned only when it was verified against the restaurant's own menu (price_status starts with "verified"). Otherwise price is null and price_status says why. last_verified_at tells you when the check was made.
- Every successful response carries a source object (name, url, licence, attribution, data_as_of).

## Limits
- Coverage is the set of restaurants we could verify, not every restaurant in a city. GET /v1/coverage lists the cities and counts.
- Not included: ratings, reviews, photos, descriptions, delivery-app prices, dietary claims.
- A request that finds nothing answers 404 and is never charged. Bad parameters answer 400 before payment.

## Attribution
Data: Waltsoft DishPulse (https://dishpulse.waltsoft.net), compiled by Waltsoft Inc. from restaurants' own published information.

## Errors (never charged)
- 400 bad or missing parameters (checked before payment)
- 401 invalid API key
- 403 insufficient credits
- 404 nothing found for the request
- 503 data store temporarily unavailable

## Payment
- x402 v2, no signup: call a paid route without payment, read the 402 (body or PAYMENT-REQUIRED header), sign, retry with PAYMENT-SIGNATURE or X-PAYMENT. You are charged only if the answer is a success.
- Base: eip155:8453 USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 payTo 0x318A4B4764eb37c3FCBcE434713128143815FD57
- Solana: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v payTo GsKr5q9TmiJQcEgUpBp2X6SmvSg3dnXuw2uxYJxgPTk8
- Prepaid API key (card, one-time pack): buy at https://dishpulse.waltsoft.net/#buy, then send Authorization: Bearer dh_live_YOUR_KEY. One credit is $0.01; credits are refunded on any error.

## Provider
Waltsoft Inc. https://waltsoft.net/contact#contact