LYVGO

OPEN API · v5

The LYVGO Unified Travel API

One read-only endpoint over the travel data LYVGO already licenses: events, live aircraft positions, routes, country facts, ride coverage and bounded AI summaries. No key, no signup.

2026-10-13

How answers behave

  • Every response is Cache-Control: no-store. Cache in your client, not in a shared proxy.
  • Each source reports its own status in sourceStates, so a partial answer is visible rather than silent.
  • AI endpoints only summarise the signals returned in the same response. They never invent prices, availability or providers, and they never name a model.
  • Event results come from the open GDELT index. Cite the article and link it — that is the licence.
  • Booking inventory is never returned, cached or stored. Search-time fares stay on the provider's page.

Endpoints

events

Dated events and activities for a place, discovered in the open news index.

Parameters: city, country, size

Sources: gdelt, gnews, newsdata, newsapi-org

Example /api/super?endpoint=events&city=Lisbon&size=8

trending-events

The same discovery without a place filter: what is on worldwide, de-duplicated by meaning.

Parameters: city, q, size

Sources: gdelt, gnews, newsdata, newsapi-org

Example /api/super?endpoint=trending-events&size=10

flights

Aircraft currently overhead one allowed airport, read from the open ADS-B network.

Parameters: airport, direction

Sources: adsb-open-network

Example /api/super?endpoint=flights&airport=LIS&direction=departure

transit

Door-to-door route for four coordinates.

Parameters: from_lat, from_lng, to_lat, to_lng

Sources: valhalla, here, osrm, ors

Example /api/super?endpoint=transit&from_lat=38.72&from_lng=-9.14&to_lat=41.15&to_lng=-8.61

country

Country reference facts by ISO code.

Parameters: code

Sources: country-io, countrywise

Example /api/super?endpoint=country&code=PT

ride-providers

Ride providers that operate in a country, best first.

Parameters: country

Sources: lyvgo-provider-directory

Example /api/super?endpoint=ride-providers&country=PT

knowledge

Books and reference works about a place, from the open Open Library index, cached and ranked by use.

Parameters: query, country, size

Sources: open-library

Example /api/super?endpoint=knowledge&query=Porto&size=6

tour-planner

Day-by-day tour plan for a destination: guide listings, walking legs and the forecast, from keyless open sources.

Parameters: destination, days, locale, country

Sources: openstreetmap, wikivoyage, open-meteo, overpass

Example /api/super?endpoint=tour-planner&destination=Porto&days=3&locale=en

ai-intent

Classifies a request into a travel mode and its place, origin and dates.

Parameters: query, locale

Sources: super-ai-v3

Example /api/super?endpoint=ai-intent&query=flights+to+Porto+in+May&locale=en

ai-brief

Summarises comparison options the caller already holds. Never invents prices.

Parameters: mode, origin, destination, depart, return, options

Sources: super-ai-v3

Example /api/super?endpoint=ai-brief&mode=flights&destination=Porto

ai-insight

Grounded insight about a destination, built only from the signals returned alongside it.

Parameters: query, locale, country

Sources: worldcities, airportcodes, airlabs, lyvgo-gtfs, countrywise, apidirect, super-ai-v3

Example /api/super?endpoint=ai-insight&query=Porto&country=PT

traveller-experience

What travellers report about a place, kept apart from verified facts and labelled as untrusted.

Parameters: query, locale, country

Sources: apidirect, super-ai-v3

Example /api/super?endpoint=traveller-experience&query=Lisbon&locale=pt

image-gen

Generate a travel-scene image from a prompt through the image cascade, tried in order and falling through on failure. Pollinations (a keyless public URL) and Workers AI (the first-party env.AI binding) answer with no credential at all; Puter is gated on PUTER_ENABLED plus PUTER_AUTH_TOKEN, and BytePlus, Gemini, OpenRouter and HuggingFace each need their own keys or console activations, so they report not_configured until supplied. Every result is labelled a generated illustration, never a photograph.

Parameters: prompt, width, height

Sources: pollinations, workers-ai, puter, byteplus, gemini, openrouter, huggingface

Example /api/super?endpoint=image-gen&prompt=sunset+over+Lisbon+rooftops&width=1024&height=1024

motion-plate

