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.
| Tool | Use it for |
|---|---|
get_catalog_overview | Coverage, languages, and the allowed category, interest and period values. |
search_cities | Resolve a city name (any of the six languages), country or region to a city id. |
list_countries | Covered 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_guide | One city: overview, headline sights, lesser-known sights, every sight. |
search_attractions | "Five Byzantine sights in Istanbul": text, category, interest, period, indoor/outdoor, distance. |
get_attraction | One 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_attractions | Sights closest to a latitude/longitude, with walking minutes. |
recommend_attractions | Personalized 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
- /llms.txt — when to use Gingerguide, plus every agent URL
- /openapi.json — OpenAPI 3.1
- /.well-known/api-catalog — RFC 9727 catalog
- /api/v1/index.json — JSON endpoint map
Questions about the API: [email protected] or the contact page.