Following search best practices

Introduction

Flight offer payloads can contain thousands of options, which makes it difficult to manage and display useful content. Asterbyte supports multiple search patterns so your product can return relevant results and improve performance.

This guide outlines the choices that help you deliver a clear, fast experience for your travelers.

The scenario

A return trip from JFK to MAD can have dozens of outbound departures, inbound departures, and possible airline combinations.

Each itinerary can include several branded fares, while every fare can contain a different cabin, baggage policy, and change condition. On busy routes, the resulting number of offers grows quickly.

Multi-step search

A return itinerary works best as a staged search using a partial-offer request. This lets travelers choose the outbound journey before the API builds compatible returns.

For example, a round trip follows this sequence:

1. Select the outbound flight
2. Select the inbound flight
3. Select a fare brand for both journeys

For a JFK–MAD example, the first request may return 6,000 full offers. A staged flow instead starts with 30 outbound itineraries, 20 inbound options, and a handful of fares, creating a much smaller response at every step.

Search filters

Airlines expose many choices for each route. Use filters to keep the first result set focused, quick to scan, and economical to process.

Offer filters can live in the request body or the result layer of your application. Keep defaults broad enough to avoid empty states, but precise enough to protect response time.

Cabin class filter

If you want travelers to specify a cabin, add the cabin_class filter to the request body. Matching in the request returns only the relevant results and reduces payload size.

1 curl -X POST "$API_BASE/offer_requests" \
2   -H "Accept-Encoding: gzip" \
3   -H "Content-Type: application/json" \
4   -H "Authorization: Bearer $ACCESS_TOKEN" \
5   -d '{
6     "data": {
7       "cabin_class": "business",
8       "slices": [{
9         "origin": "JFK",
10        "destination": "MAD",
11        "departure_date": "2026-10-12"
12      }]
13    }
14  }'

Read more in the partial offer request and offer request references.

Maximum connections

Use the max_connections filter when travelers only want itineraries with a specific number of stops. Setting it to 0 returns direct journeys; setting it to 2 can return up to two connections.

We recommend keeping this filter visible near the primary results so travelers understand why a route may not appear.

1 curl -X POST "$API_BASE/offer_requests" \
2   -H "Content-Type: application/json" \
3   -H "Authorization: Bearer $ACCESS_TOKEN" \
4   -d '{
5     "data": {
6       "max_connections": 0,
7       "slices": [{
8         "origin": "JFK",
9         "destination": "MAD",
10        "departure_date": "2026-10-12"
11      }]
12    }
13  }'

Use connections together with cabin filters to keep result sets practical.

Departure and arrival time

This filter gives travelers the fastest way to find journeys that fit their day. Provide departure_time_from and arrival_time_to values for only the slices that need them.

Time values use the local clock at each airport. An overnight window may need two separate requests so the interface remains unambiguous.

1 curl -X POST "$API_BASE/offer_requests" \
2   -H "Authorization: Bearer $ACCESS_TOKEN" \
3   -d '{
4     "data": {
5       "slices": [{
6         "origin": "MAD",
7         "destination": "JFK",
8         "departure_time": {
9           "from": "08:00",
10          "to": "11:30"
11        }
12      }]
13    }
14  }'

See the request reference for accepted time formats and timezone behavior.

Some supplier searches take longer than others. The supplier_timeout parameter lets your application choose a suitable balance between response speed and breadth.

A smaller value helps fast-paced browsing. A larger value can be useful when travelers prefer exhaustive results and are willing to wait.

1 # Limit each supplier to 12 seconds
2 curl -X POST \
3   "$API_BASE/offer_requests?supplier_timeout=12000" \
4   -H "Authorization: Bearer $ACCESS_TOKEN" \
5   -d '{
6     "data": {
7       "slices": [{
8         "origin": "MAD",
9         "destination": "JFK",
10        "departure_date": "2026-10-12"
11      }],
12      "passengers": [{ "type": "adult" }]
13    }
14  }'

If a timeout is not specified, Asterbyte applies a safe platform default.

Keep learning

The patterns above can be combined to gather only the information your interface needs. For more product guidance, continue with these resources:

• Designing a modern flight-booking experience
• Why your customers will thank you for partial offers