One wide illustration to sit behind live transit data - a single still generated through the same image cascade, so it answers with no credential today (Pollinations, Workers AI; the gated rungs report not_configured). The frame itself never moves; any motion on a board comes from the feed's own vehicle positions. Carries the generated-illustration provenance label.

Parameters: subject, width, height

Sources: pollinations, workers-ai, puter, byteplus, gemini, openrouter, huggingface

Example /api/super?endpoint=motion-plate&subject=Lisbon+tram+network+at+dusk&width=1536&height=864

video-gen

A short generated clip through the Puter video driver only. Not keyless: it reports not_configured immediately when PUTER_ENABLED plus PUTER_AUTH_TOKEN are absent and makes no call. Each synchronous attempt is bounded to a 30-second timeout (the driver's own range is 5s-600s) so no page request waits minutes; a multi-minute clip belongs to a build job, not this endpoint. A returned clip is labelled generated illustration, never footage.

Parameters: prompt, width, height, seconds

Sources: puter

Example /api/super?endpoint=video-gen&prompt=slow+pan+over+a+city+skyline&seconds=4&width=1280&height=720

activities

Tours, activities and experiences from the LYVGO Experiences catalogue for a destination.

Parameters: query, size

Sources: LYVGO Experiences

Example /api/super?endpoint=activities&query=Lisbon&size=12

activity-search

Rich LYVGO Experiences search with filtering (date, price, rating, duration, tags) and sorting.

Parameters: query, size, currency, date_from, date_to, min_price, max_price, min_rating, min_duration, max_duration, tags, sort

Sources: LYVGO Experiences

Example /api/super?endpoint=activity-search&query=Lisbon&sort=top_rated&size=12

activity-detail

Full detail for one LYVGO Experiences product by its product code.

Parameters: product_code

Sources: LYVGO Experiences

Example /api/super?endpoint=activity-detail&product_code=12345LIS

transport-locations

Transport location suggestions from the LYVGO Ground global rail, coach, ferry and flight database.

Parameters: query, size

Sources: LYVGO Ground

Example /api/super?endpoint=transport-locations&query=Bangkok&size=10

stay-destinations

Holiday-home destinations the LYVGO Stays feed publishes for a locale, as destination names only - no prices and no affiliate links are handed out.

Parameters: query, locale, size

Sources: LYVGO Stays

Example /api/super?endpoint=stay-destinations&query=Lisboa&locale=pt&size=8

ai-standings

How each model ranks per Super AI task, plus recent runs and the corrections in force. Aggregates only - no keys, no prompt text.

Parameters: task, unscored, limit

Sources: super-ai-memory

Example /api/super?endpoint=ai-standings&task=brief

ai-learn

Write path for the learning layer: grade a run, add or retire a correction. POST, admin-key gated; returns 503 until SUPER_AI_ADMIN_KEY is set.

Parameters: action, run_id, outcome, scope, scope_value, instruction, correction_id, priority

Sources: super-ai-memory

Example POST /api/super?endpoint=ai-learn {action: "grade", run_id, outcome: 0.9}

transit-catalog

Search the Mobility Database catalog for GTFS, GTFS-RT and GBFS transit feeds by text or country.

Parameters: query, country, size

Sources: mobility-database

Example /api/super?endpoint=transit-catalog&query=Lisbon&size=10

transitland-board

Live or scheduled departures for a TransitLand stop Onestop id (US/CA coverage). Cached and scheduled reads are labelled in the payload and are never passed off as live.

Parameters: stop, size

Sources: transitland

Example /api/super?endpoint=transitland-board&stop=s-fm2j-broadway+34st&size=14

osm-route

Door-to-door route geometry and timing via the public OSRM demo server. foot, bike and car are their own graphs; bus is accepted but is computed on the CAR graph and the response says so (profile_used, duration_basis, transit_eta_available:false) - it is never a bus ETA. 5-minute caching.

Parameters: from_lat, from_lon, to_lat, to_lon, profile

Sources: osrm

Example /api/super?endpoint=osm-route&from_lat=38.72&from_lon=-9.14&to_lat=38.74&to_lon=-9.13&profile=foot

ai-health

Generation and routing health for every AI provider rung: configured, cooling off, key presence (name and length only - values never leave the server) and evidence dates. Aggregates only - no keys, no prompt text.

Parameters: —

Sources: super-ai-v3, super-image, super-video, azure-key-vault

Example /api/super?endpoint=ai-health

Machine-readable contract: /api/super/openapi