{"openapi":"3.1.0","info":{"title":"Guidavera","version":"1.0.0","summary":"Read-only access to an independent restaurant guide.","description":"Guidavera is an independent restaurant guide covering Barcelona, Spain; Mallorca, Spain. Every listing is verified by hand and no restaurant pays for placement. This document describes the public JSON API: a read-only, unauthenticated /api/v1 surface with two operations (the destinations Guidavera covers, and restaurant name search), each rate limited per IP with standard RateLimit response headers. Versioning and deprecation policy: the API is versioned in the URL path (/api/v1); breaking changes ship as a new versioned path, and the previous version keeps working for at least six months after a replacement ships, signalling retirement with Deprecation and Sunset response headers first. Beyond this JSON API, every page is also machine-readable as documents: llms.txt is the site index for agents, the homepage and every editorial guide serve Markdown on their own URL via the Accept: text/markdown header (or a /llms.md twin), and sitemap.xml lists every URL. Those document endpoints are described at https://guidavera.com/docs and https://guidavera.com/llms.txt.","contact":{"name":"Guidavera","url":"https://guidavera.com/contact","email":"hello@guidavera.com"}},"servers":[{"url":"https://guidavera.com"}],"paths":{"/api/v1/destinations":{"get":{"operationId":"listDestinations","summary":"List the destinations Guidavera covers","description":"Every destination in the guide, with entry URLs for its restaurant directory, hotel directory, food events hub and guides hub. Call it with no parameters to discover full coverage before searching.","parameters":[{"name":"country","in":"query","required":false,"description":"Filter destinations to one country by its slug. Omit for all destinations.","schema":{"type":"string","enum":["spain"]}}],"responses":{"200":{"description":"The covered destinations.","headers":{"RateLimit-Limit":{"description":"Requests allowed per window for this client.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"string"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Destination"}}}}},"400":{"description":"Unknown country parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded for this IP. Retry after the number of seconds in the Retry-After header.","headers":{"RateLimit-Limit":{"description":"Requests allowed per window for this client.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"string"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/restaurants/search":{"get":{"operationId":"searchRestaurants","summary":"Search restaurants by name","description":"Case-insensitive substring search over restaurant names in the selected destination. Returns at most 6 results, ordered starts-with first, then word-boundary matches, then substring matches. Each result links to the restaurant's page, which carries the full verified detail: consensus score, menu with prices, opening hours, Michelin and Repsol status, and structured JSON-LD.","parameters":[{"name":"q","in":"query","required":true,"description":"Restaurant name or name fragment, e.g. \"disfrutar\" or \"bar\".","schema":{"type":"string","minLength":1}},{"name":"city","in":"query","required":false,"description":"Destination to search. One of the registered city slugs, or \"all\" for every destination.","schema":{"type":"string","enum":["barcelona","mallorca","all"],"default":"barcelona"}}],"responses":{"200":{"description":"Matching restaurants (empty array when q is missing or nothing matches).","headers":{"RateLimit-Limit":{"description":"Requests allowed per window for this client.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"string"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/RestaurantSearchResult"}}}}},"400":{"description":"Unknown city parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded for this IP. Retry after the number of seconds in the Retry-After header.","headers":{"RateLimit-Limit":{"description":"Requests allowed per window for this client.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"string"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"Destination":{"type":"object","required":["slug","name","country","countrySlug","url","restaurants","hotels","foodEvents","guides"],"properties":{"slug":{"type":"string","description":"Destination slug used in URLs and the city search parameter.","enum":["barcelona","mallorca"]},"name":{"type":"string","description":"Destination name."},"country":{"type":"string","description":"Country name."},"countrySlug":{"type":"string","description":"Country slug used in URLs."},"url":{"type":"string","format":"uri","description":"Destination index page."},"restaurants":{"type":"string","format":"uri","description":"Ranked restaurant directory."},"hotels":{"type":"string","format":"uri","description":"Hotel directory."},"foodEvents":{"type":"string","format":"uri","description":"Food events hub."},"guides":{"type":"string","format":"uri","description":"Editorial guides hub."}}},"RestaurantSearchResult":{"type":"object","required":["slug","name","cuisine","neighborhood","city","country","url"],"properties":{"slug":{"type":"string","description":"Stable URL slug for the restaurant."},"name":{"type":"string","description":"Restaurant name."},"cuisine":{"type":"string","description":"Primary cuisine label."},"neighborhood":{"type":"string","description":"Neighbourhood within the destination."},"city":{"type":"string","description":"Destination city slug.","enum":["barcelona","mallorca"]},"country":{"type":"string","description":"Destination country slug."},"url":{"type":"string","format":"uri","description":"Canonical page for the restaurant (may 301 to a category path for bars, brunch and coffee venues)."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"docs":{"type":"string","format":"uri","description":"Where the surface is documented."}}}}}}}}