Suggest a pickup time
Ask Transferz for a suggested pickup time based on the traveller's flight.
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:
/quotes/suggest-pickup-timeReferencecurl --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"}'{ "directionality": "ARRIVAL", "suggestedPickupTime": "2026-12-01T14:30:00", "distanceInMeters": 19800, "durationInMinutes": 26, "bufferTime": 50}What to send:
originanddestination(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 ofdepartureOrArrivalTime, as long as the two are close. Otherwise your time is used.travelType:INTERNATIONALorDOMESTIC. 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.
| Directionality | Suggested pickup time | bufferTime covers |
|---|---|---|
ARRIVAL | arrival time + bufferTime | Getting from the gate to the exit, including baggage and customs |
DEPARTURE | departure time − durationInMinutes − bufferTime | Check-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:
/quotes/suggest-pickup-timeReferencecurl --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"}'{ "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
| Problem | Cause | What to do |
|---|---|---|
400 with NO_HUB_SELECTED | Neither location is a hub. | Make the origin or the destination an airport, port or station. |
400 with LOCATION_NOT_FOUND | A location could not be resolved. | Send a fuller address, coordinates or an IATA code. |
400 with UNKNOWN | The route to the airport could not be calculated. | Check the address; if it persists, let the traveller choose the time. |
durationInMinutes and distanceInMeters are 0 | For 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 departureOrArrivalTime | A required field is missing. | Send the field. |
Next steps
- Request quotes with the suggested time.
- Look up the traveller's flight to get its scheduled time and flight number.