POST/v1/transfers/search
API 控制台
试一试
向沙箱 API 发送真实请求并查看响应。
凭证
登录后即可从已保存的 API 密钥中选择，无需手动粘贴。
请求体
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"}'请填写凭证以发送请求。
响应
点击「试一试！」发送请求，响应将显示在此处。
搜索接送报价，并获取完整 JSON 响应或渐进式流事件。
认证和请求头
| 请求头 | 说明 |
|---|---|
Authorization | Bearer <secret_key>。密钥只能保存在服务器端，不能写入客户端日志。 |
X-Travelandz-Id | <public_key>:<profile_code>，持久化的 profile code 格式为 dp_<12 位字母数字>。 |
LANG | 推荐的语言请求头，也支持 Accept-Language。 |
Content-Type | 带 JSON body 的请求使用 application/json。 |
请求
发送 mode 和 numPassengers。起点和终点分别需要地址、place ID 或经纬度对。将 responseMode 设为 stream 可在报价到达时逐步接收，而不是只返回一个最终响应。round_trip 搜索还需要 returnPickupDatetime 或 returnFlightDatetime。
请求体结构
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.请求示例
完整响应
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"
}流式响应
json
{
"mode": "one_way",
"startAddress": "433 Park Ave, New York",
"endAddress": "JFK",
"pickupDatetime": "2026-08-16 15:30",
"numPassengers": 2,
"currency": "USD",
"responseMode": "stream"
}成功响应
返回 transfers[]（可用于定价和预订的报价），以及包含已解析地点和结果集是否最终的 metadata。每个报价都带有不透明的 bookingToken，用于复制到 pricing。
搜索可能返回 200 且 metadata.timedOut 为 true。这不是错误：已返回的报价有效且可预订。
响应体结构
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.
metadatanumPassengers响应体结构 (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.响应示例
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
}
}流事件
| 事件 | 说明 |
|---|---|
provider_search_created | 搜索已被接受。若已有报价，会随事件一并返回。 |
provider_poll_result | 更新后的报价集合。请用最新事件的负载替换当前展示的内容。 |
provider_done | 某个来源已结束提供报价。 |
error | 流无法继续。包含 error 和 errorCode。 |
done | 最终合并结果。收到后请关闭连接。 |
流示例
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}]}}错误
| HTTP | 代码 | 含义 | 建议操作 |
|---|---|---|---|
400 | 请求体、查询参数或路径无效，或包含未知属性。 | 根据 message 数组修正请求。 | |
400 | transfer_invalid_currency | 该货币不在支持列表中。 | 使用受支持的货币。 |
400 | transfer_invalid_language | 请求的语言不受支持。 | 使用文档中列出的语言值之一。 |
429 | transfer_provider_error | 服务暂时被限流。 | 使用指数退避重试。 |
502 | transfer_provider_error | 请求无法完成。 | 不要假定成功。保留标识符，并在该操作可能已创建时查询预订。 |
400 | transfer_location_not_found | 无法解析起点或终点。 | 补充城市或邮编，或改用 place ID 或经纬度对。 |
503 | 当前无法确认价格。 | 稍后重试。不要预订，也不要向旅客收费。 |
使用说明
如果在流打开前所有来源都失败，请求会以普通 JSON HTTP 错误失败；如果流已开始，则以 error 事件返回失败。不再需要流连接时请显式关闭。
请持久化旅客所选报价的 searchId、resultId 和 bookingToken：pricing、预订和预订查询都需要它们。
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"
}'