{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Basic air booking concepts","meta":[{"name":"robots","content":"noindex"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"basic-air-booking-concepts","__idx":0},"children":["Basic air booking concepts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To begin using the Spotnana APIs for air bookings, you will need to first understand some basic concepts."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conceptual-overview-for-booking-air-travel","__idx":1},"children":["Conceptual overview for booking air travel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you wish to use the Spotnana APIs to search for flight options and book them, you need to understand the"," ","following basic concepts:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Search"]}," - Used to retrieve the flight offers you will use to book travel. Spotnana has separate APIs for air,"," ","hotel, rail, and car bookings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Itinerary"]}," - This is a flight offer returned by an airline based on your search."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Leg"]}," - represents a portion of a journey with a departure location, arrival location, and a date. A one-way"," ","trip has one leg, a round-trip has two legs, and a multi-city trip has two or more legs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flight"]}," - A portion of a journey between two locations. Each segment that is part of that journey is represented"," ","by a flight. If the airline is offering a direct flight, then there will only be one flight included. If there"," ","are one or more connections required, each segment will be represented by its own flight."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"workflow","__idx":2},"children":["Workflow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The basic air flow is represented below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/docs/assets/air-object-workflow.a9723a2ad770fd87169308a1ac81800237478c442bbf657a4eecfcbd69308c45.9c1bb791.png","alt":"Workflow"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"search","__idx":3},"children":["Search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To locate appropriate flight itineraries, you create a search. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," will provide results based on"," ","information about the travelers, departure and arrival locations, and travel dates. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," will also include"," ","other details, including flight attributes, amenities, cabin class, fares and fare rules."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"itinerary","__idx":4},"children":["Itinerary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Spotnana API will search across GDS, NDC, and Low-Cost Carrier (LCC) airline inventory and return multiple"," ","itineraries. These represent the offers airlines have available. Each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]}," contains a collection of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legs"]}," ","which"," ","match the criteria you entered in your search. These legs, in turn, contain the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flights"]}," that may be purchased from"," ","the airline at a particular price. Each airline can return multiple itineraries, so the list can be large."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"leg","__idx":5},"children":["Leg"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Within your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]},", you will specify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]},"(s) the travelers wish to fly. Each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]}," represents the journey the"," ","traveler wishes to make from their departure location to a particular destination location. You use an airport code"," ","(",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," for Los Angeles International) or city name (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CHI"]}," for Chicago) to specify the departure and destination"," ","locations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"flight","__idx":6},"children":["Flight"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Within each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]},", you will receive a list of flights that match the departure and destination locations and times"," ","you requested. There may be one or more flights in the leg. Each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]}," represents one particular segment of the"," ","journey. For example, if the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]}," option were a direct non-stop flight from JFK to LAX, then the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]}," would"," ","be for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},". But, if it were for a one-stop ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," journey connecting through ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]},", the"," ","flight might just be the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]}," segment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"booking","__idx":7},"children":["Booking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have located the itinerary you wish to purchase, you create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["booking"]},", providing the ID of the relevant"," ","search and itinerary, as well as information about each of the travelers who will be traveling and any payment"," ","details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":8},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Since itineraries and segments will differ depending on whether your journey is one-way direct or with connections,"," ","round-trip direct or with connections, or a multi-city trip, we will provide some examples below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"one-way-direct-non-stop","__idx":9},"children":["One-way direct non-stop"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, let’s create a search for a traveler flying from John F. Kennedy airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]},") to Los Angeles"," ","International airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Spotnana’s API sends the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," to a variety of airlines and receives an itinerary from American Airlines,"," ","that costs $270 USD. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]}," will contain the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]}," that we specified, namely ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},". Within"," ","that segment, we have just one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},", on non-stop American Airlines flight ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AA33"]}," on"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["November 8"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/docs/assets/air-oneway-direct-example.5be6f8e539e1c5a9425337c82585d6e9d5e90c8a4fcf9398e51e7ea52622b76a.9c1bb791.png","alt":"Example of one-way direct"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"one-way-with-connections","__idx":10},"children":["One-way with connections"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now, let’s create another ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]},", this time for the same locations, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},", but allowing for up to"," ","one stop. Within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]}," that is returned from American Airlines for $184 USD, we find the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]}," we"," ","requested, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},", but there are now two ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flights"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The first flight in the leg is from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]}," to Chicago O’Hare International airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]},"), on American"," ","Airlines AA2819  on November 8."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The second flight in the leg is from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},", on American Airlines AA1800 on November 8."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/docs/assets/air-oneway-connection-example.c3aafaa656ee52b1319804ce1d4fa437bbf9b62b582d74bddfef675ca9817dd4.9c1bb791.png","alt":"Example of one-way with connection"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"round-trip-direct-non-stop","__idx":11},"children":["Round Trip direct non-stop"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next, let’s create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," for a round trip non-stop journey for a traveler flying from New York (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NYC"]},") to"," ","London (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Spotnana’s API sends the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," to its airline suppliers and receives many ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itineraries"]},", among them, a non-stop"," ","one from Iberia for $842 USD. Within this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]},", there are the two legs we requested, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NYC"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," on"," ","December 8 and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NYC"]}," on December 13."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Within the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NYC"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]},", there is only one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]},", Iberia Airlines flight IB7377 operated by"," ","British Airways and flying from John F. Kennedy (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JFK"]},") to London Heathrow (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LHR"]},") airport on December 8."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Within the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NYC"]}," leg, there is one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]},", Iberia Airlines flight IB4223 operated by American"," ","Airlines and flying from London Heathrow (LHR) airport to John F. Kennedy (JFK)  airport on December 1"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/docs/assets/air-roundtrip-direct-example.2384171baa3678856aa5ad1b06a26d6b202d715a8d1061ac6477da2e2f1bc107.9c1bb791.png","alt":"Example of round trip direct"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"round-trip-with-connections","__idx":12},"children":["Round Trip with connections"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now, let’s create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," for a round trip journey for a traveler flying from Los Angeles International"," ","Airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]},") to London (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Spotnana’s API sends the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," to its airline suppliers and receives an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]}," back from Virgin Atlantic"," ","Airlines for $599 USD. Within this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]},", there are the two ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legs"]}," we requested, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," on"," ","December 9 and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," on December 14."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Within the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]},", there is only one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]},", Virgin Atlantic flight VS8 and flying from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," ","to London Heathrow (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LHR"]},") airport on December 9. However, inside the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["leg"]},", we have two"," ","flights:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["London Heathrow (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LHR"]},") to Charles de Gaulle Airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CDG"]},") being flown on VS6714 with Virgin Atlantic"," ","on December 14."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Charles de Gaulle Airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CDG"]},") to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," being flown on VS6763 with Virgin Atlantic on December 14."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/docs/assets/air-roundtrip-connection-example.dfe1160359d92fee419af8334a25476c00c312bb2ae0e721d02da470e8618382.9c1bb791.png","alt":"Example of round trip with connection"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"multi-city-direct-non-stop","__idx":13},"children":["Multi-city direct non-stop"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next, we will try a multi-city trip. A multi-city trip is one with two or more legs (sometimes where"," ","one does not return from the original destination location)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, let’s create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," to O’Hare International Airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]},") on December 8 and"," ","from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]}," to London (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LON"]},") on December 14."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We get a bunch of itineraries back from the airlines, one of which is from Continental Airlines costing $680 USD."," ","Within this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itinerary"]}," we have 2 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legs"]},", each with a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flight"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LAX"]}," to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]}," being flown on UA1332 with Continental on December 8."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ORD"]}," to Heathrow Airport (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LHR"]},") being flown on UA920 with Continental on December 14."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/docs/assets/air-multicity-direct-example.c5c45762feec41cc031e381005f3dd6b9b052167924b2362d6c80c6234990f5f.9c1bb791.png","alt":"Example of multi-city direct"},"children":[]}]}]},"headings":[{"value":"Basic air booking concepts","id":"basic-air-booking-concepts","depth":1},{"value":"Conceptual overview for booking air travel","id":"conceptual-overview-for-booking-air-travel","depth":2},{"value":"Workflow","id":"workflow","depth":3},{"value":"Search","id":"search","depth":4},{"value":"Itinerary","id":"itinerary","depth":4},{"value":"Leg","id":"leg","depth":4},{"value":"Flight","id":"flight","depth":4},{"value":"Booking","id":"booking","depth":4},{"value":"Examples","id":"examples","depth":2},{"value":"One-way direct non-stop","id":"one-way-direct-non-stop","depth":3},{"value":"One-way with connections","id":"one-way-with-connections","depth":3},{"value":"Round Trip direct non-stop","id":"round-trip-direct-non-stop","depth":3},{"value":"Round Trip with connections","id":"round-trip-with-connections","depth":3},{"value":"Multi-city direct non-stop","id":"multi-city-direct-non-stop","depth":3}],"frontmatter":{"toc":{"enable":true,"maxDepth":3},"seo":{"title":"Basic air booking concepts"}},"lastModified":"2025-07-04T09:01:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/spotnana/basic_air_concepts","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}