POST/v1/transfers/search
Consola API
Pruébalo
Envía una petición real al entorno sandbox e inspecciona la respuesta.
Credenciales
Inicia sesión para elegir entre tus API keys guardadas en vez de pegarlas.
Cuerpo de la petición
Petición cURL
bash
curl -X POST 'https://api.sandbox.travelandz.com/v1/transfers/search' \
-H 'Authorization: Bearer YOUR_SECRET_KEY' \
-H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
-H 'Content-Type: application/json' \
-d '{"mode":"one_way","startAddress":"433 Park Ave","startCity":"New York","startZipcode":"10022","endAddress":"JFK","pickupDatetime":"2026-08-16 15:30","numPassengers":2,"currency":"USD","responseMode":"complete"}'Añade tus credenciales para enviar una petición.
Respuesta
Pulsa «¡Pruébalo!» para enviar una petición y ver la respuesta aquí.
Busca ofertas de transfers y recibe una respuesta JSON completa o eventos progresivos en stream.
Autenticación y headers
| Header | Descripción |
|---|---|
Authorization | Bearer <secret_key>. Conserva el secret en el servidor y nunca lo escribas en logs del cliente. |
X-Travelandz-Id | <public_key>:<profile_code>, donde el profile code persistido usa el formato dp_<12 alfanuméricos>. |
LANG | Header recomendado para el idioma. También se acepta Accept-Language. |
Content-Type | application/json para peticiones con body JSON. |
Petición
Envía mode y numPassengers. Origen y destino requieren cada uno una dirección, un place ID o un par de latitud/longitud. Usa responseMode en stream para recibir las ofertas a medida que llegan en lugar de una única respuesta final. Una búsqueda round_trip requiere además returnPickupDatetime o returnFlightDatetime.
Schema del body
moderesponseModeDefaults to
complete.numPassengersInteger from 1 to 99.
startAddressSend an address, a place ID, or a latitude/longitude pair for the origin.
startCityAppended to the address to improve resolution.
startZipcodeAppended to the address to improve resolution.
startLatMust be sent together with
startLng.startLngMust be sent together with
startLat.startPlaceIdAlternative to an address or coordinates.
endAddressSend an address, a place ID, or a latitude/longitude pair for the destination.
endCityAppended to the address to improve resolution.
endZipcodeAppended to the address to improve resolution.
endLatMust be sent together with
endLng.endLngMust be sent together with
endLat.endPlaceIdAlternative to an address or coordinates.
pickupDatetimeLocal date and time at the origin.
flightDatetimeflightTypereturnPickupDatetimeA
round_trip search requires this field or returnFlightDatetime.returnFlightDatetimeA
round_trip search requires this field or returnPickupDatetime.amenitiesamenities[]Amenity keys to bias the search. Also accepted as a CSV string.
currencyLowercase values are accepted and normalized. Defaults to
USD on a new search and is inherited afterwards.campaignYour own campaign context.
branchRequires
campaign when sent.languageLegacy field. Prefer the
LANG or Accept-Language header.Ejemplo de petición
Respuesta completa
json
{
"mode": "one_way",
"startAddress": "433 Park Ave",
"startCity": "New York",
"startZipcode": "10022",
"endAddress": "JFK",
"pickupDatetime": "2026-08-16 15:30",
"numPassengers": 2,
"currency": "USD",
"responseMode": "complete"
}Respuesta en stream
json
{
"mode": "one_way",
"startAddress": "433 Park Ave, New York",
"endAddress": "JFK",
"pickupDatetime": "2026-08-16 15:30",
"numPassengers": 2,
"currency": "USD",
"responseMode": "stream"
}Respuesta exitosa
Devuelve transfers[] con las ofertas que pueden cotizarse y reservarse, más metadata con las ubicaciones resueltas y si el conjunto de resultados es definitivo. Cada oferta incluye un bookingToken opaco que copias en pricing.
Una búsqueda puede devolver 200 con metadata.timedOut: true. No es un error: las ofertas ya presentes son válidas y reservables.
Schema de respuesta
transferstransfers[]searchIdSend this value in pricing, booking and reservation reads.
transfers[]gdsprovidertransfers[]resultIdIdentifies the selected offer.
transfers[]bookingTokenOpaque value. Copy it into pricing and booking; never decode or modify it.
transfers[]expiresAtThe offer and its token stop being usable after this moment.
transfers[]vehicleIdtransfers[]totalAmountIndicative total for the offer in
currency.transfers[]currencytransfers[]bookableFalse when the offer cannot be booked.
transfers[]flightInfoRequiredWhen true,
airline and flightNumber are required to book.transfers[]extraPaxRequiredWhen true,
extraPaxInfo is required to book.transfers[]goodToKnowInfotransfers[]goodToKnowInfo[]Localized operational notes to show the traveller.
transfers[]supportstransfers[]cancellationPoliciestransfers[]cancellationPolicies[]noticeHours of notice the policy requires.
transfers[]cancellationPolicies[]refundPercenttransfers[]cancellationPolicies[]refundableUntilDatetimetransfers[]cancellationPolicies[]refundAmountRefundable amount in the offer currency.
transfers[]cancellationPolicies[]currencytransfers[]stepstransfers[]steps[]stepTypeLeg type, for example
car.transfers[]steps[]mainTrue for the primary leg of the transfer.
transfers[]steps[]descriptiontransfers[]steps[]departureDatetimetransfers[]steps[]durationMinutestransfers[]steps[]durationSecondstransfers[]steps[]distanceMeterstransfers[]steps[]distanceMilestransfers[]steps[]lineNamePresent for scheduled line transport.
transfers[]steps[]lineColortransfers[]steps[]providertransfers[]steps[]providernametransfers[]steps[]providerratingtransfers[]steps[]vehicletransfers[]steps[]vehicletypeVehicle name, for example
Shared Ride Van.transfers[]steps[]vehiclecategoryVehicle grouping, for example
Shared or Private.transfers[]steps[]vehiclemaxBagstransfers[]steps[]vehiclemaxPassengerstransfers[]steps[]vehiclenumVehiclestransfers[]steps[]vehicleimageUrltransfers[]steps[]waitTimetransfers[]steps[]waitTimeincludedtransfers[]steps[]waitTimeminutesIncludedtransfers[]steps[]waitTimeextraWaitTimeChargeabletransfers[]steps[]amenitiestransfers[]steps[]amenities[]keyValue to send in
selectedAmenities.transfers[]steps[]amenities[]nameLocalized name.
transfers[]steps[]amenities[]descriptiontransfers[]steps[]amenities[]imageUrltransfers[]steps[]amenities[]pngImageUrltransfers[]steps[]amenities[]inputTypetransfers[]steps[]amenities[]includedTrue when the amenity is already part of the offer.
transfers[]steps[]amenities[]selectableTrue when the amenity can be added to this offer.
transfers[]steps[]amenities[]selectedTrue when the amenity is part of the priced selection.
transfers[]steps[]startLocationtransfers[]steps[]startLocationformattedAddresstransfers[]steps[]startLocationfullAddresstransfers[]steps[]startLocationiataCodePresent for airport locations.
transfers[]steps[]startLocationicaoCodetransfers[]steps[]startLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]startLocationlatitudetransfers[]steps[]startLocationlongitudetransfers[]steps[]startLocationtimezoneIANA timezone of the location.
transfers[]steps[]endLocationtransfers[]steps[]endLocationformattedAddresstransfers[]steps[]endLocationfullAddresstransfers[]steps[]endLocationiataCodePresent for airport locations.
transfers[]steps[]endLocationicaoCodetransfers[]steps[]endLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]endLocationlatitudetransfers[]steps[]endLocationlongitudetransfers[]steps[]endLocationtimezoneIANA timezone of the location.
transfers[]ticketTypestransfers[]ticketTypes[]idSend this value in
ticketTypes[].id when booking.transfers[]ticketTypes[]nametransfers[]ticketTypes[]departureDatetimetransfers[]ticketTypes[]arrivalDatetimetransfers[]alternativeTimestransfers[]alternativeTimes[]departureDatetimetransfers[]alternativeTimes[]arrivalDatetimemetadatametadatacompletedTrue when the result set is final.
metadatatimedOutTrue when results were returned before every source finished. The offers already present are valid.
metadataproviderResultsmetadataproviderResults[]gdsprovidermetadataproviderResults[]searchIdmetadataproviderResults[]completedTrue when this source has no further offers to return.
metadataproviderResults[]timedOutmetadataproviderResults[]moreComingTrue when more offers may still arrive for this
searchId.metadatastartLocationmetadatastartLocationformattedAddressmetadatastartLocationfullAddressmetadatastartLocationiataCodePresent for airport locations.
metadatastartLocationicaoCodemetadatastartLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadatastartLocationlatitudemetadatastartLocationlongitudemetadatastartLocationtimezoneIANA timezone of the location.
metadataendLocationmetadataendLocationformattedAddressmetadataendLocationfullAddressmetadataendLocationiataCodePresent for airport locations.
metadataendLocationicaoCodemetadataendLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadataendLocationlatitudemetadataendLocationlongitudemetadataendLocationtimezoneIANA timezone of the location.
metadatapickupDatetimeResolved pickup moment in the origin timezone.
metadatanumPassengersSchema de respuesta (responseMode=stream)
transferstransfers[]searchIdSend this value in pricing, booking and reservation reads.
transfers[]gdsprovidertransfers[]resultIdIdentifies the selected offer.
transfers[]bookingTokenOpaque value. Copy it into pricing and booking; never decode or modify it.
transfers[]expiresAtThe offer and its token stop being usable after this moment.
transfers[]vehicleIdtransfers[]totalAmountIndicative total for the offer in
currency.transfers[]currencytransfers[]bookableFalse when the offer cannot be booked.
transfers[]flightInfoRequiredWhen true,
airline and flightNumber are required to book.transfers[]extraPaxRequiredWhen true,
extraPaxInfo is required to book.transfers[]goodToKnowInfotransfers[]goodToKnowInfo[]Localized operational notes to show the traveller.
transfers[]supportstransfers[]cancellationPoliciestransfers[]cancellationPolicies[]noticeHours of notice the policy requires.
transfers[]cancellationPolicies[]refundPercenttransfers[]cancellationPolicies[]refundableUntilDatetimetransfers[]cancellationPolicies[]refundAmountRefundable amount in the offer currency.
transfers[]cancellationPolicies[]currencytransfers[]stepstransfers[]steps[]stepTypeLeg type, for example
car.transfers[]steps[]mainTrue for the primary leg of the transfer.
transfers[]steps[]descriptiontransfers[]steps[]departureDatetimetransfers[]steps[]durationMinutestransfers[]steps[]durationSecondstransfers[]steps[]distanceMeterstransfers[]steps[]distanceMilestransfers[]steps[]lineNamePresent for scheduled line transport.
transfers[]steps[]lineColortransfers[]steps[]providertransfers[]steps[]providernametransfers[]steps[]providerratingtransfers[]steps[]vehicletransfers[]steps[]vehicletypeVehicle name, for example
Shared Ride Van.transfers[]steps[]vehiclecategoryVehicle grouping, for example
Shared or Private.transfers[]steps[]vehiclemaxBagstransfers[]steps[]vehiclemaxPassengerstransfers[]steps[]vehiclenumVehiclestransfers[]steps[]vehicleimageUrltransfers[]steps[]waitTimetransfers[]steps[]waitTimeincludedtransfers[]steps[]waitTimeminutesIncludedtransfers[]steps[]waitTimeextraWaitTimeChargeabletransfers[]steps[]amenitiestransfers[]steps[]amenities[]keyValue to send in
selectedAmenities.transfers[]steps[]amenities[]nameLocalized name.
transfers[]steps[]amenities[]descriptiontransfers[]steps[]amenities[]imageUrltransfers[]steps[]amenities[]pngImageUrltransfers[]steps[]amenities[]inputTypetransfers[]steps[]amenities[]includedTrue when the amenity is already part of the offer.
transfers[]steps[]amenities[]selectableTrue when the amenity can be added to this offer.
transfers[]steps[]amenities[]selectedTrue when the amenity is part of the priced selection.
transfers[]steps[]startLocationtransfers[]steps[]startLocationformattedAddresstransfers[]steps[]startLocationfullAddresstransfers[]steps[]startLocationiataCodePresent for airport locations.
transfers[]steps[]startLocationicaoCodetransfers[]steps[]startLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]startLocationlatitudetransfers[]steps[]startLocationlongitudetransfers[]steps[]startLocationtimezoneIANA timezone of the location.
transfers[]steps[]endLocationtransfers[]steps[]endLocationformattedAddresstransfers[]steps[]endLocationfullAddresstransfers[]steps[]endLocationiataCodePresent for airport locations.
transfers[]steps[]endLocationicaoCodetransfers[]steps[]endLocationplaceIdReusable place identifier; send it back to skip geocoding.
transfers[]steps[]endLocationlatitudetransfers[]steps[]endLocationlongitudetransfers[]steps[]endLocationtimezoneIANA timezone of the location.
transfers[]ticketTypestransfers[]ticketTypes[]idSend this value in
ticketTypes[].id when booking.transfers[]ticketTypes[]nametransfers[]ticketTypes[]departureDatetimetransfers[]ticketTypes[]arrivalDatetimetransfers[]alternativeTimestransfers[]alternativeTimes[]departureDatetimetransfers[]alternativeTimes[]arrivalDatetimemetadatametadatacompletedTrue when the result set is final.
metadatatimedOutTrue when results were returned before every source finished. The offers already present are valid.
metadataproviderResultsmetadataproviderResults[]gdsprovidermetadataproviderResults[]searchIdmetadataproviderResults[]completedTrue when this source has no further offers to return.
metadataproviderResults[]timedOutmetadataproviderResults[]moreComingTrue when more offers may still arrive for this
searchId.metadatastartLocationmetadatastartLocationformattedAddressmetadatastartLocationfullAddressmetadatastartLocationiataCodePresent for airport locations.
metadatastartLocationicaoCodemetadatastartLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadatastartLocationlatitudemetadatastartLocationlongitudemetadatastartLocationtimezoneIANA timezone of the location.
metadataendLocationmetadataendLocationformattedAddressmetadataendLocationfullAddressmetadataendLocationiataCodePresent for airport locations.
metadataendLocationicaoCodemetadataendLocationplaceIdReusable place identifier; send it back to skip geocoding.
metadataendLocationlatitudemetadataendLocationlongitudemetadataendLocationtimezoneIANA timezone of the location.
metadatapickupDatetimeResolved pickup moment in the origin timezone.
metadatanumPassengerserrorPresent on an
error event.errorCodePresent on an
error event.Ejemplos de respuesta
json
{
"transfers": [
{
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"gdsprovider": 0,
"resultId": "763475651c06f5ac31ea587084dc0629",
"bookingToken": "opaque_offer_token_generated_by_travelandz",
"expiresAt": "2026-08-05T21:20:00.000Z",
"totalAmount": 49.84,
"currency": "USD",
"bookable": true,
"flightInfoRequired": true,
"extraPaxRequired": false,
"goodToKnowInfo": [],
"cancellationPolicies": [
{
"notice": 48,
"refundPercent": 100,
"refundableUntilDatetime": "2026-08-14T14:40:00-04:00",
"refundAmount": 49.84,
"currency": "USD"
}
],
"supports": {},
"steps": [
{
"stepType": "car",
"main": true,
"departureDatetime": "2026-08-16T14:40:00-04:00",
"durationMinutes": 26,
"distanceMeters": 25749,
"provider": {
"name": "GO Airlink NYC",
"rating": 5
},
"vehicle": {
"type": "Shared Ride Van",
"category": "Shared",
"maxBags": 4,
"maxPassengers": 11,
"numVehicles": 1
},
"waitTime": {
"included": false,
"minutesIncluded": 0,
"extraWaitTimeChargeable": false
},
"amenities": []
}
],
"ticketTypes": [],
"alternativeTimes": [
{
"departureDatetime": "2026-08-16T14:40:00-04:00",
"arrivalDatetime": "2026-08-16T15:06:10-04:00"
},
{
"departureDatetime": "2026-08-16T13:40:00-04:00",
"arrivalDatetime": "2026-08-16T14:06:10-04:00"
}
]
}
],
"metadata": {
"completed": true,
"timedOut": false,
"providerResults": [
{
"gdsprovider": 0,
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"completed": true,
"timedOut": false,
"moreComing": false
}
],
"startLocation": {
"formattedAddress": "433 Park Ave, New York, NY 10022, USA",
"fullAddress": "433 Park Ave, New York",
"placeId": "EiU0MzMgUGFyayBBdmUsIE5ldyBZb3JrLCBOWSAxMDAyMiwgVVNB",
"latitude": 40.7607634,
"longitude": -73.971212,
"timezone": "America/New_York"
},
"endLocation": {
"formattedAddress": "John F Kennedy International Airport",
"fullAddress": "John F Kennedy International Airport",
"iataCode": "JFK",
"icaoCode": "KJFK",
"latitude": 40.639751,
"longitude": -73.778926,
"timezone": "America/New_York"
},
"pickupDatetime": "2026-08-16T15:30:00-04:00",
"numPassengers": 2
}
}Eventos del stream
| Evento | Descripción |
|---|---|
provider_search_created | La búsqueda fue aceptada. Incluye las primeras ofertas, si ya hay alguna disponible. |
provider_poll_result | Un conjunto actualizado de ofertas. Reemplaza lo que estabas mostrando con el payload del último evento. |
provider_done | Una fuente terminó de aportar ofertas. |
error | El stream no pudo continuar. Incluye error y errorCode. |
done | Resultado final combinado. Cierra la conexión al recibirlo. |
Ejemplo de stream
text
event: provider_search_created
data: {"transfers":[],"metadata":{"completed":false,"timedOut":false,"providerResults":[{"gdsprovider":0,"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","moreComing":true}]}}
event: provider_poll_result
data: {"transfers":[{"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","resultId":"763475651c06f5ac31ea587084dc0629","totalAmount":49.84,"currency":"USD"}],"metadata":{"completed":false,"timedOut":false,"providerResults":[{"gdsprovider":0,"moreComing":true}]}}
event: provider_done
data: {"transfers":[{"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","resultId":"763475651c06f5ac31ea587084dc0629","totalAmount":49.84,"currency":"USD"}],"metadata":{"completed":true,"timedOut":false,"providerResults":[{"gdsprovider":0,"completed":true,"moreComing":false}]}}
event: done
data: {"transfers":[{"searchId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","resultId":"763475651c06f5ac31ea587084dc0629","totalAmount":49.84,"currency":"USD"}],"metadata":{"completed":true,"timedOut":false,"providerResults":[{"gdsprovider":0,"completed":true,"moreComing":false}]}}Errores
| HTTP | Código | Significado | Acción recomendada |
|---|---|---|---|
400 | El body, la query o el path son inválidos, o incluyen una propiedad desconocida. | Corrige la petición usando el array message. | |
400 | transfer_invalid_currency | La moneda está fuera de la lista soportada. | Usa una moneda soportada. |
400 | transfer_invalid_language | El idioma solicitado no está soportado. | Usa uno de los valores de idioma documentados. |
429 | transfer_provider_error | El servicio está temporalmente limitado por rate limit. | Reintenta con backoff exponencial. |
502 | transfer_provider_error | La petición no pudo completarse. | No asumas que tuvo éxito. Conserva tus identificadores y consulta la reserva cuando la operación pudiera haberse creado. |
400 | transfer_location_not_found | No se pudo resolver el origen o el destino. | Añade city o zipcode, o envía un place ID o un par de coordenadas. |
503 | El precio no pudo confirmarse en este momento. | Reintenta más tarde. No reserves ni cobres al viajero. |
Notas de uso
Si todas las fuentes fallan antes de abrir el stream, la petición falla con un error HTTP JSON normal. Si el stream ya empezó, el fallo llega como evento error. Cierra explícitamente las conexiones de stream cuando ya no las necesites.
Persiste searchId, resultId y bookingToken de la oferta que elija el viajero: pricing, booking y las consultas de reserva los necesitan.
Ejemplo cURL
bash
curl --request POST \
--url "https://api.sandbox.travelandz.com/v1/transfers/search" \
-H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
-H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
-H "Content-Type: application/json" \
--data '{
"mode": "one_way",
"startAddress": "433 Park Ave",
"startCity": "New York",
"startZipcode": "10022",
"endAddress": "JFK",
"pickupDatetime": "2026-08-16 15:30",
"numPassengers": 2,
"currency": "USD",
"responseMode": "complete"
}'