# Basic air booking concepts

To begin using the Spotnana APIs for air bookings, you will need to first understand some basic concepts.

## Conceptual overview for booking air travel

If you wish to use the Spotnana APIs to search for flight options and book them, you need to understand the
following basic concepts:

- **Search** - Used to retrieve the flight offers you will use to book travel. Spotnana has separate APIs for air,
hotel, rail, and car bookings.
- **Itinerary** - This is a flight offer returned by an airline based on your search.
- **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.
- **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.


### Workflow

The basic air flow is represented below.

![Workflow](/assets/air-object-workflow.a9723a2ad770fd87169308a1ac81800237478c442bbf657a4eecfcbd69308c45.9c1bb791.png)

#### Search

To locate appropriate flight itineraries, you create a search. A `search` will provide results based on
information about the travelers, departure and arrival locations, and travel dates. The `search` will also include
other details, including flight attributes, amenities, cabin class, fares and fare rules.

#### Itinerary

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 `itinerary` contains a collection of `legs`
which
match the criteria you entered in your search. These legs, in turn, contain the `flights` that may be purchased from
the airline at a particular price. Each airline can return multiple itineraries, so the list can be large.

#### Leg

Within your `search`, you will specify the `leg`(s) the travelers wish to fly. Each `leg` represents the journey the
traveler wishes to make from their departure location to a particular destination location. You use an airport code
(**LAX** for Los Angeles International) or city name (**CHI** for Chicago) to specify the departure and destination
locations.

#### Flight

Within each `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 `flight` represents one particular segment of the
journey. For example, if the `flight` option were a direct non-stop flight from JFK to LAX, then the `flight` would
be for **JFK** to **LAX**. But, if it were for a one-stop **JFK** to **LAX** journey connecting through **ORD**, the
flight might just be the **JFK** to **ORD** segment.

#### Booking

Once you have located the itinerary you wish to purchase, you create a `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.

## Examples

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.

### One-way direct non-stop

In this example, let’s create a search for a traveler flying from John F. Kennedy airport (**JFK**) to Los Angeles
International airport (**LAX**).

Spotnana’s API sends the `search` to a variety of airlines and receives an itinerary from American Airlines,
that costs $270 USD. The `itinerary` will contain the `leg` that we specified, namely **JFK** to **LAX**. Within
that segment, we have just one `flight`, **JFK** to **LAX**, on non-stop American Airlines flight **AA33** on
**November 8**.

![Example of one-way direct](/assets/air-oneway-direct-example.5be6f8e539e1c5a9425337c82585d6e9d5e90c8a4fcf9398e51e7ea52622b76a.9c1bb791.png)

### One-way with connections

Now, let’s create another `search`, this time for the same locations, **JFK** and **LAX**, but allowing for up to
one stop. Within the `itinerary` that is returned from American Airlines for $184 USD, we find the `leg` we
requested, **JFK** to **LAX**, but there are now two `flights`.

- The first flight in the leg is from **JFK** to Chicago O’Hare International airport (**ORD**), on American
Airlines AA2819  on November 8.
- The second flight in the leg is from **ORD** to **LAX**, on American Airlines AA1800 on November 8.


![Example of one-way with connection](/assets/air-oneway-connection-example.c3aafaa656ee52b1319804ce1d4fa437bbf9b62b582d74bddfef675ca9817dd4.9c1bb791.png)

### Round Trip direct non-stop

Next, let’s create a `search` for a round trip non-stop journey for a traveler flying from New York (**NYC**) to
London (**LON**).

Spotnana’s API sends the `search` to its airline suppliers and receives many `itineraries`, among them, a non-stop
one from Iberia for $842 USD. Within this `itinerary`, there are the two legs we requested, **NYC** to **LON** on
December 8 and **LON** to **NYC** on December 13.

- Within the **NYC** to **LON** `leg`, there is only one `flight`, Iberia Airlines flight IB7377 operated by
British Airways and flying from John F. Kennedy (**JFK**) to London Heathrow (**LHR**) airport on December 8.
- Within the **LON** to **NYC** leg, there is one `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


![Example of round trip direct](/assets/air-roundtrip-direct-example.2384171baa3678856aa5ad1b06a26d6b202d715a8d1061ac6477da2e2f1bc107.9c1bb791.png)

### Round Trip with connections

Now, let’s create a `search` for a round trip journey for a traveler flying from Los Angeles International
Airport (**LAX**) to London (**LON**).

Spotnana’s API sends the `search` to its airline suppliers and receives an `itinerary` back from Virgin Atlantic
Airlines for $599 USD. Within this `itinerary`, there are the two `legs` we requested, **LAX** to **LON** on
December 9 and **LON** to **LAX** on December 14.

Within the **LAX** to **LON** `leg`, there is only one `flight`, Virgin Atlantic flight VS8 and flying from **LAX**
to London Heathrow (**LHR**) airport on December 9. However, inside the **LON** to **LAX** `leg`, we have two
flights:

- London Heathrow (**LHR**) to Charles de Gaulle Airport (**CDG**) being flown on VS6714 with Virgin Atlantic
on December 14.
- Charles de Gaulle Airport (**CDG**) to **LAX** being flown on VS6763 with Virgin Atlantic on December 14.


![Example of round trip with connection](/assets/air-roundtrip-connection-example.dfe1160359d92fee419af8334a25476c00c312bb2ae0e721d02da470e8618382.9c1bb791.png)

### Multi-city direct non-stop

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).

In this example, let’s create a `search` for **LAX** to O’Hare International Airport (**ORD**) on December 8 and
from **ORD** to London (**LON**) on December 14.

We get a bunch of itineraries back from the airlines, one of which is from Continental Airlines costing $680 USD.
Within this `itinerary` we have 2 `legs`, each with a single `flight`:

- **LAX** to **ORD** being flown on UA1332 with Continental on December 8.
- **ORD** to Heathrow Airport (**LHR**) being flown on UA920 with Continental on December 14.


![Example of multi-city direct](/assets/air-multicity-direct-example.c5c45762feec41cc031e381005f3dd6b9b052167924b2362d6c80c6234990f5f.9c1bb791.png)