Jettova for Developers

The Meet API

Where should a scattered group meet? Send everyone's home cities and get back destinations ranked by the whole group's total flight cost, travel time, or carbon, with per-person estimates for every option. It's the same fairness engine behind Jettova's group trips, as one endpoint.

Opening soon: we're preparing a small early-access cohort, and keys will be issued personally. Tell us what you're building to reserve a spot. Everything below documents the API as it will ship.

Endpoint

POST /api/v1/meet with your key in the Authorization header. CORS is open, so it works from a server or a browser.

curl -X POST https://www.jettova.com/api/v1/meet \
  -H "Authorization: Bearer jk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origins": ["Boston", "Berlin", "Tokyo"],
    "sort_by": "cost",
    "limit": 5,
    "major_hubs_only": true,
    "dates": { "start": "2026-09-10", "end": "2026-09-14" },
    "adults": 1
  }'

Request fields

• origins(required): 2 to 25 city names. Free text is fine; we resolve cities and major airports ("Boston", "berlin", "Mexico City").
• sort_by: cost (default), time, or co2.
• limit: results to return, 1 to 25 (default 10).
• major_hubs_only: restrict to ~50 major business hubs, built for corporate offsite use cases (default false).
• dates (optional): {"start", "end"} in YYYY-MM-DD. When provided, every ranked city returns prefilled booking links: hotels for the group, plus a flight search per member from their own airport for those exact dates. Your users go from "where should we meet" to booking in one step.
• adults (optional): traveler count for the hotel link, 1 to 8 (default 2).
• candidates(optional): score ONLY these cities. Built for decision support: your users already have a shortlist ("Austin, Denver, or Chicago?") and want the fairness numbers for exactly those. Unknown cities come back in meta.unmatched_candidates.
• exclude(optional): drop these cities from the ranking. The inverse of candidates ("anywhere but where we met last year").
• vibes (optional): restrict to destinations matching tags like beach, nightlife, adventure, from our curated destination data.
• countries (optional): restrict results to specific countries.
• max_member_flight_hours(optional): drop any city where even one member's estimated flight exceeds this. The "nobody suffers a 16-hour trek" constraint.
• max_avg_cost_usd (optional): drop cities above this estimated cost per person.

sort_by also accepts fairness, which minimizes the worst single member's journey instead of the group total. When you pass dates, each result includes expected_climate(warm, cold, or mixed) for that month, so "somewhere warm in January" is one request, and meta.date_info reports the number of nights and whether the window covers a weekend.

The Itinerary API

Once a destination is chosen, POST /api/v1/itinerary builds a full day-by-day plan for it: real named venues and restaurants, one free activity per trip, per-day and total cost estimates, and prefilled booking links when you pass dates. It's the same generation engine behind Jettova trips.

curl -X POST https://www.jettova.com/api/v1/itinerary \
  -H "Authorization: Bearer jk_live_YOUR_KEY" \
  -H "Idempotency-Key: your-unique-id-123" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "Lisbon",
    "days": 3,
    "vibes": ["foodie", "history"],
    "pace": "balanced",
    "dates": { "start": "2026-09-10", "end": "2026-09-13" }
  }'

• destination (required) and days (required, 1 to 14).
• vibes, pace (relaxed, balanced, packed), and budget_per_day_usd (all optional).
• dates and adults: unlock prefilled hotel and activity booking links, same as the Meet API.
• Idempotency: send an Idempotency-Key header. Because generation is billed per call, a retry with the same key returns the original itinerary without regenerating or double-charging your quota.

Refine an itinerary

Generation is a starting point; travelers edit. POST /api/v1/itinerary/refine takes an itinerary you generated with us plus a natural-language instruction ("make day 2 cheaper", "more seafood", "slow the pace down") and returns the complete updated itinerary with re-summed costs and a modified_dayslist. The destination can't be changed by an instruction; off-scope asks return a structured refusal with the itinerary unchanged. Send city, days (the array from a generate response), and instruction.

Multi-city trips

