Skip to content

Suggest a pickup time

Ask Transferz for a suggested pickup time based on the traveller's flight.

Updated · 3 min read

You will get a pickup time that fits the traveller's flight, and use it to request quotes. You need the route and the flight's arrival or departure time; the flight number makes the suggestion more accurate. Call this before Request quotes, because the quote request needs the pickup time.

Step 1: Ask for a suggestion

Send the route and the flight to Suggest pickup time. For a traveller landing at Schiphol on flight TZ1234 at 13:40:

POST/quotes/suggest-pickup-timeReference
Sign in to fill in your staging key. Sign in
curl --request POST \  --url 'https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY' \  --data '{  "origin": {    "iataCode": "AMS"  },  "destination": {    "address": {      "addressSearchPhrase": "Herengracht 182, Amsterdam",      "countryCode": "NL"    }  },  "departureOrArrivalTime": "2026-12-01T13:40:00",  "travelType": "INTERNATIONAL",  "roundToNearestMinutes": 15,  "flightNumber": "TZ1234"}'
Response 200
{  "directionality": "ARRIVAL",  "suggestedPickupTime": "2026-12-01T14:30:00",  "distanceInMeters": 19800,  "durationInMinutes": 26,  "bufferTime": 50}

What to send:

  • origin and destination (required), in the same format as a quote request. One of them must be a hub.
  • departureOrArrivalTime (required): the flight's local arrival time when the journey starts at the airport, or its local departure time when the journey ends there.
  • flightNumber: when given, Transferz looks the flight up and uses its scheduled time instead of departureOrArrivalTime, as long as the two are close. Otherwise your time is used.
  • travelType: INTERNATIONAL or DOMESTIC. It changes the buffer time. If you leave it out, Transferz takes it from the flight it found; without a flight a default buffer applies.
  • roundToNearestMinutes: rounds the result down to a multiple of this many minutes, for example 15. Leave it out for no rounding.
  • onlyCarryOnLuggage: accepted, but it does not change the result today.

Step 2: Use the suggested time in the quote request

Send suggestedPickupTime as pickupDateTime when you request quotes. It is a local time at the pickup location, like every pickup time. Show it to the traveller so they can change it if they want more or less time.

How the time is calculated

directionality is ARRIVAL when the journey starts at the hub and DEPARTURE when it ends there.

DirectionalitySuggested pickup timebufferTime covers
ARRIVALarrival time + bufferTimeGetting from the gate to the exit, including baggage and customs
DEPARTUREdeparture time − durationInMinutes − bufferTimeCheck-in, security and walking to the gate

bufferTime and durationInMinutes are in minutes; durationInMinutes is the expected drive time. The result is then rounded down to roundToNearestMinutes.

For the traveller's return flight, departing from Schiphol at 11:05 with a buffer of 180 minutes and a 26-minute drive, the calculation is 11:05 − 26 − 180 = 07:39, rounded down to 07:30:

POST/quotes/suggest-pickup-timeReference
Sign in to fill in your staging key. Sign in
curl --request POST \  --url 'https://warpdrive.staging.transferz.com/partners/quotes/suggest-pickup-time' \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY' \  --data '{  "origin": {    "address": {      "addressSearchPhrase": "Herengracht 182, Amsterdam",      "countryCode": "NL"    }  },  "destination": {    "iataCode": "AMS"  },  "departureOrArrivalTime": "2026-12-08T11:05:00",  "travelType": "INTERNATIONAL",  "roundToNearestMinutes": 15,  "flightNumber": "TZ1235"}'
Response 200
{  "directionality": "DEPARTURE",  "suggestedPickupTime": "2026-12-08T07:30:00",  "distanceInMeters": 19800,  "durationInMinutes": 26,  "bufferTime": 180}

The buffer and drive times in these examples are illustrations. The real values depend on the airport, the travel type and the route.

Errors

ProblemCauseWhat to do
400 with NO_HUB_SELECTEDNeither location is a hub.Make the origin or the destination an airport, port or station.
400 with LOCATION_NOT_FOUNDA location could not be resolved.Send a fuller address, coordinates or an IATA code.
400 with UNKNOWNThe route to the airport could not be calculated.Check the address; if it persists, let the traveller choose the time.
durationInMinutes and distanceInMeters are 0For an arrival, the route could not be calculated; only the buffer was added.Treat the suggestion as a minimum and let the traveller adjust it.
400 with a field, such as departureOrArrivalTimeA required field is missing.Send the field.

Next steps

Was this helpful?

Back to your build path: How a booking works →