AI Itinerary Optimization API

Core Decision Engine Constraint Optimization Multi-Modal Journeys Disruption-Resilient
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

What this API really is

The AI Itinerary Optimization API is not a planner. It is a constraint-based decision engine that composes flights, hotels, ground transport, and activities into a single optimized journey.

Most platforms assemble itineraries sequentially (flight → hotel → extras). Spyface optimizes the whole graph at once.

Primary outputs

Globally optimized itinerary (not greedy)
Arrival & completion probability
Total journey risk score
Cost–comfort–reliability tradeoff
Fallback & recovery paths

1) Overview

A journey is a dependency graph. Delays, fatigue, and policy constraints propagate forward. Optimizing components independently creates brittle itineraries.

2) Why Sequential Planning Fails

Legacy approach

Pick cheapest flight
Add closest hotel
Append transfers & activities

Result: hidden conflicts, missed check-ins, no-shows.

Spyface approach

Model full journey graph
Optimize under all constraints
Select itinerary with max success probability

Result: resilient, explainable journeys.

3) Optimization Model

The engine solves a constrained optimization problem:


maximize:
  P(journey_completed)
+ α * comfort_score
+ β * margin_score
- γ * total_cost
- δ * tail_risk

subject to:
  time_constraints
  policy_constraints
  fatigue_constraints
  accessibility_constraints
  budget_constraints

Predictions (ETAs, delays, availability) come from upstream Spyface APIs. Optimization is deterministic and auditable.

4) Constraints

Constraint	Description	Example
Time	Arrival, check-in, activity windows	No hotel check-in before flight arrival + buffer
Policy	Refund & payment rules	Non-refundable hotel avoided before risky flight
Fatigue	Daily energy budget	No high-intensity activity on arrival day
Accessibility	Mobility & special needs	Step-free transfers only
Budget	Total or per-leg limits	Transfers ≤ $120, total ≤ $2,000

5) Risk Propagation

Risk is propagated forward along the journey graph. A risky flight increases hotel no-show risk, which increases refund exposure.


flight_delay_risk
  → arrival_uncertainty
    → hotel_checkin_risk
      → activity_miss_risk

The optimizer penalizes paths where early risk compounds downstream.

6) Endpoints

Method	Endpoint	Purpose
POST	/v1/itinerary/optimize	Compute optimized itinerary
POST	/v1/itinerary/reoptimize	Re-optimize after disruption
POST	/v1/itinerary/explain	Explain decision & tradeoffs
POST	/v1/events	Send outcomes for calibration

7) Sample Schema

{
  "request_id":"req_itin_001",
  "traveler":{
    "party_size":2,
    "accessibility":{"step_free":true},
    "preferences":{"comfort":"HIGH"}
  },
  "constraints":{
    "arrive_by":"2026-03-12T18:00",
    "max_budget":2000
  },
  "components":{
    "flights":[...],
    "hotels":[...],
    "transfers":[...],
    "activities":[...]
  }
}

8) Code Example (Python)


import os, requests

resp = requests.post(
  "https://api.spyface.com/v1/itinerary/optimize",
  headers={
    "Authorization": f"Bearer {os.environ['SPYFACE_API_KEY']}",
    "Content-Type": "application/json"
  },
  json=payload
)

data = resp.json()
best = data["itineraries"][0]

print("Completion probability:", best["completion_probability"])
print("Total cost:", best["total_cost"])
print("Risk score:", best["risk_score"])

9) Re-optimization & Disruptions

Live recovery

Trigger re-optimization on flight delay or cancellation
Swap hotels or transfers automatically
Preserve as much of the journey as possible

This is where most competitors stop. Spyface continues.

Why this API is hard to copy

Requires probabilistic models + deterministic optimization
Needs cross-domain data consistency
Must be explainable for enterprise trust

For architecture reviews or pilot programs: hello@spyface.com