Ground Transport

Ground transport endpoints live under /v1/travel/ground-transport. Covering airport transfers, private cars, shuttles, and ride-hailing in 500+ cities.

Authentication requires Authorization: Bearer <token>.

Search

Search Available Rides

POST /v1/travel/ground-transport

Search for available vehicles and pricing for a route. Returns a search_id for polling.

{
  "start_address": "Heathrow Airport, London",
  "end_address": "1 Buckingham Palace Rd, London SW1W 0QT",
  "pickup_datetime": "2025-06-01T10:00:00Z",
  "num_passengers": 2,
  "currency": "USD"
}

Response: 202 Accepted with search_id. Results arrive async — poll until complete.

Poll Search Results

GET /v1/travel/ground-transport/{search_id}/poll

Poll for search results. Repeat until status is complete or failed.

Path param	Description
search_id	ID returned by the search endpoint

Response fields:

• status — pending | complete | failed
• results — array of available vehicles with pricing when complete

---

Bookings

Create Booking

POST /v1/travel/ground-transport/bookings

Book a vehicle from the search results. Use the result_id from the poll response.

{
  "search_id": "srch_abc123",
  "result_id": "res_xyz456",
  "passenger": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "+447700900000"
  },
  "flight_number": "BA123"
}

Response: 202 Accepted with search_id for booking confirmation polling.

Poll Booking Confirmation

GET /v1/travel/ground-transport/bookings/{search_id}/poll

Poll for booking confirmation. Repeat until status is confirmed or failed.

Path param	Description
search_id	ID returned by the book endpoint

Booking History

GET /v1/travel/ground-transport/bookings/history

Returns the authenticated user's past ground transport bookings.

Cancel Booking

POST /v1/travel/ground-transport/bookings/cancel

{
  "booking_id": "book_def789"
}

---

Search Pattern

Ground transport uses an async two-step pattern for both search and booking:

POST /search → search_id
  ↓
GET /search/{search_id}/poll (repeat until complete)
  ↓ pick a result_id
POST /bookings → search_id
  ↓
GET /bookings/{search_id}/poll (repeat until confirmed)

Recommended poll interval: 2 seconds. Search typically completes in 5–15 seconds.