Transfer search endpoints allow you to find available transfer vehicles between two points at a given time. The search returns a list of vehicle offers with pricing, rules, and cancellation policies; each offer is identified by the searchId + code pair used in the subsequent order step.
Search for available transfer vehicles for the specified route, time, and passenger count.
POST /transfer/searchThis endpoint requires authentication. Include your JWT access token in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKENTake pickup and dropoff coordinates from the Locations endpoints (place search + place detail) rather than your own geocoding. Transfer suppliers map the given coordinates onto their own service regions; raw coordinates that fall slightly outside a supplier's region are silently dropped from the results. The same search therefore returns noticeably more vehicles when the coordinates come from a /locations point of interest (airport, hotel, district) than from a nearby raw coordinate.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Trip type: oneway or round |
pickup | object | Yes | Pickup point |
pickup.lat | number | Yes | Latitude coordinate (-90 to 90) |
pickup.lon | number | Yes | Longitude coordinate (-180 to 180) |
pickup.name | string | No | Human-readable name of the pickup point |
dropoff | object | Yes | Dropoff point (same structure as pickup) |
pickupTime | datetime | Yes | Pickup date and time (RFC 3339 format with timezone). Must be in the future |
returnPickupTime | datetime | Conditional | Return leg pickup time. Required when type is round; must be after pickupTime |
passengerCount | integer | Yes | Number of passengers (minimum 1) |
commission | object | No | Agency commission to add on top of the net price |
commission.type | string | Yes* | Commission type: percentage or fixed |
commission.percentage | number | Conditional | Commission percentage (0-100). Required when type is percentage |
commission.fixed | object | Conditional | Fixed commission as {amount, currency}. Required when type is fixed |
The dates in the examples are illustrative; use a pickup time in the future when you send your own request.
curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"type": "oneway",
"pickup": {"lat": 41.276146, "lon": 28.728735, "name": "Istanbul Airport (IST)"},
"dropoff": {"lat": 41.037003, "lon": 28.985092, "name": "Taksim Square"},
"pickupTime": "2027-06-15T10:00:00+03:00",
"passengerCount": 2,
"commission": {"type": "percentage", "percentage": 10}
}'Success Response (200 OK):
{
"searchId": "0ba0fea9-1e98-43ce-a69b-e895e2bc68a6",
"products": [
{
"code": "9972a93a-707e-403e-928e-cbb68a65584f",
"appointment": {
"pickup": {
"lat": 41.276146,
"lon": 28.728735,
"name": "Istanbul Airport (IST)"
},
"dropoff": {
"lat": 41.037003,
"lon": 28.985092,
"name": "Taksim Square"
},
"pickupTime": "2027-06-15T10:00:00+03:00",
"passengerCount": 2
},
"onewayDistance": 41662,
"onewayDuration": 2727,
"vehicle": {
"name": "Minivan",
"seatCount": 6,
"baggageCount": 6,
"image": "https://cdn.example.com/assets/images/van.png"
},
"pricing": {
"currency": "TRY",
"fees": [
{
"amount": 132000,
"currency": "TRY",
"type": "oneway",
"charge": "advance",
"description": "Outbound Trip Amount"
},
{
"amount": 13200,
"currency": "TRY",
"type": "commission",
"charge": "advance",
"description": "commission"
}
],
"vendorTotal": {
"amount": 0,
"currency": "TRY"
},
"paymentTotal": {
"amount": 145200,
"currency": "TRY"
},
"discountTotal": {
"amount": 0,
"currency": "TRY"
},
"total": {
"amount": 145200,
"currency": "TRY"
}
},
"rules": [
{
"type": "freeCancellation",
"description": "Free Cancellation"
},
{
"type": "waitForFree",
"description": "First 15 minutes of waiting free"
},
{
"type": "safeTripWithInvoice",
"description": "Safe trip with invoice"
}
],
"cancellationPolicies": [
{
"type": "freeCancel",
"until": "2027-06-15T09:00:00+03:00",
"description": "You can cancel your transfer free of charge up to 1 hour before departure."
}
]
}
]
}| Field | Type | Description |
|---|---|---|
searchId | string | Search session identifier, used when creating the order |
products | array | Available vehicle offers |
| Field | Type | Description |
|---|---|---|
code | string | Offer code, used together with searchId when creating the order |
appointment | object | The trip as understood by the supplier (points, times, passenger count) |
onewayDistance | integer | Outbound trip distance in meters |
onewayDuration | integer | Outbound trip duration in seconds |
returnDistance | integer | Return trip distance in meters (round trips only) |
returnDuration | integer | Return trip duration in seconds (round trips only) |
vehicle | object | Vehicle name, seat count, baggage count, and image |
pricing | object | Price breakdown (see below) |
rules | array | Service rules as {type, description} items |
cancellationPolicies | array | Cancellation policy windows as {type, until, description} items |
All amounts are in minor units (kuruş for TRY).
| Field | Type | Description |
|---|---|---|
currency | string | Currency of the breakdown |
fees | array | Price line items: oneway and return trip amounts, plus a commission line when an agency commission was requested |
vendorTotal | object | Amount payable to the supplier at the vehicle (currently always paid in advance) |
paymentTotal | object | Amount that will be charged at the payment step |
discountTotal | object | Total discount applied |
total | object | Grand total including commission |
Set type to round and provide returnPickupTime. The response contains the additional returnDistance and returnDuration fields and a return fee line:
curl -X POST https://api.pro.yolcu360.com/api/v1/transfer/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"type": "round",
"pickup": {"lat": 41.276146, "lon": 28.728735, "name": "Istanbul Airport (IST)"},
"dropoff": {"lat": 41.037003, "lon": 28.985092, "name": "Taksim Square"},
"pickupTime": "2027-06-15T10:00:00+03:00",
"returnPickupTime": "2027-06-20T14:00:00+03:00",
"passengerCount": 2
}'{
"searchId": "9635f52b-e0f9-4b5e-8b23-0986be44b88b",
"products": [
{
"code": "e96d7154-e0c8-45c6-81c6-54db5506bfaf",
"appointment": {
"pickup": {
"lat": 41.276146,
"lon": 28.728735,
"name": "Istanbul Airport (IST)"
},
"dropoff": {
"lat": 41.037003,
"lon": 28.985092,
"name": "Taksim Square"
},
"pickupTime": "2027-06-15T10:00:00+03:00",
"returnPickupTime": "2027-06-20T14:00:00+03:00",
"passengerCount": 2
},
"onewayDistance": 41662,
"returnDistance": 41662,
"onewayDuration": 2727,
"returnDuration": 2727,
"pricing": {
"currency": "TRY",
"fees": [
{
"amount": 132000,
"currency": "TRY",
"type": "oneway",
"charge": "advance",
"description": "Outbound Trip Amount"
},
{
"amount": 132000,
"currency": "TRY",
"type": "return",
"charge": "advance",
"description": "Return Trip Amount"
}
]
}
}
]
}The example above is trimmed to the round-trip-specific fields; the full product structure is identical to the one-way response.
Retrieve a single offer from an earlier search by its searchId and code. Useful for re-rendering an offer the user selected without keeping the whole search response in your session.
GET /transfer/search/{searchId}/{code}This endpoint requires authentication. Include your JWT access token in the Authorization header.
| Parameter | Type | Required | Description |
|---|---|---|---|
searchId | string | Yes | Search identifier from the search |
code | string | Yes | Offer code from the search |
curl -X GET https://api.pro.yolcu360.com/api/v1/transfer/search/0ba0fea9-1e98-43ce-a69b-e895e2bc68a6/9972a93a-707e-403e-928e-cbb68a65584f \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Success Response (200 OK):
Returns a single product object with exactly the same structure as an item of the search response's products array.
Search offers are valid for roughly 30 minutes. Requesting an expired or unknown offer returns:
{
"code": 8003,
"description": "Transfer product not found or expired",
"details": "The search result was not found or has expired, please search again."
}Run a new search and present fresh offers in that case.