The Itinerary API also plans routes: pass legs instead of a single destination — {"legs": [{"city": "Lisbon", "nights": 3}, {"city": "Porto", "nights": 2}]} (2 to 4 legs) — and each leg comes back with its own days, an arrival_transport estimate (train, flight, bus, with duration and price), and per-leg hotel links on sequential date windows when you pass dates.

The Group-Trip API

The whole group decision in one call. POST /api/v1/group-trip takes members with home cities AND the dates each can travel — {"members": [{"origin": "Boston", "name": "Sam", "available": ["2026-09-10", ...]}]} — and returns the fairest cities for that exact group, the best travel window (who makes it, who misses it, with alternatives), and booking links per member from their own airport for those dates. Supports the Meet API's filters (major_hubs_only, vibes, countries, exclude, sort_by) plus trip_length_days. No scheduling tool connects availability to travel decisions; this is that connection as an endpoint.

The Video-to-Trip API (private preview)

The most Jettova thing we make: POST /api/v1/video-trip takes a TikTok or YouTube travel video URL your user pasted, reads the frames and caption, and returns the extracted trip intent (destination, vibe, activities, a confidence level) plus a full generated itinerary, with booking links when you pass dates. Analysis takes 5 to 15 seconds; send an Idempotency-Key so retries never double-bill.

• url(required): a TikTok or YouTube link, including Shorts. YouTube analysis uses only YouTube's public embed metadata and thumbnails; TikTok support is best-effort and may degrade without notice.
• days, dates, adults (optional): same semantics as the Itinerary API. Omit days to use the trip length the video suggests.
• official_sources_only(optional): restrict analysis to platform-documented endpoints. For TikTok this analyzes the official embed cover and caption instead of sampled video frames — confidence is typically lower, but every byte comes from TikTok's own documented API. YouTube analysis is official-sources by default. Built for partners whose compliance teams require it.
• Calls must be user-directed: your end user submits the specific URL. Nothing from the video is stored, and bulk or automated harvesting isn't permitted.

There's a photo counterpart too: POST /api/v1/photo-trip takes a base64 image your user uploaded (a screenshot, a saved travel photo) and runs the same extraction: destination, vibe, activities, confidence, and a generated itinerary. Since the user supplies their own image bytes, nothing is fetched from any platform at all.

Video-to-Trip and Photo-to-Trip are in private preview at premium per-call pricing. Tell us what you're building to get access.

Health check

GET /api/v1/health is unauthenticated and reports which products are live. Point your uptime monitor at it.

The destination catalog

GET /api/v1/destinations lists every city the API can rank: name, country, vibe tags, and whether it's a major business hub. Use it to build destination pickers and validate candidates before you submit. Optional query filters: country, vibe, major_hubs_only=true. Cacheable for an hour.

Every response also echoes your optional request_id (up to 64 chars) in meta, and carries X-Quota-Used / X-Quota-Limit headers.

Response

{
  "results": [
    {
      "rank": 1,
      "city": "Lisbon",
      "country": "Portugal",
      "total_est_cost_usd": 2140,
      "avg_est_cost_usd": 713,
      "total_flight_hours": 24.9,
      "max_member_flight_hours": 14.2,
      "total_co2_kg": 3462,
      "per_member": [
        {
          "origin": "Boston",
          "distance_km": 5185,
          "est_round_trip_cost_usd": 512,
          "est_flight_hours": 8.5,
          "flights_url": "https://..."
        }
      ],
      "booking": {
        "activities_url": "https://...",
        "hotels_url": "https://..."
      }
    }
  ],
  "meta": {
    "sort_by": "cost",
    "major_hubs_only": true,
    "currency": "USD",
    "note": "All figures are directional estimates for ranking, not bookable quotes."
  },
  "usage": { "month": "2026-07", "used": 12, "limit": 500 }
}

Every figure is a directional estimate for ranking, not a bookable quote. Unresolvable origins return a 422 listing exactly which inputs failed.

Pricing

All tiers are capped at 60 requests per minute, and quota state rides along in every response's usage object. This is the planned pricing for launch; early-access billing will be by simple monthly invoice, arranged through contact.

Booking links in responses carry Jettova's partner attribution by default. Want your own affiliate IDs in them instead? That's a Scale conversation.