Following Search Best Practices

Introduction

Flight offer payloads can sometimes contain thousands of offers, making it difficult to manage and display content.
The Duffel API supports building many kinds of search flows, but depending on your needs you might need to tweak your requests to ensure relevance of results and improve performance.
This guide outlines some options to help you deliver the best possible experience for your users.

The Scenario

A return trip flight from JKF to MAD, can have 30 outbound departures and 20 inbound departures, resulting in 600 possible itineraries.
In addition, each itinerary offers 5 fare brands that can be combined with each other (e.g. selecting flexible economy on the outbound and premium economy on the inbound) resulting in 6,000 possible itineraries.
In some of the most popular flight routes we see the number of offers go up to the tens of thousands meaning a lot of content to manage and a heavy payload.
The first option is to develop a Multi-Step search flow experience using Partial Offer Request.
This flow is recommended over the Offer Request flow because it allows your users to select the slices of their flight offer, one at a time. This means payloads are way smaller and easier to manage, often leading to performance improvements.
For instance, a return trip would go as follows:
  • Select the outbound flight

  • Select the inbound flight

  • Select the fare brand for both flights

Referring to the JFK to MAD example, the Offer Request endpoint will return 6,000 full offers in a single payload while Partial Offer Request would section them out in: 30 outbound itineraries, 20 inbound itineraries, and lastly, 5 fare brand offers for each slice. This creates a much more manageable experience for you and your users, and it means processing a lot fewer offers!
Read more in the Multi-Step Search Guide or head directly to the Partial Offer Request reference.

Search Filters

Because airlines provide so very many options for flights it can be hard to find and quickly serve the right ones.
Duffel offers a series of Search Filters that can be used before sending a search request that notably reduce the number of offers.
The use of these filters prioritize relevant content to your users and optimize speed. We recommend using as many of these as possible in your integration, and in cases where it makes sense, setting them as default filters.

Cabin Class Filter

If you want your users to specify what cabin they want to fly in, you can add the cabin_classfilter to the request body.
This value is passed down to each airline, meaning you not only receive more relevant results, but also faster.

Shell

curl -X POST --compressed "https://api.duffel.com/air/offer_requests?return_offers=true"
-H "Accept-Encoding: gzip"
-H "Accept: application/json"
-H "Content-Type: application/json"
-H "Duffel-Version: v1"
-H "Authorization: Bearer $YOUR_ACCESS_TOKEN"
-d '{
"data": {
"slices": [
{
"origin": "MAD",
"destination": "JFK",
"departure_date": "2023-12-05"
},
{
"origin": "JFK",
"destination": "MAD",
"departure_date": "2023-12-10"
}
],
"passengers": [
{
"type": "adult"
}
],
"cabin_class":"first"
}
})
Read more in the Partial Offer Request reference and the Offer Request reference.

Max Connections

Using the max_connections filter on the request body, ensures your users only receive offers that have up to the specified number of connections.
We recommend setting this filter to either 0 or 1 to get the right balance of relevant content and search speed. Although, one can also set the value to 2 connections if looking for even more offers.
Today, Duffel defaults to searching up to 1 connection when no filter is specified.

Shell

curl -X POST --compressed "https://api.duffel.com/air/offer_requests?return_offers=true"
-H "Accept-Encoding: gzip"
-H "Accept: application/json"
-H "Content-Type: application/json"
-H "Duffel-Version: v1"
-H "Authorization: Bearer $YOUR_ACCESS_TOKEN"
-d '{
"data": {
"slices": [
{
"origin": "MAD",
"destination": "JFK",
"departure_date": "2023-12-05"
},
{
"origin": "JFK",
"destination": "MAD",
"departure_date": "2023-12-10"
}
],
"passengers": [
{
"type": "adult"
}
],
"max_connections": "0"
}
})
Read more in the Partial Offer Request reference and the Offer Request reference.

Departure and Arrival Time

This filter provides the fastest search experience if the user knows the flight they are looking for.
By providing the departure_time and/or arrival_time filters, we can limit the results to only those within the specified time frames.
This allows your users to e.g. search for all flights departing after 11am, or all flights arriving before 8pm. They can even specify if they want to depart and arrive between two specific times of the day.

Shell

curl -X POST --compressed "https://api.duffel.com/air/offer_requests?return_offers=true"
-H "Accept-Encoding: gzip"
-H "Accept: application/json"
-H "Content-Type: application/json"
-H "Duffel-Version: v1"
-H "Authorization: Bearer $YOUR_ACCESS_TOKEN"
-d '{
"data": {
"slices": [
{
"origin": "MAD",
"destination": "JFK",
"departure_time": {
"to": "11:00",
"from": "08:00"
},
"departure_date": "2023-12-05",
"arrival_time": {
"to": "17:00",
"from": "09:45"
}
},
{
"origin": "JFK",
"destination": "MAD",
"departure_date": "2023-12-10"
}
],
"passengers": [
{
"type": "adult"
}
],
}
})
Read more in the Partial Offer Request reference and the Offer Request reference.

Query Parameters

Controlling supplier timeout

Some searches take longer than others, and different users have different levels of tolerance for waiting.
The supplier_timeout allows you to specify on a per request basis, how long should a user wait for results.
A lower value is helpful if you are looking to favour speed over quantity of results, while a higher value favours more options.
By default, and as our recommendation, the Duffel API sets the limit at 20 seconds when the query parameter is unspecified.

Shell

curl -X POST --compressed "https://api.duffel.com/air/offer_requests?return_offers=true&supplier_timeout=10000"
-H "Accept-Encoding: gzip"
-H "Accept: application/json"
-H "Content-Type: application/json"
-H "Duffel-Version: v1"
-H "Authorization: Bearer $YOUR_ACCESS_TOKEN"
-d '{
"data": {
"slices": [
{
"origin": "MAD",
"destination": "JFK",
"departure_date": "2023-12-05"
},
{
"origin": "JFK",
"destination": "MAD",
"departure_date": "2023-12-10"
}
],
"passengers": [
{
"type": "adult"
}
],
}
})
Read more in the Partial Offer Request reference and the Offer Request reference.

Keep Learning

The above guide focused on best practices to optimally gather information for your users.
If you want some recommendations on how to display the information to your users or learn more about how does NDC power the modern flight booking experience, follow these articles: