Overview

The empty leg search API offers the possibility to find information about available empty legs that could be of interest to the end client. With the given search criteria, which can be a start airport and/or an end airport along with a time span, the empty leg search algorithm tries to match available empty legs with the given input. Read more about how the empty leg search algorithm works in the info box below.

The information shown can include aircraft details, flight times, estimated prices (if available) etc. The end client can then request the best empty leg option. The request will be available as a lead in the Avinode Marketplace and will contain information about the requested empty leg, along with the end client’s contact information. The company owning the app can then access the lead directly in the Avinode Marketplace and use all the Marketplace features to find a suitable solution for the end client.

Important: Empty leg postings do not represent “Scheduled Flights”. Times and routes are flexible and need to be confirmed with the operator.

📘

Empty Leg Search explained

The empty leg search works a bit differently than the regular availability search in Avinode. For example, if the entered itinerary is from Paris to Rome, an empty leg search might return an empty leg from London to Rome since Paris is almost on that route.

The operator can in this case fly empty from London to Paris, pick up the passengers and fly them from Paris to Rome. The operator can then make some money on this otherwise non-profitable flight from London to Rome.

Similar matches are made if only the start airport or only the end airport is specified in the input. For example if the start airport is in San Francisco and no end airport is specified, then an empty leg from Los Angeles to New York can be returned since it is a relatively short distance between Los Angeles and San Francisco compared with the total distance of the empty leg.

Feasibility

For an empty leg to match it has to be deemed feasible in terms of the ratio between the distance of the empty leg segment (NM) and the requested distance (NM). If they differ too much the empty leg will not match.

Pre-requisites

Gaining an understanding of our APIs and fundamentals is essential to the success of your project. To do so, start by reading our introductions page, including the pages linked in the "Before you start" section.

Implementation and API Examples

Use case parts

This use case is implemented in one or more frontends, and in most cases, also includes a backend. Frontends are, in most cases, web interfaces on a company’s website or native mobile apps. The backend can be implemented with any technology preferred by the company, for example, Java, .NET, PHP, Python, Ruby, Go, etc. Using a backend is recommended and required if the frontend is a web interface. For a native mobile app it would be possible for a frontend to just communicate directly with the Avinode API servers.

Searchable aircraft

The information presented to the end client can be based on all empty legs available in the Avinode Marketplace matching the search criteria, or a subset of these. Brokers implementing this application usually base the information on all empty legs, while operators usually base the information on their own fleet.

Workflow

Find airports

The Airports API can be used to create features enabling the end client to find airports by entering airport or city names. The Airports API also returns the airport codes that are required when calling other API operations.

📘

Airport information source

The application can use a different source for airport information. However, this may increase the risk of errors, should that source have airport code information that does not match the airport code information available through the Avinode API services.

GET /airports/search

You can search airports using a text filter to match the airport code or name etc. or using Geo-location data and a max distance (radius). It is not possible to combine filter search with location search.

The results will be sorted by airport popularity based on usage data from the Avinode Marketplace.

See more at GET /airports/search

❗️

Abuse

Calling the service in any repetitive or automated manner to collect airport information is not allowed.

Find trip options

The end client specifies trip details like a start and/or end airport, a time span (in number of days out they are willing to fly) and pax numbers. The application then calls the empty leg search API service and presents the result as options to the end client.

Search for available empty legs

The application should call the POST /emptyleg/search operation with details regarding itinerary, pax numbers, days of flexibility and other potential criteria such as the subset of operators to include in the search.

This operation is used to find available empty legs currently published in the Avinode Marketplace. If the empty leg is priced the price will be available in the response. More information about available input parameters, and what can be included in the output, is described on the POST /emptyleg/search page.

End client request

This part of the implementation deals with when the end client wants to create a booking request. The booking request will be available as a client lead in the Avinode Marketplace for the company owning the API connection that was used. From here the Avinode member can perform the final sourcing of aircraft to suit the end client's needs.

It's also possible to download the client lead data into an external quoting tool, store the customer info etc., and then initiate a pre-filled aircraft search in Avinode directly from the external system, to avoid any double entry. See the Deep links section below.

Create the end client lead

The application should call the POST /leads operation with details about what the end client has requested, and also the end client’s contact information. This lead will show in the broker's Trips - Client Leads page in Avinode Marketplace, and from here it's easy to send a request on the chosen empty leg or alternatively to initiate an aircraft search from the given itinerary.

Client lead push notifications

There is also the option as a broker to subscribe to notifications for every incoming client lead that your application generates. Once notified, the lead data can be downloaded into an external quoting tool.

Read more about how to setup Avinode webhook notifications.

Deep links

When downloading the client lead to your backend system, there will be two deep links available in the response data, to use for opening up a new browser window with Avinode (see picture below):

• viewInAvinode - takes the broker directly to the newly created lead in Avinode with all the request information
• searchInAvinode - opens up a search in Avinode (based on the lead itinerary) that will be initiated immediately for further sourcing

Read more about working with deep links here.

Restrictions

Data displayed to the end client

Without explicit approval from Avinode, any information that can easily identify operators may not be displayed to the end client.

Storing data returned from the API operations

The application may only store data that is required to complete the business transaction with the end-client. So, for example, if the APIs returned information for 100 aircraft and the end-client makes a request for 2 of these, then any information about the other 98 aircraft may not be stored in the application’s backend storage.

Go Live!

👍

Implementation checklist

All items on this checklist must be implemented for an application of this type to be allowed to call the live production environment of Avinode Marketplace:

1. The application must comply with the Basic Go Live requirements.
2. If the Avinode Airport lookup API is used; when an end client is entering itinerary details, the application should call on the GET /airports/search endpoint for airport lookup.
   Note:The application is not allowed to call the service in any repetitive or automated fashion to collect airport information
3. The application calls on the POST /api/emptylegs/search endpoint with valid parameters to run an availability search.
4. The application successfully retrieves the search results response.
5. The application does not display any information (seller name, aircraft tail number, etc) or images from the search results that could easily identify the seller/operator.
6. The application does not store data retrieved from searches in its own back-end, nor does it build a “database” based on returned search results.
7. The application does not allow the end client to send out a request RFQ directly to an operator based on a search result. The empty leg preferred by the end client should be used to generate a lead in Avinode Marketplace.
8. The application calls on the appropriate POST /leads endpoint with valid parameters, which will generate a Client Lead in Avinode Marketplace.
9. The application does not store any data related to options that aren’t requested by the end client.