AI Cars & Transfers API

Technical Docs Ground Transport Intelligence ETA Confidence + Matching Risk & Dispatch Scoring
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

1) Overview

Ground transport looks simple until you operate at scale: airport pickup regimes, curb restrictions, event traffic, provider reliability variance, and “last mile” timing chains with flights/hotels. Spyface models transfers as a probabilistic arrival problem: not “ETA = 42 min”, but “ETA distribution + confidence + best option under constraints”.

2) Use Cases

3) Quickstart

1. POST trip + traveler constraints to /v1/transfers/quote
2. POST returned options to /v1/transfers/rank
3. Confirm with /v1/transfers/book (optional) + subscribe to webhooks

4) Authentication

Authorization: Bearer YOUR_SPYFACE_API_KEY

5) Endpoints

6) Data Model

6.1 Quote Request (Airport Transfer Example)

{
  "request_id": "req_20260125_xfer_91f",
  "trip": {
    "pickup": {
      "type": "AIRPORT",
      "iata": "JFK",
      "lat": 40.6413,
      "lng": -73.7781,
      "local_time": "2026-03-12T18:20:00-04:00",
      "terminal": "4",
      "pickup_mode": "CURB"
    },
    "dropoff": {
      "type": "HOTEL",
      "name": "Midtown Hotel",
      "lat": 40.7580,
      "lng": -73.9855
    }
  },
  "traveler": {
    "party_size": 2,
    "bags": {"checked": 2, "carry_on": 2},
    "accessibility": {"wheelchair": false},
    "preferences": {"avoid_shared": true, "quiet_ride": true}
  },
  "constraints": {
    "latest_arrival_local": "2026-03-12T19:45:00-04:00",
    "max_price_usd": 160,
    "min_vehicle_class": "STANDARD"
  }
}

6.2 Quote Response (Normalized Options)

{
  "request_id": "req_20260125_xfer_91f",
  "currency": "USD",
  "options": [
    {
      "option_id": "opt_1",
      "provider": {"name":"ProviderA","service_level":"chauffeur"},
      "vehicle": {"class":"STANDARD","seats":3,"bags_capacity":4},
      "pricing": {"total": 98.50, "includes_tolls": true},
      "policy": {"free_wait_minutes_airport": 45},
      "raw": {"provider_ref": "A-99181"}
    },
    {
      "option_id": "opt_2",
      "provider": {"name":"ProviderB","service_level":"rideshare"},
      "vehicle": {"class":"PREMIUM","seats":3,"bags_capacity":3},
      "pricing": {"total": 132.00, "includes_tolls": false},
      "policy": {"free_wait_minutes_airport": 10},
      "raw": {"provider_ref": "B-77120"}
    }
  ]
}

6.3 ETA Response (Distribution + Confidence)

{
  "request_id": "req_20260125_eta_3a2",
  "option_id": "opt_1",
  "eta_minutes": {"p50": 44, "p90": 63},
  "on_time_probability": 0.86,
  "pickup_feasibility": {"score": 0.92, "regime": "AIRPORT_CURB_OK"},
  "risk_flags": ["EVENT_TRAFFIC_MODERATE"],
  "explanations": [
    {"code":"AIRPORT_BUFFER", "detail":"Airport pickup adds predictable curb/exit delay"},
    {"code":"TRAFFIC_REGIME", "detail":"Time-of-day congestion elevated vs baseline"}
  ]
}

7) ETA & On-time Model (Measurable)

Spyface does not ship a single “ETA number”. We ship a distribution. If your SLA requires arrival by a deadline, the only honest question is: P(arrive before deadline).

8) Vehicle Matching (Constraints)

Matching is not a marketing filter; it’s a hard feasibility check. Bags and accessibility constraints are frequent failure points in transfers.

9) Ranking Engine (Objective Function)

Ranking is deterministic and auditable. The AI feeds measured probabilities, while the ranker enforces business constraints.

// Conceptual scoring (example)
score(option) =
  w1 * on_time_probability
+ w2 * reliability_score
+ w3 * match_score
- w4 * normalized_price
- w5 * operational_risk

10) Risk Signals

11) Idempotency & Webhooks

Idempotency-Key: xfer_book_20260312_istjfk_0001

12) Code Examples

12.1 cURL — Quote

curl -X POST "https://api.spyface.com/v1/transfers/quote" \
  -H "Authorization: Bearer YOUR_SPYFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @quote-request.json

12.2 Node.js — Rank Options

import fetch from "node-fetch";

const payload = {
  request_id: "req_20260125_rank_19a",
  preset: "BEST_VALUE",
  deadline_local: "2026-03-12T19:45:00-04:00",
  options: optionsFromQuote // normalized options array
};

const res = await fetch("https://api.spyface.com/v1/transfers/rank", {
  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("Top option:", data.results[0].option_id);
console.log("Why:", data.results[0].explanations.map(e => e.code).join(","));

12.3 Python — ETA With Confidence

import os, requests

resp = requests.post(
  "https://api.spyface.com/v1/transfers/eta",
  headers={
    "Authorization": f"Bearer {os.environ['SPYFACE_API_KEY']}",
    "Content-Type": "application/json",
  },
  json={
    "request_id":"req_20260125_eta_3a2",
    "option": option,              # one option from /quote
    "deadline_local":"2026-03-12T19:45:00-04:00",
    "context":{"airport":"JFK","terminal":"4","pickup_mode":"CURB"}
  },
  timeout=10
)
resp.raise_for_status()
eta = resp.json()
print("p50:", eta["eta_minutes"]["p50"], "p90:", eta["eta_minutes"]["p90"],
      "P(on-time):", eta["on_time_probability"])

12.4 Outcomes → Calibration (high leverage)

Send actual pickup delay / travel time / no-show outcomes. This improves calibration and tail-risk estimates.

{
  "request_id": "req_20260125_xfer_91f",
  "events": [
    {"type":"OUTCOME_PICKUP_DELAY_MINUTES","value": 12, "ts":"2026-03-12T18:35:00-04:00"},
    {"type":"OUTCOME_TRIP_DURATION_MINUTES","value": 49, "ts":"2026-03-12T19:25:00-04:00"},
    {"type":"OUTCOME_NO_SHOW","value": false, "ts":"2026-03-12T18:34:00-04:00"}
  ]
}

13) Errors

14) Security

• Encrypt in transit (TLS). Do not send raw payment credentials.
• Minimize PII. Use pseudonymous traveler IDs when possible.
• Optional enterprise controls: IP allowlist, HMAC request signing, scoped keys.