Providers

The Mobility API aggregates offers from multiple mobility providers behind a unified interface. While request and response formats are consistent across all providers, the underlying modality types have fundamentally different characteristics — pricing models, vehicle access patterns, and booking flows. Understanding these differences helps you build integrations that handle each modality correctly.

Modality Types

The API organizes providers into four modality categories. Each category has its own set of endpoints and response structures, but follows the same core patterns (search, offer, prebook, book).

Station-Based vs. Free-Floating

Providers fall into two access patterns that affect how users pick up and return vehicles:

Station-based providers have fixed locations. Vehicles must be picked up and returned at designated stations. When you search by coordinates, the API returns offers grouped by nearby stations. Car rental (airport/city stations) and most car sharing providers follow this model.

Free-floating providers allow vehicles to be picked up and dropped off anywhere within a service area. When you search by coordinates, results show individual vehicles near that location. Most micromobility providers (e-scooters, bikes) operate this way.

The API handles both patterns transparently — you always search by coordinates and receive a list of offers. The station field in the response indicates whether the offer is tied to a fixed location or a free-floating vehicle.

Pricing Models

The most important distinction between provider types is how pricing works. This directly impacts how you display offers and compare them across providers.

Car Rental — Daily/Weekly Rates

Car rental providers charge fixed daily or weekly rates. The price you see is the price you pay, regardless of distance driven.

• Fuel policy: FULL_TO_FULL — the customer refuels before returning
• Mileage: Typically unlimited, no per-kilometer charges
• Price breakdown: Base rate + taxes + fees, itemized in the response
• Currency: Prices in cents (smallest currency unit) with currency code

Car Sharing — Time + Distance

Car sharing providers charge based on rental duration and distance driven. Fuel is included in the price.

• Fuel policy: FUEL_INCLUDED — fuel/charging costs are built into the rate
• Mileage: Charged per kilometer, included in the total price calculation
• Price breakdown: Time component + distance component, requires estimatedKilometers for accurate pricing
• Currency: Same normalized format as car rental

The estimatedKilometers Parameter

Because car sharing prices depend on distance, the API needs to know your expected trip distance to calculate comparable prices. This is where estimatedKilometers comes in:

POST /mobility-api/v2/cars
{
  "pickup": { ... },
  "dates": { ... },
  "estimatedKilometers": 150
}

Without estimatedKilometers: Car sharing offers may return pricing: null in search results because the per-kilometer component cannot be calculated. Car rental offers are unaffected (they don't charge per km).

With estimatedKilometers: All providers return full price breakdowns in the same normalized format, making direct cross-provider comparison possible.

The parameter is also required for the offer detail, prebook, and booking endpoints on car sharing providers to ensure pricing accuracy throughout the booking flow.

Micromobility Pricing

Micromobility providers (bikes, scooters) typically use per-minute pricing with optional unlock fees. Pricing plans are sourced from standardized GBFS feeds and displayed in the offer response. Since micromobility is currently search-only, no booking-related pricing applies.

Public Transport Pricing

Public transport providers return journey-based pricing (single tickets, day passes). Pricing structures vary by region and transport authority. Subscription-based pricing (e.g., Deutschlandticket) is available through select providers.

Cross-Usage Networks

Some car sharing providers operate cross-usage networks ("Quernutzungsnetzwerk"), where a registration with one regional provider grants access to vehicles from partner providers across the network.

The most prominent example is the Stadtmobil network, which spans 25+ regional providers across Germany. A user registered with Stadtmobil Stuttgart can book vehicles from Stadtmobil Karlsruhe, Stadtmobil Berlin, or any other network member.

The API handles this transparently. When you search by location, you receive offers from all available network providers in the area — you never need to know which regional entity operates a specific vehicle. The provider field in the response identifies the regional provider for display purposes, but the booking flow is identical regardless of which network member owns the vehicle.

Provider Configuration

Each tenant in your organization can have its own provider configuration. This is managed in the Dashboard Portal under your tenant's provider settings.

What Gets Configured

• Credentials — Provider-specific access credentials (API keys, access cards, contract IDs). These determine which providers your tenant can access and book through.
• Settings — Non-credential configuration like preferred regions, default brands, or feature toggles.
• Enabled/Disabled — Toggle individual providers on or off per tenant.

System vs. Custom Providers

System providers (micromobility via GBFS, most public transport) are available to all tenants automatically. They use shared infrastructure and don't require per-tenant credentials.

Custom providers (car rental, car sharing) require your organization to have a contract or account with the provider. You configure the credentials in your tenant settings, and the API uses them to authenticate requests on your behalf.

This two-tier model means your tenants get immediate access to a broad set of mobility data (vehicle locations, transit routes) while car rental and car sharing bookings require explicit provider relationships.

General Provider Behavior

Response Times

Response times vary across providers, typically ranging from 1 to 15 seconds. The API queries all relevant providers in parallel with a hard timeout of 20 seconds. Always show a loading indicator while waiting for search results.

If a provider is temporarily unavailable or times out, the API still returns results from the remaining providers. Check the response for provider-level warnings indicating incomplete results.

Offer Validity

Offer tokens are typically valid for 15 minutes, but the exact expiration varies by provider and modality. Car sharing offers tend to have shorter validity windows because they reflect real-time vehicle availability.

Prebooking Behavior

Prebooking behavior differs between provider types:

• Car rental: Prebooking creates a local reservation reference. Availability is not guaranteed until the final booking call succeeds — another customer could reserve the same vehicle class in between.
• Car sharing: Some providers support actual server-side reservations during prebook, while others treat it as advisory. Always check the prebook response status to understand what guarantee you have.

Required Information

Some bookings require additional information that isn't known at search time. The requiredInformation field in the prebook response tells you what's needed — for example, a flight number for airport car rental locations. Collect this from the user and include it in the booking request.

Unlock Credentials

Car sharing booking confirmations may include vehicle unlock credentials (e.g., a PIN code or app instructions). If the confirmation response contains unlock information, make sure to surface it to the end user.