Developers

The catalogue, machine-readable

Max Eats Out is an editorially curated guide to restaurants and bars — 1,800 places across 51 cities, each one chosen and written up by hand. The same catalogue the website renders is available as a public REST API and as a remote MCP server for AI assistants. Both are anonymous, read-only and need no key.

It is a guide with a point of view, not a comprehensive places database. A venue’s absence means it is not on the list — not that it does not exist.

REST API

Base URL https://www.maxeatsout.club/api/public/v1. Every response is { data, meta }, CORS-enabled, and cacheable for an hour.

GET https://www.maxeatsout.club/api/public/v1/cities
GET https://www.maxeatsout.club/api/public/v1/cities/{slug}
GET https://www.maxeatsout.club/api/public/v1/venues?city={slug}&...
GET https://www.maxeatsout.club/api/public/v1/venues/{slug}
GET https://www.maxeatsout.club/api/public/v1/taxonomy

Start at /taxonomy: it publishes the complete filter vocabulary. Values outside it are rejected with a 400 and a suggestion rather than silently ignored, so a wrong guess costs one round trip instead of a wrong answer.

Searching

q is resolved against the guide’s own vocabulary — a cuisine, a dish, an area, a tag, a drink category, a Best For moment or a venue name — and the response reports the interpretation in meta.resolved. Words the guide has no concept for come back in meta.unresolved, and a query that resolves to nothing returns nothing rather than the unfiltered list.

GET https://www.maxeatsout.club/api/public/v1/venues?city=london&q=cocktails

"meta": {
  "resolved":   [{ "facet": "drinks", "value": "cocktails", … }],
  "unresolved": [],
  "total": 18
}

Reading a venue

Three kinds of statement are kept structurally apart, and it matters that they stay apart when you present them:

  • editorial — the guide’s own judgement: the note, Best For moments, what a venue is known for, awards.
  • practical — structured facts: seating, the door, ordering, payment, what they pour. null means unknown, and never means “no” — the scaled values carry three states (null, offered, known_for) and flattening them loses the point.
  • community — dish recommendations written by members, not by the guide.
  • branches[].provider — provider-derived identifiers (a Google Place ID). Useful for matching an entry to a place you already have; never a recommendation.

MCP

A remote MCP server lives at https://www.maxeatsout.club/api/mcp, speaking Streamable HTTP. It exposes four tools — search_venues, get_venue, list_cities and get_city — over the same catalogue the REST API serves, so the two never disagree.

{
  "mcpServers": {
    "max-eats-out": { "url": "https://www.maxeatsout.club/api/mcp" }
  }
}

Limits

The catalogue runs on a small budget, and the limits exist so that it keeps running. Per request: at most 50 results, 4 values per filter, 4 filters combined, a 64-character q, and pagination to the first 1,000 results.

Per client: roughly 120 requests a minute on the REST API and 60 on MCP. Going over returns 429 with a Retry-After header — back off for that many seconds and you will be fine. Responses cache for an hour, so repeating an identical request is free for both of us and is always preferable to re-querying.

Using it

No key, no sign-up, no rate-limit headers to manage. In return: please link to the venue’s canonical maxeatsout.club URL when you cite an entry — it travels in every response as url. The guide is one person’s work, and attribution is the whole payment.