Gingerguide developers

Gingerguide API and agent interfaces

Gingerguide publishes a read-only catalog of 275 European cities and 4,500+ narrated sights across 46 countries. Agents use it to recommend self-guided audio walking tours. No API key is required: every resource below is public. An optional free key raises the MCP server's daily limit.

When to use the Gingerguide API

Reach for Gingerguide when a traveler wants a self-guided audio walking tour of a covered 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

The REST API needs none. Do not send API keys, bearer tokens, or cookies to /api/v1/. CORS is open (Access-Control-Allow-Origin: *). This is catalog data already shown on the website. The MCP server also works without a key; an optional free key only raises its daily limit (see API key).

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.

Fair use

The REST API has no enforced rate limit: it is static JSON, cached at the edge. Please keep to about 60 requests per minute, and do not scrape POI pages in bulk when /api/v1/cities/{id}.json already has the sight list. The MCP server has its own enforced daily limits (see API key).

MCP server

Streamable HTTP at POST /mcp (also POST /.well-known/mcp). No key required (optional free key). Every tool is read-only and answers in English, Spanish, French, German, Turkish or Chinese (language argument). Server card: /.well-known/mcp/server-card.json . Initialize with JSON-RPC initialize, then tools/list and tools/call. Client configs (Claude, Cursor, VS Code), agent skills and the CLI source are on GitHub.

ToolUse it for
get_catalog_overviewCoverage, languages, and the allowed category, interest and period values.
search_citiesResolve a city name (any of the six languages), country or region to a city id.
list_countriesCovered countries with their city ids.
recommend_destinations"Best cities for Byzantine history", "art and food in Spain".
compare_cities"Porto or Lisbon?": two to four cities side by side, stronger city per interest or period.
find_day_trips"Day trips from Florence": nearby covered cities by distance and interests, with what to see.
get_city_guideOne city: overview, headline sights, lesser-known sights, every sight.
search_attractions"Five Byzantine sights in Istanbul": text, category, interest, period, indoor/outdoor, distance.
get_attractionOne sight: long description, notable fact, photo, map link, nearest sights, and visit facts where researched.
get_visit_info"Best time to visit Rome", "Civitavecchia to Rome": best months, getting to the centre, city passes, free sights, booking, weekly closing days. Researched cities only, each fact sourced and dated.
find_nearby_attractionsSights closest to a latitude/longitude, with walking minutes.
recommend_attractionsPersonalized picks: interests, periods, headline sights or hidden gems, time available.
plan_walking_tour"A two-hour historical walk in Rome": ordered stops, clock times, Google Maps link.
plan_trip_itinerary"Three days in Vienna": one or two walkable areas per day.

Interests, periods and indoor/outdoor are derived from each sight's category and description. Walking times are estimates (straight-line distance x 1.3). Day-trip and comparison distances are straight-line, with no travel times. Visit facts (get_visit_info, the free_only filter and the weekday option of the planners) exist for researched cities only; get_catalog_overview lists them. Opening hours and prices are not included.

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"}}}'

Optional free API key (MCP)

Without a key, the MCP server allows 1,000 tool calls per IP per UTC day. With a free key it allows 20,000 per key per day, and you can see your own usage. A key is useful when your agent runs on a shared cloud (Vercel, AWS, Cloudflare), where many apps share one outbound IP. There is no sign-up, no email, and no cost. Only tools/call counts; initialize and tools/list are free. Hosted assistants (Claude, ChatGPT) call from a few shared IPs for all their users, so their requests get 50,000 per IP per day.

Or from a terminal (the key is shown once; we store only its hash):

curl -sS -X POST https://gingerguide.app/api/keys \
  -H 'content-type: application/json' -d '{"label":"my-agent"}'

Send the key as a bearer token (or as X-API-Key):

curl -sS https://gingerguide.app/mcp \
  -H 'authorization: Bearer ggk_...' \
  -H 'content-type: application/json' -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_cities","arguments":{"query":"rome"}}}'

Usage for the last 30 days: GET /api/keys/me with the same header. Revoke: DELETE /api/keys/me. Tool-call responses carry RateLimit and X-RateLimit-Remaining headers. Over the limit, the tool returns an error result that says when the limit resets. An unknown or revoked key gets HTTP 401; remove the header to continue without a key. On Vercel, store the key with Vercel Connect (API key connector) and read it at runtime instead of hard-coding it.

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.