AI Tours & Activities API

Technical Docs Intent Matching Conversion Scoring Itinerary-Aware Ranking
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

What this API actually solves

Tours & activities are not inventory problems. They are timing + intent + fatigue problems. Users abandon not because “nothing is available”, but because activities conflict with flights, hotels, energy level, or expectations.

The AI Tours & Activities API computes when, what, and why to show an activity — based on itinerary context, traveler intent, and conversion probability.

Primary outputs

Intent match score (experience fit)
Time-feasibility (arrival, fatigue, buffers)
Conversion probability per activity
Refund & no-show risk
Ranked list with explanation codes

1) Overview

An activity shown at the wrong time has a 0% chance of conversion. Spyface treats activities as schedule-bound experiences with probability of fit, not static products.

2) Use Cases

OTA / Destination Platforms

Increase attach rate post-flight or post-hotel booking
Reduce refund & no-show rates
Explain recommendations (“Why this tour now?”)

Medical Tourism

Recovery-safe experiences only
Fatigue & mobility-aware ranking
Exclude activities conflicting with treatment windows

3) Quickstart

POST available activities to /v1/activities/ingest
POST traveler + itinerary context to /v1/activities/rank
Render results using rank + explanation codes

4) Endpoints

Method	Endpoint	Purpose
POST	/v1/activities/ingest	Normalize activity inventory
POST	/v1/activities/intent	Infer traveler intent vector
POST	/v1/activities/feasibility	Check timing & fatigue feasibility
POST	/v1/activities/rank	Rank activities by objective function
POST	/v1/events	Send outcomes (click, book, refund)

5) Intent Modeling (No Buzzwords)

Intent is inferred from observable signals, not text prompts.

Trip type (business, leisure, recovery)
Duration & pace (short stay vs slow travel)
Previous bookings (culture, food, adventure)
Filters & scroll behavior

6) Time & Fatigue Constraints

Spyface enforces hard feasibility checks:

Arrival buffers (flight/rail delays)
Hotel check-in / check-out windows
Daily fatigue budget (hours + intensity)

7) Ranking Objective


score(activity) =
  w1 * intent_match
+ w2 * conversion_probability
- w3 * fatigue_penalty
- w4 * refund_risk
- w5 * timing_conflict_penalty

8) Sample Schema

{
  "activity_id":"act_7781",
  "category":"CULTURE",
  "duration_minutes":120,
  "intensity":"LOW",
  "start_times":["10:00","14:00"],
  "price":{"total":45,"currency":"USD"},
  "policies":{"refund":"24H_BEFORE"},
  "location":{"lat":41.01,"lng":28.97}
}

9) Code Example (Node.js)


const res = await fetch("https://api.spyface.com/v1/activities/rank", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    request_id:"req_act_001",
    traveler:{intent:"culture", pace:"slow"},
    itinerary:{arrival:"2026-03-12T09:30", hotel_checkin:"14:00"},
    activities: activities
  })
});
const data = await res.json();
console.log(data.results[0]);

10) Operational Advantage

Why this beats competitors

Most platforms rank by popularity → Spyface ranks by feasibility
Most ignore refunds → Spyface predicts them
Most don’t explain → Spyface is auditable