Skyscanner Flight API Entegrasyonu: Developer Rehberi

POST /flights/live/search/create
        |
        v
initial / partial results
+ sessionToken
        |
        v
POST /flights/live/search/poll/{sessionToken}
        |
        v
progressively richer results
        |
        v
completed

Place discovery       -> Flights Autosuggest
Initial live search   -> /flights/live/search/create
Search completion     -> /flights/live/search/poll/{sessionToken}
Selected price refresh-> /flights/live/itineraryrefresh/create
Refresh completion    -> /flights/live/itineraryrefresh/poll/{refreshSessionToken}
Booking handoff       -> pricing option / agent deep link

search/create
   -> search/poll
   -> user selects itinerary
   -> itineraryrefresh/create
   -> itineraryrefresh/poll
   -> refreshed pricing options
   -> agent deeplink

SEARCH_PRICE
REFRESHING
REFRESHED
PRICE_CHANGED
HANDOFF_READY

x-api-key: <your-api-key>

interface SkyscannerCredentials {
  apiKeyRef: string;
}

Browser
  -> Your backend
      -> Skyscanner API

POST https://partners.api.skyscanner.net/apiservices/v3/flights/live/search/create
Content-Type: application/json
x-api-key: <api-key>

{
  "query": {
    "market": "TR",
    "locale": "tr-TR",
    "currency": "TRY",
    "queryLegs": [
      {
        "originPlaceId": {
          "iata": "IST"
        },
        "destinationPlaceId": {
          "iata": "LHR"
        },
        "date": {
          "year": 2026,
          "month": 10,
          "day": 12
        }
      }
    ],
    "adults": 1,
    "cabinClass": "CABIN_CLASS_ECONOMY"
  }
}

interface FlightSearchRequest {
  market: string;
  locale: string;
  currency: string;

  legs: Array<{
    origin: {
      iata?: string;
      entityId?: string;
    };
    destination: {
      iata?: string;
      entityId?: string;
    };
    departureDate: string;
  }>;

  passengers: {
    adults: number;
    childAges: number[];
  };

  cabinClass:
    | "economy"
    | "premium_economy"
    | "business"
    | "first";
}

Internal FlightSearchRequest
        |
        v
Skyscanner request mapper
        |
        v
Skyscanner create payload

{
  "sessionToken": "session-token",
  "status": "RESULT_STATUS_INCOMPLETE",
  "content": {
    "results": {
      "itineraries": {
        "itinerary-1": {
          "pricingOptions": []
        }
      }
    }
  }
}

type SearchStatus =
  | "created"
  | "partial"
  | "polling"
  | "complete"
  | "failed"
  | "expired";

POST https://partners.api.skyscanner.net/apiservices/v3/flights/live/search/poll/{sessionToken}
x-api-key: <api-key>

interface FlightSearchSession {
  id: string;
  provider: "skyscanner";
  providerSessionToken: string;
  requestHash: string;

  status: SearchStatus;

  createdAt: string;
  lastPolledAt?: string;
  completedAt?: string;

  pollCount: number;
}

poll 1 -> 300 ms
poll 2 -> 500 ms
poll 3 -> 800 ms
poll 4 -> 1200 ms
poll 5+ -> 1500-2000 ms

interface PollPolicy {
  maxDurationMs: number;
  maxPollCount: number;
  initialDelayMs: number;
  maxDelayMs: number;
}

interface FlightSearchViewState {
  status: "searching" | "partial" | "complete" | "error";
  itineraries: FlightItinerary[];
  lastUpdatedAt: string;
}

create
  -> first results render
  -> poll
  -> merge/deduplicate
  -> rerank
  -> render
  -> poll
  -> complete

Itinerary
  -> Leg
      -> Segment
          -> Carrier

Itinerary
  -> PricingOption
      -> Agent
      -> DeepLink

interface FlightItinerary {
  id: string;
  legIds: string[];
  pricingOptions: FlightPricingOption[];
  score?: number;
}

interface FlightLeg {
  id: string;
  origin: string;
  destination: string;
  departure: string;
  arrival: string;
  durationMinutes: number;
  segmentIds: string[];
  stopCount: number;
}

interface FlightSegment {
  id: string;
  origin: string;
  destination: string;
  departure: string;
  arrival: string;

  marketingCarrierId?: string;
  operatingCarrierId?: string;

  flightNumber?: string;
}

interface FlightAgent {
  id: string;
  name: string;
  type?: "airline" | "ota";
  rating?: number;
}

interface FlightPricingOption {
  id: string;

  agentIds: string[];

  price: {
    amount: number;
    currency: string;
  };

  deepLink?: string;

  transferType?: string;
  farePolicy?: string;
}

itinerary != offer

Skyscanner JSON
    |
    v
Provider DTO
    |
    v
Entity dictionaries
    |
    +--> itineraries
    +--> legs
    +--> segments
    +--> carriers
    +--> agents
    |
    v
Canonical flight model

function mergeSearchResults(
  current: FlightSearchResult,
  incoming: FlightSearchResult
): FlightSearchResult {
  // upsert entities by provider-stable id
  // replace/update pricing options
  // preserve newest provider state
  return current;
}

POST https://partners.api.skyscanner.net/apiservices/v3/autosuggest/flights

{
  "query": {
    "market": "TR",
    "locale": "tr-TR",
    "searchTerm": "Istanbul",
    "includedEntityTypes": [
      "PLACE_TYPE_CITY",
      "PLACE_TYPE_AIRPORT"
    ]
  },
  "limit": 10,
  "isDestination": false
}

interface FlightPlace {
  id: string;
  entityId?: string;
  iata?: string;
  name: string;
  type: "airport" | "city" | "country";
}

origin
+ destination
+ dates
+ adults
+ child ages
+ cabin
+ market
+ locale
+ currency

Discovery
  -> indicative/aggregated pricing

Booking intent
  -> Flights Live Prices

do not hammer retry
  -> exponential backoff
  -> jitter
  -> quota metric
  -> request suppression/cache

interface RetryPolicy {
  retryable: number[];
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
}

429
500
503
network timeout

SKYSCANNER_AUTH
SKYSCANNER_FORBIDDEN
SKYSCANNER_BAD_REQUEST
SKYSCANNER_RATE_LIMIT
SKYSCANNER_SESSION_INVALID
SKYSCANNER_TIMEOUT
SKYSCANNER_UPSTREAM
SKYSCANNER_PARSE
SKYSCANNER_EMPTY_RESULT
SKYSCANNER_DEEPLINK

interface FlightClickEvent {
  searchId: string;
  itineraryId: string;
  pricingOptionId: string;
  agentId: string;

  displayedPrice: number;
  currency: string;

  clickedAt: string;
}

search_created
time_to_first_result
time_to_complete
poll_count
itinerary_count
agent_count
api_429
api_5xx
empty_result
deeplink_click
deeplink_failure

{
  "searchId": "srch_123",
  "provider": "skyscanner",
  "market": "TR",
  "currency": "TRY",
  "route": "IST-LHR",
  "pollCount": 4,
  "providerStatus": "complete"
}

create success              >= 99%
time to first useful result <= product budget
poll completion             >= 98%
429 rate                    < agreed quota threshold
deeplink success            >= 99%
search error rate           < 1%

Search Request
   -> Skyscanner Adapter
   -> create
   -> partial normalize
   -> poll
   -> merge
   -> canonical itinerary
   -> pricing options
   -> agent deep link
   -> post-click quality measurement

same session + same entity revision -> idempotent upsert
older snapshot                 -> ignore
newer pricing state            -> replace/update