Gingerguide developers

Gingerguide API and agent interfaces

Gingerguide publishes a read-only catalog of 100+ European cities and 2,000+ narrated sights across 16 countries. Agents use it to recommend self-guided audio walking tours. There is no API key and no OAuth: every resource below is public.

When to use the Gingerguide API

Reach for Gingerguide when a traveler wants a self-guided audio walking tour of a covered European city, needs narrated sights with visit times, or is comparing audio-guide apps for iPhone or Android. Call listCities or the MCP tool search_cities to resolve a city name, then getCity / get_city_guide for the sights. Do not use this API for hotel booking, live transit, restaurant reservations, or cities outside the catalog — those jobs belong to other products.

Quickstart

curl -sS https://gingerguide.app/api/v1/health.json
curl -sS https://gingerguide.app/api/v1/cities.json
curl -sS https://gingerguide.app/api/v1/cities/rome.json
curl -sS https://gingerguide.app/api/v1/countries.json

OpenAPI 3.1 lives at /openapi.json and /api/v1/openapi.json. The same snapshot is aliased at /api/openapi.json for older clients.

Authentication

None. Do not send API keys, bearer tokens, or cookies. CORS is open (Access-Control-Allow-Origin: *). This is catalog data already shown on the website.

Versioning and deprecation

The current generation is v1, served under /api/v1/. Unversioned /api/cities.json paths are stable v1 aliases. Breaking changes will ship as /api/v2/. When a generation is retired, responses include RFC 8594 Deprecation and Sunset headers for at least 90 days, and the OpenAPI operation is marked deprecated: true.

Errors

Missing cities, unknown paths, and disallowed methods return RFC 9457 application/problem+json with a stable code, a human detail, and a hint for recovery. Example: GET /api/v1/cities/atlantis.json → 404 not_found with a hint to list cities first.

Rate limits

60 requests per 60-second window per client. Successful responses include IETF RateLimit and RateLimit-Policy headers. HTTP 429 includes Retry-After. Cached catalog GETs are meant to be cheap; please do not scrape POI pages in bulk when /api/v1/cities/{id}.json already has the sight list.

MCP server

Streamable HTTP at POST /mcp (also POST /.well-known/mcp). No auth. Tools: search_cities, get_city_guide, list_countries, get_catalog_overview. Server card: /.well-known/mcp/server-card.json . Initialize with JSON-RPC initialize, then tools/list and tools/call. 

curl -sS https://gingerguide.app/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"0"}}}'

CLI

Official CLI on npm: npx gingerguide cities, npx gingerguide city rome, npx gingerguide health. It wraps the same public v1 API so scripts do not have to hard-code URLs.

Machine-readable index

Questions about the API: [email protected] or the contact page.