AI Flight Intelligence API

Technical Docs Prediction Pricing & Demand B2B
Operated by Spyface Tech Company, LLC • Support: hello@spyface.com

What this API does

AI Flight Intelligence API provides measurable prediction and scoring signals for: fare movement, demand intensity, availability stability, and booking timing. It sits after your flight search results and before your UX decisions (sorting, badges, alerts, price-lock, re-check logic).

Legacy stacks: search → sort by price.
Spyface: search → predict → optimize UX + margin + trust.

Primary outcomes

Higher conversion by surfacing “bookable & stable” fares
Lower checkout failures (reprice, sold-out)
Better margins via timing & elasticity signals
Fewer support tickets from “price changed” complaints

1) Overview

Flights are not “lowest price wins”. They are dominated by volatility and availability fragility. The same fare can reprice during checkout, disappear after 30 seconds, or become irrationally expensive due to demand shocks. Spyface converts raw itineraries into actionable, testable intelligence.

Inputs

Itineraries (segments, carriers, fare brand, baggage)
Price breakdown + taxes + currency
Search context (market, device, channel)
Optional events (clicks, shortlist, checkout start)

Outputs

Fare movement prediction (up/down/stable) + confidence
Demand score (route/date pressure)
Availability stability score (risk of sold-out/reprice)
Booking timing recommendation (buy now vs wait)

No buzzwords

Each AI field is tied to a label and evaluation metric: AUC, calibration error (ECE), Brier score, Lift@K, and live “checkout-fail reduction”.

2) Quickstart

POST your flight search results to /v1/flights/intelligence
Use returned scores to sort, badge and decide re-check steps
Optionally stream events to /v1/events for personalization

3) Authentication

Authorization: Bearer YOUR_SPYFACE_API_KEY

4) Endpoints

Method	Endpoint	Purpose
POST	/v1/flights/intelligence	Compute flight prediction & scoring bundle
POST	/v1/flights/fare-forecast	Predict fare movement within horizon
POST	/v1/flights/demand-score	Route/date demand pressure scoring
POST	/v1/flights/stability	Availability + reprice risk scoring
POST	/v1/events	Behavior signals (view, click, shortlist, checkout)

5) Data Model

5.1 Intelligence Request

{
  "request_id": "req_20260125_fli_19c2",
  "search": {
    "origin": "IST",
    "destination": "JFK",
    "depart_date": "2026-03-12",
    "return_date": "2026-03-19",
    "adults": 1,
    "cabin": "ECONOMY",
    "currency": "USD"
  },
  "context": {
    "market": "US",
    "channel": "web",
    "device": "desktop"
  },
  "itineraries": [
    {
      "itinerary_id": "it_001",
      "segments": [
        {"from":"IST","to":"JFK","dep":"2026-03-12T10:20:00Z","arr":"2026-03-12T20:05:00Z","carrier":"TK","flight_no":"1"}
      ],
      "price": {"total": 720.40, "currency":"USD"},
      "fare_brand": "LIGHT",
      "bags": {"carry_on": 1, "checked": 0},
      "provider": {"name":"gds_x"}
    }
  ]
}

5.2 Intelligence Response

{
  "request_id": "req_20260125_fli_19c2",
  "generated_at": "2026-01-25T12:00:00Z",
  "results": [
    {
      "itinerary_id": "it_001",
      "scores": {
        "fare_movement_up": 0.62,
        "fare_movement_down": 0.10,
        "fare_stability": 0.71,
        "demand_pressure": 0.77,
        "availability_stability": 0.84,
        "reprice_risk": 0.16
      },
      "recommendations": {
        "timing": "BOOK_NOW",
        "badges": ["Price likely to rise", "High bookability"],
        "recheck_policy": "STANDARD"
      },
      "explanations": [
        {"code":"DEMAND_HIGH","detail":"Route/date shows elevated demand vs baseline"},
        {"code":"STABLE_PROVIDER","detail":"Low historical reprice rate for this provider"},
        {"code":"UPWARD_DRIFT","detail":"Short-horizon upward movement probability is high"}
      ]
    }
  ]
}

6) Signals & Definitions

Signal	Meaning	How to use
fare_movement_up/down	Probabilities for direction within horizon	“Book now / wait” UX, alerts, price lock
fare_stability	Probability price won’t jump in near term	Top-rank stable fares for trust
demand_pressure	Route/date demand intensity	Scarcity messaging, merchandising
availability_stability	Probability itinerary remains bookable	Reduce checkout failures, choose recheck policy
reprice_risk	Probability price changes at checkout	Trigger “pre-price-check” or warning

7) Models (Measurable AI)

Model	Output	Labels	Metrics
Fare Movement	Up/Down/Stable probs	Observed price deltas over horizon	AUC, Calibration (ECE), MAPE (bucketed)
Availability Stability	P(bookable at checkout)	Success vs sold-out vs provider fail	Brier, Fail-rate reduction
Reprice Risk	P(reprice event)	Search→checkout price mismatch events	Precision/Recall, Lift@K
Demand Pressure	0–1 intensity score	Search volume + bookings + seasonality	Correlation w/ price drift, stability impact

8) Decision Patterns (How real teams use it)

Pattern A — Trust-first sorting

Sort by: availability_stability desc → fare_stability desc → price asc.

// pseudo
sortKey = 0.45*availability_stability + 0.35*fare_stability - 0.20*normalized_price

Pattern B — Checkout guardrails

if reprice_risk > 0.35 → run pre-price-check
if availability_stability < 0.60 → show backup fares in UI
if demand_pressure > 0.80 → compress results to “high confidence” subset

9) Code Examples

9.1 cURL

curl -X POST "https://api.spyface.com/v1/flights/intelligence" \
  -H "Authorization: Bearer YOUR_SPYFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @flight-intel.json

9.2 Node.js

import fetch from "node-fetch";

const res = await fetch("https://api.spyface.com/v1/flights/intelligence", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error(await res.text());
const data = await res.json();
console.log(data.results[0].recommendations);

9.3 Python

import os, requests

r = requests.post(
  "https://api.spyface.com/v1/flights/intelligence",
  headers={"Authorization": f"Bearer {os.environ['SPYFACE_API_KEY']}"},
  json=payload,
  timeout=10
)
r.raise_for_status()
print(r.json()["results"][0]["scores"])

10) Errors

HTTP	Meaning	Action
400	Schema invalid	Validate required fields
401	Unauthorized	Check Bearer token
429	Rate limited	Retry with exponential backoff
500	Internal	Retry once, then contact support

11) Security

Do not send payment card data.
Minimize PII; use hashed user_id if needed.
Optional enterprise HMAC signing available.

Integration review

Send a sanitized search payload + your current sorting logic to hello@spyface.com. We’ll propose a measurable rollout plan (A/B, KPIs, guardrails).