Booking Workflow

Before searching for mobility offers, help users discover the best locations (stations, stops, terminals, etc.) for their journey.

Purpose: Find nearby stations, terminals, or pickup/dropoff points before performing a full search.

Available for:

• Car rentals:
  GET/mobility-api/v2/cars/stations
• Other modalities: Coming soon

When to Use Station Search

• User selects location on map - Show available stations as pins
• User enters city/address - Let them choose from nearby stations
• Displaying station details - Show operating hours, address, services before searching
• Comparing locations - Help users decide between airport vs. downtown pickup

When NOT to Use Station Search

• You already have a place ID - Skip directly to offer search with the place ID
• Autocomplete/typeahead - Station search is not optimized for keystroke-by-keystroke calls
• Generic coordinate search is fine - If users don't need to pick a specific station, search directly with coordinates

What you provide:

• Geographic search area (coordinates with radius, address, or map bounding box)
• Optional travel dates (to get availability estimates)

What you get:

• List of stations with names, addresses, and coordinates
• Place IDs for optimized offer searches
• Operating hours and available services
• Availability estimates (when dates provided)

Rate Limiting: Call once per user location input, not on every keystroke.

See OpenAPI Reference for endpoint details and schemas.

Search for available mobility options based on location and travel details.

Purpose: Find available offers from multiple providers that match the user's travel needs.

What you provide:

• Location: Use location identifier from Phase 0, or provide coordinates/address directly
• Travel details: Departure and arrival times, route information
• Optional filters (vehicle type, price range, features, etc.)
• Pagination preferences

Location options:

• Location identifiers (recommended) - Use place IDs from location discovery for best performance
• Geographic coordinates - Latitude/longitude with search radius
• Address search - Human-readable address that will be geocoded

What you get:

• Aggregated list of offers from all responding providers
• Basic offer information (pricing, vehicle/service details, provider)
• Offer tokens for each result (time-limited, required for booking)
• Pagination information for loading more results

See OpenAPI Reference for complete endpoint schemas and examples.

Estimated Kilometers

Provide the estimated trip distance in kilometers to enable pricing calculation:

{
  "estimatedKilometers": 500
}

This parameter is required because the API aggregates offers with different pricing models (e.g., car rental with daily rates vs. car sharing with per-kilometer rates). A common distance estimate ensures all offers are priced consistently and can be compared directly.

The value provided in search is encoded in the offerToken. You can override it in offer details or prebook requests to refresh pricing if the user updates their trip plan.

Display search results to users with key information:

• Service/vehicle details (type, category, specifications)
• Pricing (base price, taxes, total cost)
• Provider information
• Departure/arrival locations and times
• Duration and route information

Users can sort, filter, and compare options before choosing.

Fetch comprehensive details about a specific offer before booking.

Purpose: Provide users with complete information to make informed decisions.

What you get:

• Full service/vehicle specifications and features
• Complete pricing breakdown with all fees
• Terms and conditions
• Cancellation and change policies
• Pickup requirements (minimum age, credit card, etc.)
• Available upsells summary (without pricing - full pricing only in prebook response)
• Refreshed offerToken with updated pricing

When to use: When users click "View Details" or want more information before proceeding.

Response: Detailed offer with refreshed token (always use the latest token).

Reserve the offer and lock pricing for a limited time.

Purpose: Create a temporary hold on the offer while collecting traveler information.

What you provide: The offerToken from search results or offer details, plus estimatedKilometers (if not already in token)

What you get:

• Refreshed offerToken - Use this token in the booking endpoint (replaces the search token)
• Confirmation of reservation (if provider supports holding offers)
• Updated offer with current pricing
• reservedUntil - Reservation expiration time (typically 10-15 minutes)
• requiredInformation - List of required driver fields for booking (e.g., DRIVER_EMAIL). Note: DRIVER_PHONE and DRIVER_NAME are optional but recommended for provider communication.
• availableUpsells - Full upsell details with pricing (not available in offer details)

Collect required information from the user based on the prebook response.

Common fields:

• Traveler name, email, phone number
• Age or date of birth
• Additional verification details (license, passport, etc.)
• Special requests or preferences
• Payment information (if required)

Validation: The prebook response indicates which fields are required. Validate all inputs before proceeding to booking.

Finalize the booking with the provider using collected information.

What you provide: The offerToken (from prebook response or directly from search/details) plus driver information

Possible Outcomes:

1. CONFIRMED - Booking immediately confirmed and ready to use
2. PENDING - Booking is being processed by the provider (poll for status or wait for notification)
3. REQUIRES_CONFIRMATION - Additional action needed (e.g., redirect to provider for payment)
4. FAILED - Booking could not be completed (show error and allow retry)