{"openapi":"3.1.0","info":{"version":"2.0.0-beta.1","title":"Adapt2Move Mobility API v2","description":"# Getting Started\n\nREST API for integrating with Adapt2Move's mobility aggregation platform.\n\n## Features\n- Search vehicles from multiple providers\n- Real-time pricing and availability\n- Complete booking lifecycle management\n- Comprehensive filtering and sorting\n\n## Authentication\nAll API endpoints require authentication using Bearer tokens.\n\n### API Key Types\n\n| Type | Format | Use Case |\n|------|--------|----------|\n| **Secret Key** | `a2m_live_...` | Server-side integrations (full access) |\n| **Publishable Key** | `a2m_pk_live_...` | Client-side / browser (read-only, domain-restricted) |\n\nInclude your API key in the `Authorization` header:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n**Secret Keys** support all permissions and must only be used in server-side code.\n\n**Publishable Keys** are restricted to read-only endpoints and validate the request `Origin` header against configured allowed domains. They include CORS headers in the response, making them ideal for browser-based map integrations (e.g., Multimodal Tiles endpoint).\n\n### Obtaining API Keys\nCreate API keys in the **Workspace Dashboard**, or contact development@adapt2move.de.\n\n## Payment & Billing\nAll payment and billing is handled at the tenant level. Your API key is associated with your tenant's configured payment method and billing information.\n\n**No per-booking payment details required:** When creating bookings, you do not need to provide credit card information, billing addresses, or other payment details. All charges are automatically billed to your tenant according to your payment agreement with Adapt2Move.\n\nFor billing inquiries or to update your tenant's payment information, please contact info@adapt2move.de.\n\n## Rate Limits\n- **Default:** 3600 requests per hour per API token\n\n**Production Apps:** Rate limits can be increased for production applications that have been certified by the Adapt2Move Development Team. To request certification and higher rate limits, please contact development@adapt2move.de with details about your application and expected usage patterns.\n\n## Pagination\n\nThe API uses two pagination strategies depending on the endpoint:\n\n### Cursor-based Pagination\nUsed for search endpoints that aggregate results from multiple providers in real-time: cars, stations, micromobility, and public-transport stops.\n\nEach cursor is an encrypted token representing a server-side **pagination session** (30-minute TTL, renewed on each page request). The session tracks per-provider cursor state so only non-exhausted providers are queried on subsequent pages.\n\n**Request:** Include `cursor` parameter from previous response\n```\nPOST /cars\n{ \"pickup\": {...}, \"dates\": {...}, \"cursor\": \"token_abc...\" }\n```\n\n**Response:**\n```json\n{\n  \"pagination\": {\n    \"nextCursor\": \"token_abc...\",\n    \"hasMore\": true\n  }\n}\n```\n\n- `nextCursor`: Encrypted opaque token (present when `hasMore` is true). Never parse or construct manually.\n- `hasMore`: `true` when at least one provider still has more results\n- If search parameters change between pages, a fresh search is started silently (no error)\n\n**Benefits:** Efficient for \"load more\" UX patterns, prevents duplicate/missing items, automatically reduces provider queries as pages progress.\n\n### Offset-based Pagination\nUsed for finite, countable result sets (e.g., booking history, provider lists).\n\n**Request:** Include `page` and `limit` parameters\n```\nGET /bookings?page=2&limit=20\n```\n\n**Response:**\n```json\n{\n  \"pagination\": {\n    \"total\": 45,\n    \"currentPage\": 2,\n    \"limit\": 20\n  }\n}\n```\n\n**Benefits:** Allows jumping to specific pages, provides exact position in result set.\n\n## Response Format\nAll responses follow a consistent envelope format:\n\n**Success Response:**\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": {\n    \"requestId\": \"req_...\",\n    \"timestamp\": \"2025-10-27T14:00:00Z\"\n  }\n}\n```\n\n**Error Response:**\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_REQUEST\",\n    \"message\": \"Human-readable error message\",\n  },\n  \"meta\": {\n    \"requestId\": \"req_...\",\n    \"timestamp\": \"2025-10-27T14:00:00Z\"\n  }\n}\n```\n\n## Language Support\nThe API supports multiple languages for localized content (e.g., location names, descriptions, error messages).\n\n**Setting Language Preferences:**\n\nUse the `Accept-Language` header in your requests:\n\n```\nAccept-Language: de-DE, en-US\n```\n\nYou can specify multiple languages in order of preference. The API will return content in the best matching available language.\n\n**Default Language:** If no `Accept-Language` header is provided, the API uses your tenant's default language setting.\n\n**Organization language defaults can be changed by:**\n\n- Contacting Adapt2Move API support at development@adapt2move.de\n- Using the Management API (requires appropriate permissions)\n\n## Support\nFor API support, contact development@adapt2move.de","contact":{"name":"Adapt2Move API Support","email":"development@adapt2move.de","url":"https://adapt2move.de/support"},"license":{"name":"Proprietary"}},"security":[{"API-Token Auth":["bearerAuth"]}],"servers":[{"description":"Production","url":"https://adapt2move.de/mobility-api/v2"},{"description":"Testing","url":"https://dev.adapt2move.de/mobility-api/v2"}],"tags":[{"name":"Cars (Rental & Sharing)","description":"Search for offers, prebook/create reservations and create & manage bookings related to rental cars and car sharing."},{"name":"Public Transport","description":"Search for public transport journeys, view real-time information, and book tickets. Supports multiple transit agencies and aggregators with real-time departure/arrival information, accessibility details, and fare calculations."},{"name":"Micro Mobility (Scooters & Bikes)","description":"**Beta**: These endpoints are under active development. Breaking changes may occur.\n\nSearch for available e-scooters, bikes, mopeds and other micro mobility vehicles. Get real-time availability, pricing, and geofencing zones from multiple providers."},{"name":"Mobility Providers","description":"Discover and get information about mobility service providers (MSPs) that are available and enabled for your tenant. This includes provider capabilities, contact information, supported countries and languages, and branding details."},{"name":"Multimodal","description":"**Beta**: Aggregated endpoints that combine multiple mobility types in a single request.\n\nIdeal for map-based applications that need to display PT departures, micromobility vehicles, and carsharing stations together. Supports partial success handling - if one data source fails, others still return data.\n\n**Client-Side Usage:** These endpoints support **Publishable Keys** (`a2m_pk_...`) for direct browser access. Configure allowed domains when creating your publishable key, and the API will include proper CORS headers automatically."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Tenant-specific API key. Two key types are available:\n\n**Secret Key** (`a2m_live_...`) — For server-side use only. Supports all permissions.\n\n**Publishable Key** (`a2m_pk_live_...`) — For client-side use (browser). Read-only permissions, domain-restricted. Ideal for map integrations using the Multimodal Tiles endpoint.\n\nContact development@adapt2move.de to obtain your API credentials, or create keys in the Workspace Dashboard."}},"schemas":{"ErrorCode":{"type":"string","enum":["INVALID_REQUEST","INVALID_LOCATION","INVALID_DATE_RANGE","INVALID_CURSOR","MISSING_REQUIRED_FIELD","GEOCODING_FAILED","AUTHENTICATION_REQUIRED","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","RATE_LIMIT_EXCEEDED","INTERNAL_ERROR","SERVICE_UNAVAILABLE","PROVIDER_ERROR","TIMEOUT","OPERATION_NOT_SUPPORTED","NO_OFFERS_AVAILABLE","OFFER_EXPIRED","OFFER_TOKEN_ALREADY_USED","BOOKING_FAILED","INVALID_OFFER_TOKEN","PIN_REQUIRED","SUBSCRIPTION_NOT_FOUND","SUBSCRIPTION_ALREADY_CANCELLED","SUBSCRIPTION_NOT_CANCELLABLE","SUBSCRIPTION_EXPIRED","PRODUCT_NOT_AVAILABLE","INVALID_IDENTIFICATION","TICKET_NOT_READY"],"description":"Standard error codes for the public API (Machine Readable)","example":"INVALID_REQUEST"},"Metadata":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1234567890","description":"Unique request identifier"},"timestamp":{"type":"string","format":"date-time","example":"2025-10-27T14:30:00Z","description":"Response timestamp in ISO 8601 format"}},"required":["requestId","timestamp"],"description":"Response metadata for debugging and tracking"},"Error":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"WarningSeverity":{"type":"string","enum":["INFO","WARNING","ALERT","CRITICAL"],"description":"Warning severity level","example":"WARNING"},"Warning":{"type":"object","properties":{"code":{"type":"string","example":"PRICE_INCREASED","description":"Machine-readable warning code"},"message":{"type":"string","example":"The price has increased by €10.00 since the original search","description":"Human-readable warning message"},"severity":{"$ref":"#/components/schemas/WarningSeverity"},"field":{"type":"string","example":"pricing.total","description":"Related field (if applicable)"}},"required":["code","message","severity"],"description":"Warning related to API response (non-blocking issues or important notices).\n\nWarnings communicate important information that doesn't prevent the operation from completing but may require user attention or UI adjustments.\n\n## Severity Levels\n\n- **INFO**: Informational message (e.g., \"Reservation expires in 10 minutes\")\n- **WARNING**: Important notice requiring attention (e.g., price changes, limited availability)\n- **CRITICAL**: Critical issue that may affect booking completion (e.g., offer about to expire)\n\n## Car Rental Warning Codes\n\nThe following codes are specific to car rental and car sharing bookings:\n\n| Code | Description |\n|------|-------------|\n| TIME_ROUNDED | Requested time was rounded to provider's time slots |\n| PRICE_CHANGED | Price has changed since last request |\n| PRICE_INCREASED | Price increased from previous offer |\n| PRICE_DECREASED | Price decreased from previous offer |\n| LIMITED_AVAILABILITY | Low stock remaining |\n| PICKUP_LOCATION_CHANGED | Pickup location details updated |\n| RETURN_LOCATION_CHANGED | Return location details updated |\n| FEATURE_UNAVAILABLE | Requested feature not available |\n| POLICY_CHANGED | Rental policy or terms updated |\n| VEHICLE_SUBSTITUTED | Different vehicle model provided |\n| MILEAGE_ADJUSTED | Mileage allowance adjusted |\n| INSURANCE_CHANGED | Insurance coverage level changed |\n| ADDITIONAL_FEES_MAY_APPLY | Extra fees may be charged |\n| OPERATING_HOURS_CHANGED | Operating hours restricted or changed |\n| REFILL_POLICY_CHANGED | Fuel/refill policy differs from requested |\n| AGE_RESTRICTION_APPLIES | Age restrictions or fees apply |\n| ONE_WAY_FEE_APPLIES | One-way rental fee applies |\n| OTHER | Other provider-specific warning |\n\n**Note**: Warning codes may vary by modality type. Additional codes may be introduced for other mobility types in future versions."},"PaginationParams":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"example":0,"description":"Page number (0-indexed, default: 0)"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":100,"example":20,"description":"Number of results per page (default: 20, max: 100)"}},"description":"Offset-based pagination parameters"},"PaginationMeta":{"type":"object","properties":{"total":{"type":"number","example":42,"description":"Total number of entries"},"currentPage":{"type":"number","example":0,"description":"Current page number (0-indexed)"},"limit":{"type":"number","example":20,"description":"Number of results per page"}},"required":["total","currentPage","limit"],"description":"Pagination metadata in response"},"CursorPaginationMeta":{"type":"object","properties":{"nextCursor":{"type":"string","example":"eyJ0eXAiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..example","description":"Opaque cursor for fetching the next page of results. Present when hasMore is true. Use this value in the next request's cursor parameter."},"hasMore":{"type":"boolean","example":true,"description":"Whether more results are available after the current page"}},"required":["hasMore"],"description":"Cursor-based pagination metadata for efficient browsing through large result sets"},"Price":{"type":"object","properties":{"amount":{"type":"integer","example":15000,"description":"Price in smallest currency unit. Cents for USD/EUR/GBP (÷100), yen for JPY (÷1), fils for KWD (÷1000). See ISO 4217 for currency decimal places."},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"EUR","description":"ISO 4217 currency code"},"description":{"type":"string","example":"Base rental price","description":"Human-readable description of what this price represents"}},"required":["amount","currency"],"description":"Price representation with currency-aware smallest unit handling"},"DetailedPrice":{"type":"object","properties":{"totalPrice":{"allOf":[{"$ref":"#/components/schemas/Price"},{"example":{"amount":12064,"currency":"EUR"}}]},"includedTaxes":{"type":"array","items":{"$ref":"#/components/schemas/Price"},"example":[{"amount":1064,"currency":"EUR"}],"description":"All taxes included in the total price (VAT, local taxes, etc.)"},"includedInsurances":{"type":"array","items":{"$ref":"#/components/schemas/Price"},"example":[],"description":"Insurance costs included in the total price"},"includedFees":{"type":"array","items":{"$ref":"#/components/schemas/Price"},"example":[],"description":"Additional fees included in the total price (service fees, airport fees, etc.)"},"includedExtras":{"type":"array","items":{"$ref":"#/components/schemas/Price"},"example":[],"description":"Optional extras included in the total price (GPS, child seats, etc.)"},"estimatedFuel":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Estimated fuel cost for the planned trip. Zero amount indicates fuel is included in the package or no extra cost. NOT included in totalPrice.","example":{"amount":200,"currency":"EUR","description":"E.g. 20€ for fuel representing potential price for current fuel prices and what type of fuel is used. Car sharing offers often have just 0."}}]}},"required":["totalPrice","includedTaxes","includedInsurances","includedFees","includedExtras","estimatedFuel"],"description":"Detailed price breakdown with categorized costs. Only available when estimated kilometers are provided in the search requests. Estimated fuel price is NOT included in totalPrice, but should be shown for comparasion!"},"ProviderDisplay":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Minimal provider information for display purposes"},"Coordinates":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"example":48.8566,"description":"Latitude in decimal degrees (WGS84)"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":2.3522,"description":"Longitude in decimal degrees (WGS84)"}},"required":["latitude","longitude"],"description":"Geographic coordinates"},"CoordinateSearch":{"type":"object","properties":{"type":{"type":"string","enum":["coordinates"],"description":"Location search type discriminator"},"coordinates":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Geographic coordinates for search"}]},"radiusMeters":{"type":"number","exclusiveMinimum":0,"maximum":50000,"example":5000,"description":"Search radius in meters (max: 50km)"},"walkingTimeMinutes":{"type":"number","exclusiveMinimum":0,"maximum":60,"example":15,"description":"Maximum walking time in minutes (alternative to radius)"}},"required":["type","coordinates"],"description":"Location search by coordinates with optional radius or walking time"},"AddressSearch":{"type":"object","properties":{"type":{"type":"string","enum":["address"],"description":"Location search type discriminator"},"address":{"type":"string","example":"Paris, France","description":"Human-readable address to search (will be geocoded internally)"},"radiusMeters":{"type":"number","exclusiveMinimum":0,"maximum":50000,"example":5000,"description":"Search radius in meters (max: 50km)"},"walkingTimeMinutes":{"type":"number","exclusiveMinimum":0,"maximum":60,"example":10,"description":"Maximum walking time in minutes (alternative to radius)"}},"required":["type","address"],"description":"Location search by address with optional radius or walking time"},"PlaceId":{"type":"string","pattern":"^p_[a-z0-9]+$","example":"p_8f3d9a2b","description":"Unique place identifier in format 'p_{hash}'"},"PlaceIdSearch":{"type":"object","properties":{"type":{"type":"string","enum":["place"],"description":"Location search type discriminator"},"placeId":{"allOf":[{"$ref":"#/components/schemas/PlaceId"},{"description":"Place ID from station search (exact location identifier for optimal performance)"}]}},"required":["type","placeId"],"description":"Location search by place ID from station search endpoint"},"LocationSearch":{"oneOf":[{"$ref":"#/components/schemas/CoordinateSearch"},{"$ref":"#/components/schemas/AddressSearch"},{"$ref":"#/components/schemas/PlaceIdSearch"}],"discriminator":{"propertyName":"type","mapping":{"coordinates":"#/components/schemas/CoordinateSearch","address":"#/components/schemas/AddressSearch","place":"#/components/schemas/PlaceIdSearch"}}},"BoundingBox":{"type":"object","properties":{"southwest":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Southwest corner of the bounding box"}]},"northeast":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Northeast corner of the bounding box"}]}},"required":["southwest","northeast"],"description":"Geographic bounding box defined by two corners"},"LocationDetails":{"type":"object","properties":{"id":{"type":"string","example":"loc_paris_cdg_t2","description":"Unique location identifier"},"name":{"type":"string","example":"Paris Charles de Gaulle Airport - Terminal 2","description":"Location name (e.g., 'Downtown Station', 'Airport Terminal 2')"},"address":{"type":"object","properties":{"street":{"type":"string","example":"Terminal 2","description":"Street address"},"city":{"type":"string","example":"Roissy-en-France","description":"City name"},"postalCode":{"type":"string","example":"95700","description":"Postal/ZIP code"},"country":{"type":"string","example":"France","description":"Country name"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"example":"FR","description":"ISO 3166-1 alpha-2 country code"}},"required":["city","country","countryCode"],"description":"Physical address"},"coordinates":{"$ref":"#/components/schemas/Coordinates"},"additionalInfo":{"type":"string","example":"Terminal 2, Level 1, Exit 5","description":"Additional location info (e.g., 'Terminal A, Level 3')"},"operatingHours":{"type":"string","example":"24/7","description":"Operating hours if location has restricted hours"}},"required":["id","name","address","coordinates"],"description":"Detailed location information"},"DatetimeInput":{"type":"string","format":"date-time","description":"Start date and time in ISO 8601 format. Must be in the future. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-01T10:00:00Z"},"DateRange":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Date range for rental period"},"CarCategory":{"type":"string","enum":["ECONOMY","COMPACT","MIDSIZE","FULLSIZE","LUXURY","SUV","VAN","SPORTS"],"description":"Vehicle size and category classification","example":"COMPACT"},"FuelType":{"type":"string","enum":["PETROL","DIESEL","ELECTRIC","HYBRID","PLUGIN_HYBRID","HYDROGEN","OTHER"],"description":"Vehicle fuel/energy type","example":"ELECTRIC"},"Transmission":{"type":"string","enum":["MANUAL","AUTOMATIC"],"description":"Transmission type","example":"AUTOMATIC"},"RefillPolicy":{"type":"string","enum":["FULL_TO_FULL","SAME_AS_PICKUP","FUEL_INCLUDED"],"description":"Refueling/recharging policy for the rental. FULL_TO_FULL: Pick up vehicle with full tank/charge, return with full tank/charge (most common, fairest for customers). SAME_AS_PICKUP: Return vehicle with the same fuel/charge level as at pickup (flexible, but requires tracking initial level). FUEL_INCLUDED: Fuel/charging costs included in rental price, return at any level (convenient, but may be more expensive upfront). Applies to both conventional fuel vehicles and electric vehicles.","example":"FULL_TO_FULL"},"InsuranceCoverage":{"type":"string","enum":["BASIC","STANDARD","COMPREHENSIVE","FULL_COVERAGE","PREMIUM"],"description":"Insurance coverage level (increasing protection). BASIC: liability only, high deductible. STANDARD: +theft protection, €500-€1500 deductible. COMPREHENSIVE: +collision damage waiver, €150-€500 deductible. FULL_COVERAGE: +glass/tire/undercarriage, €0-€150 deductible. PREMIUM: full benefits, no deductible. Exact terms vary by provider and region.","example":"COMPREHENSIVE"},"CarFeature":{"type":"string","enum":["AIR_CONDITIONING","GPS_NAVIGATION","BLUETOOTH","USB_CHARGING","WIFI_HOTSPOT","APPLE_CARPLAY","INFANT_SEAT","CHILD_SEAT","BOOSTER_SEAT","ISOFIX","SKI_RACK","BIKE_RACK","ROOF_LUGGAGE","WINTER_TIRES","FOUR_WHEEL_DRIVE","ACCESSIBILITY_SUPPORT"],"description":"Vehicle features and equipment","example":"GPS_NAVIGATION"},"PickupRequirementType":{"type":"string","enum":["MINIMUM_AGE","INTERNATIONAL_LICENSE","CREDIT_CARD_REQUIRED","PASSPORT_REQUIRED","ADDITIONAL_DRIVER_FEE"],"description":"Type of pickup or dropoff requirement","example":"MINIMUM_AGE"},"SortBy":{"type":"string","enum":["PRICE_LOW_TO_HIGH","PRICE_HIGH_TO_LOW","DISTANCE","RECOMMENDED"],"description":"Sorting options for search results","example":"PRICE_LOW_TO_HIGH"},"CarFilters":{"type":"object","properties":{"category":{"type":"array","items":{"$ref":"#/components/schemas/CarCategory"},"example":["COMPACT","MIDSIZE"],"description":"Filter by vehicle categories"},"minSeats":{"type":"integer","exclusiveMinimum":0,"maximum":15,"example":5,"description":"Minimum number of passenger seats"},"minDoors":{"type":"integer","exclusiveMinimum":0,"maximum":6,"example":4,"description":"Minimum number of doors"},"fuelType":{"type":"array","items":{"$ref":"#/components/schemas/FuelType"},"example":["ELECTRIC","HYBRID"],"description":"Filter by fuel/energy types"},"transmission":{"type":"array","items":{"$ref":"#/components/schemas/Transmission"},"example":["AUTOMATIC"],"description":"Filter by transmission types"},"refillPolicy":{"type":"array","items":{"$ref":"#/components/schemas/RefillPolicy"},"example":["FULL_TO_FULL"],"description":"Filter by refueling policies"},"insuranceCoverage":{"type":"array","items":{"$ref":"#/components/schemas/InsuranceCoverage"},"example":["COMPREHENSIVE","FULL_COVERAGE"],"description":"Filter by insurance coverage levels"},"unlimitedMileage":{"type":"boolean","example":true,"description":"Filter for unlimited mileage only"},"requiredFeatures":{"type":"array","items":{"$ref":"#/components/schemas/CarFeature"},"example":["AIR_CONDITIONING","GPS_NAVIGATION"],"description":"Required vehicle features (all must be present)"},"minLuggageCapacity":{"type":"integer","exclusiveMinimum":0,"example":2,"description":"Minimum luggage capacity (number of standard carry-on bags)"},"maxPricePerDay":{"type":"number","exclusiveMinimum":0,"example":10000,"description":"Maximum price per day in cents"},"maxTotalPrice":{"type":"number","exclusiveMinimum":0,"example":50000,"description":"Maximum total price in cents"}},"additionalProperties":false,"description":"Optional filters for car search"},"Vehicle":{"type":"object","properties":{"make":{"type":"string","example":"Mercedes-Benz","description":"Vehicle manufacturer (e.g., 'Toyota', 'BMW')"},"model":{"type":"string","example":"A-Class","description":"Vehicle model (e.g., 'Camry', 'X5')"},"year":{"type":"integer","example":2025,"description":"Model year"},"category":{"$ref":"#/components/schemas/CarCategory"},"seats":{"type":"integer","exclusiveMinimum":0,"example":5,"description":"Number of passenger seats"},"doors":{"type":"integer","exclusiveMinimum":0,"example":4,"description":"Number of doors"},"fuelType":{"$ref":"#/components/schemas/FuelType"},"transmission":{"$ref":"#/components/schemas/Transmission"},"luggageCapacity":{"type":"integer","exclusiveMinimum":0,"example":3,"description":"Luggage capacity (number of standard carry-on bags)"},"features":{"type":"array","items":{"$ref":"#/components/schemas/CarFeature"},"example":["AIR_CONDITIONING","GPS_NAVIGATION","BLUETOOTH"],"description":"Available vehicle features"},"imageUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.de/vehicles/mercedes-a-class.jpg","description":"URL to vehicle image"},"isConfirmed":{"type":"boolean","example":false,"description":"Whether this exact vehicle is guaranteed (true) or just an example of the category (false)"},"co2Emissions":{"type":"number","example":142,"description":"Estimated CO2 emissions in g/100km"}},"required":["make","model","category","seats","doors","fuelType","transmission","features"],"description":"Vehicle specifications"},"MileageAllowance":{"type":"object","properties":{"unlimited":{"type":"boolean","description":"Whether mileage is unlimited"},"includedKilometers":{"type":"integer","exclusiveMinimum":0,"example":500,"description":"Included kilometers (if not unlimited)"}},"required":["unlimited"],"description":"Mileage allowance for the rental"},"DeepLinks":{"type":"object","properties":{"android":{"type":"string","format":"uri","example":"https://play.google.com/store/apps/details?id=com.provider.app","description":"Android app deep link"},"ios":{"type":"string","format":"uri","example":"https://apps.apple.com/app/provider-app/id123456789","description":"iOS app deep link"},"web":{"type":"string","format":"uri","example":"https://provider.com/book?offer=abc123","description":"Web booking URL"}},"description":"Deep links to provider app/website for booking (when API booking not available or as alternative)"},"UpsellCategory":{"type":"string","enum":["EXTRA_SERVICE","EXTRA_COVERAGE","CHILD_SEAT","GPS_DEVICE","WINTER_EQUIPMENT","TRANSPORT_GEAR","OTHER"],"description":"Category of the upsell","example":"GPS_DEVICE"},"UpsellAvailability":{"type":"string","enum":["ALWAYS_INCLUDED","INCLUDED","BOOKABLE","BOOKABLE_ON_PICKUP"],"description":"Availability status of the upsell","example":"BOOKABLE"},"UpsellSummary":{"type":"object","properties":{"referenceCode":{"type":"string","example":"GPS_DEVICE_01","description":"Unique reference code for this upsell product"},"category":{"$ref":"#/components/schemas/UpsellCategory"},"name":{"type":"string","example":"Premium GPS Navigation System","description":"Display name of the upsell product"},"description":{"type":"string","example":"TomTom GO Premium with real-time traffic updates","description":"Brief description of the upsell"},"availability":{"$ref":"#/components/schemas/UpsellAvailability"},"hasPricing":{"type":"boolean","example":true,"description":"Whether pricing information is available. Detailed price is not included in summary (use prebook for full pricing details)."}},"required":["referenceCode","category","name","availability","hasPricing"],"description":"Summary of available upsell. Simplified version for displaying available upsells without full pricing details. Use prebook endpoint to get complete upsell information including pricing."},"CarOffer":{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/Vehicle"},"pickupLocation":{"$ref":"#/components/schemas/LocationDetails"},"dropoffLocation":{"$ref":"#/components/schemas/LocationDetails"},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Date range for rental period"},"price":{"$ref":"#/components/schemas/DetailedPrice"},"insurance":{"$ref":"#/components/schemas/InsuranceCoverage"},"refillPolicy":{"$ref":"#/components/schemas/RefillPolicy"},"mileageAllowance":{"$ref":"#/components/schemas/MileageAllowance"},"offerToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"Encrypted token for booking (single-use). Updates with each API call—always use latest. Valid until usableUntil timestamp. Required for prebook and booking operations."},"usableUntil":{"type":"string","format":"date-time","example":"2025-10-27T16:00:00Z","description":"Token expiration time (ISO 8601). After this, token becomes invalid—start new search. Typically 15-30 minutes from issuance."},"distanceFromSearch":{"type":"number","example":1500,"description":"Distance from search location in meters"},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"deepLinks":{"$ref":"#/components/schemas/DeepLinks"},"availableUpsells":{"type":"array","items":{"$ref":"#/components/schemas/UpsellSummary"},"example":[{"referenceCode":"CHILD_SEAT_7035,7034","category":"CHILD_SEAT","name":"Kindersitz (15-36 kg)","availability":"BOOKABLE","hasPricing":true}],"description":"Summary of available upsells (optional extras, equipment, services). Use the offer details endpoint for more information."}},"required":["vehicle","pickupLocation","dropoffLocation","rentalPeriod","insurance","refillPolicy","mileageAllowance","offerToken","usableUntil","provider"],"description":"Car rental offer with optional detailed price breakdown when estimated kilometers are provided"},"CarSearchResult":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/Vehicle"},"pickupLocation":{"$ref":"#/components/schemas/LocationDetails"},"dropoffLocation":{"$ref":"#/components/schemas/LocationDetails"},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Date range for rental period"},"price":{"$ref":"#/components/schemas/DetailedPrice"},"insurance":{"$ref":"#/components/schemas/InsuranceCoverage"},"refillPolicy":{"$ref":"#/components/schemas/RefillPolicy"},"mileageAllowance":{"$ref":"#/components/schemas/MileageAllowance"},"offerToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"Encrypted token for booking (single-use). Updates with each API call—always use latest. Valid until usableUntil timestamp. Required for prebook and booking operations."},"usableUntil":{"type":"string","format":"date-time","example":"2025-10-27T16:00:00Z","description":"Token expiration time (ISO 8601). After this, token becomes invalid—start new search. Typically 15-30 minutes from issuance."},"distanceFromSearch":{"type":"number","example":1500,"description":"Distance from search location in meters"},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"deepLinks":{"$ref":"#/components/schemas/DeepLinks"},"availableUpsells":{"type":"array","items":{"$ref":"#/components/schemas/UpsellSummary"},"example":[{"referenceCode":"CHILD_SEAT_7035,7034","category":"CHILD_SEAT","name":"Kindersitz (15-36 kg)","availability":"BOOKABLE","hasPricing":true}],"description":"Summary of available upsells (optional extras, equipment, services). Use the offer details endpoint for more information."}},"required":["vehicle","pickupLocation","dropoffLocation","rentalPeriod","insurance","refillPolicy","mileageAllowance","offerToken","usableUntil","provider"],"description":"Car rental offer with optional detailed price breakdown when estimated kilometers are provided"},"description":"List of available car offers. Offers include detailed price breakdown only when estimatedKilometers was provided in the search request; otherwise, only availability information is returned."},"searchedPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Actual rental period for these results (may differ slightly from requested period)"},"pagination":{"allOf":[{"$ref":"#/components/schemas/CursorPaginationMeta"},{"description":"Cursor-based pagination information"}]}},"required":["offers","searchedPeriod","pagination"],"description":"Car search result data. Price information is only included in offers when estimatedKilometers is provided in the search request."},"PolicyAvailability":{"type":"string","enum":["AVAILABLE_VIA_API","REQUIRES_MANUAL_CONTACT","NOT_AVAILABLE"],"description":"How cancellation can be performed: via API, requires manual contact, or not available","example":"AVAILABLE_VIA_API"},"ManualContactMethod":{"type":"string","enum":["PHONE","EMAIL","PROVIDER_WEBSITE","IN_PERSON"],"description":"Contact method for manual actions","example":"PHONE"},"ManualContactInfo":{"type":"object","properties":{"methods":{"type":"array","items":{"$ref":"#/components/schemas/ManualContactMethod"},"example":["PHONE","EMAIL"],"description":"Available contact methods for this action"},"phone":{"type":"string","example":"+49 711 12345 67","description":"Phone number to contact provider"},"email":{"type":"string","format":"email","example":"service@stadtmobil.de","description":"Email address to contact provider"},"url":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/manage-booking","description":"Provider URL for managing booking"},"instructions":{"type":"string","example":"Please call our customer service to cancel your booking","description":"Human-readable instructions for the user on how to proceed"}},"required":["methods"],"description":"Contact information when cancellation requires manual action (only present when availability is REQUIRES_MANUAL_CONTACT)"},"CancellationTerms":{"type":"object","properties":{"fee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Fee charged for cancellation (absolute amount)"}]},"refund":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Amount refunded after cancellation (absolute amount)"}]},"description":{"type":"string","description":"Human-readable description (e.g., 'Free cancellation', '50% of time costs = 25€', '100% refund minus 5.99€ fee')"}},"description":"Combined cancellation terms with fee and refund as absolute amounts","example":{"fee":{"amount":599,"currency":"EUR"},"refund":{"amount":14280,"currency":"EUR"},"description":"100% refund (142.80€) minus 5.99€ cancellation fee"}},"CancellationDeadline":{"type":"object","properties":{"deadline":{"type":"string","format":"date-time","description":"Deadline for this cancellation policy"},"terms":{"$ref":"#/components/schemas/CancellationTerms"}},"required":["deadline","terms"],"description":"Cancellation deadline with associated terms","example":{"deadline":"2025-02-01T00:00:00Z","terms":{"description":"Free cancellation until 24 hours before pickup"}}},"PolicySection":{"type":"object","properties":{"title":{"type":"string","example":"Cancellation Policy","description":"Section title (e.g., 'Cancellation Policy', 'Important Notice')"},"text":{"type":"string","example":"You may cancel your reservation free of charge up to 24 hours before pickup.","description":"Section content in markdown or plain text format for text-based display and processing"},"html":{"type":"string","example":"<p>You may cancel your reservation <strong>free of charge</strong> up to 24 hours before pickup.</p>","description":"Section content in HTML format for rich web display (optional, same content as text field)"},"order":{"type":"integer","minimum":0,"example":1,"description":"Display order (lower numbers appear first)"}},"required":["title","text"],"description":"Human-readable policy section providing supplementary context to machine-readable policy data"},"CancellationPolicy":{"type":"object","properties":{"availability":{"$ref":"#/components/schemas/PolicyAvailability"},"manualContact":{"$ref":"#/components/schemas/ManualContactInfo"},"deadlines":{"type":"array","items":{"$ref":"#/components/schemas/CancellationDeadline"},"description":"Time-based cancellation policies"},"currentTerms":{"allOf":[{"$ref":"#/components/schemas/CancellationTerms"},{"description":"Current terms, if cancelled now"}]},"conditions":{"type":"array","items":{"type":"string"},"example":["Refund processing may take 5-10 business days"],"description":"Additional conditions or restrictions"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/PolicySection"},"description":"Human-readable policy sections providing supplementary context (e.g., detailed explanations, FAQs, special notes)"},"policyUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/cancellation-policy","description":"URL to detailed policy terms"}},"required":["availability"],"description":"Cancellation policy"},"ChangeType":{"type":"string","enum":["RENTAL_TIMES","DRIVER_INFO","PICKUP_LOCATION","DROPOFF_LOCATION","VEHICLE_CATEGORY"],"description":"Type of change that can be made","example":"DRIVER_INFO"},"ChangeTerms":{"type":"object","properties":{"fee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Fee charged for making this change (absolute amount)"}]},"description":{"type":"string","description":"Human-readable description (e.g., 'Free changes', '10% of base price = 12€')"}},"description":"Change terms with associated fee as absolute amount","example":{"description":"Free changes"}},"ChangeDeadline":{"type":"object","properties":{"deadline":{"type":"string","format":"date-time","description":"Deadline for this change policy"},"terms":{"$ref":"#/components/schemas/ChangeTerms"}},"required":["deadline","terms"],"description":"Change deadline with associated terms","example":{"deadline":"2025-02-01T10:00:00Z","terms":{"description":"Free changes until pickup time"}}},"ChangeTypePolicy":{"type":"object","properties":{"changeType":{"$ref":"#/components/schemas/ChangeType"},"availability":{"allOf":[{"$ref":"#/components/schemas/PolicyAvailability"},{"description":"How this type of change can be performed: via API, requires manual contact, or not available"}]},"manualContact":{"allOf":[{"$ref":"#/components/schemas/ManualContactInfo"},{"description":"Contact information when this change requires manual action (only present when availability is REQUIRES_MANUAL_CONTACT)"}]},"deadlines":{"type":"array","items":{"$ref":"#/components/schemas/ChangeDeadline"},"description":"Time-based change policies"},"currentTerms":{"allOf":[{"$ref":"#/components/schemas/ChangeTerms"},{"description":"Current terms if changed now"}]},"conditions":{"type":"array","items":{"type":"string"},"example":["Changes subject to availability"],"description":"Additional conditions"}},"required":["changeType","availability"],"description":"Policy for a specific type of change","example":{"changeType":"DRIVER_INFO","availability":"AVAILABLE_VIA_API","currentTerms":{"description":"Free changes"},"conditions":["Changes subject to availability"]}},"ChangePolicy":{"type":"object","properties":{"availability":{"allOf":[{"$ref":"#/components/schemas/PolicyAvailability"},{"description":"Overall availability status for changes: via API, requires manual contact, or not available"}]},"manualContact":{"allOf":[{"$ref":"#/components/schemas/ManualContactInfo"},{"description":"Contact information when changes require manual action (only present when availability is REQUIRES_MANUAL_CONTACT)"}]},"changeTypes":{"type":"array","items":{"$ref":"#/components/schemas/ChangeTypePolicy"},"description":"Policies for each type of change"},"generalTerms":{"allOf":[{"$ref":"#/components/schemas/ChangeTerms"},{"description":"General terms for any change"}]},"conditions":{"type":"array","items":{"type":"string"},"example":["Changes subject to availability"],"description":"General conditions"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/PolicySection"},"description":"Human-readable policy sections providing supplementary context (e.g., detailed explanations, FAQs, special notes)"},"policyUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/change-policy","description":"URL to detailed policy terms"}},"required":["availability"],"description":"Change/update policy"},"BookingPolicies":{"type":"object","properties":{"cancellation":{"$ref":"#/components/schemas/CancellationPolicy"},"changes":{"$ref":"#/components/schemas/ChangePolicy"},"terms":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/terms-and-conditions","description":"URL to complete terms and conditions document"},"lastUpdated":{"type":"string","format":"date-time","example":"2025-01-15T00:00:00Z","description":"Last update timestamp for terms and conditions (ISO 8601)"},"sections":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","example":"Rental Terms","description":"Section title"},"content":{"type":"string","example":"The renter must be at least 21 years old.\nA valid driver's license is required.","description":"Section content as plain text with line breaks, no HTML formatting"}},"required":["title","content"]},"description":"Structured terms sections for display"}},"description":"Complete terms and conditions information"}},"required":["cancellation","changes"],"description":"Complete cancellation and change policies with machine-readable structure and optional human-readable text sections"},"DetailedCarOffer":{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/Vehicle"},"pickupLocation":{"$ref":"#/components/schemas/LocationDetails"},"dropoffLocation":{"$ref":"#/components/schemas/LocationDetails"},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Date range for rental period"},"insurance":{"$ref":"#/components/schemas/InsuranceCoverage"},"refillPolicy":{"$ref":"#/components/schemas/RefillPolicy"},"mileageAllowance":{"$ref":"#/components/schemas/MileageAllowance"},"offerToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"Encrypted token for booking (single-use). Updates with each API call—always use latest. Valid until usableUntil timestamp. Required for prebook and booking operations."},"usableUntil":{"type":"string","format":"date-time","example":"2025-10-27T16:00:00Z","description":"Token expiration time (ISO 8601). After this, token becomes invalid—start new search. Typically 15-30 minutes from issuance."},"distanceFromSearch":{"type":"number","example":1500,"description":"Distance from search location in meters"},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"deepLinks":{"$ref":"#/components/schemas/DeepLinks"},"availableUpsells":{"type":"array","items":{"$ref":"#/components/schemas/UpsellSummary"},"example":[{"referenceCode":"GPS_DEVICE_01","category":"GPS_DEVICE","name":"Premium GPS Navigation System","description":"TomTom GO Premium with real-time traffic updates","availability":"BOOKABLE","hasPricing":true},{"referenceCode":"CHILD_SEAT_01","category":"CHILD_SEAT","name":"Child Safety Seat","availability":"BOOKABLE","hasPricing":true}],"description":"Summary of available upsells (optional extras, equipment, services). Shows basic info without pricing details. Use prebook endpoint to get complete upsell information with pricing."},"price":{"allOf":[{"$ref":"#/components/schemas/DetailedPrice"},{"description":"Detailed price breakdown with categorized costs"}]},"pickupRequirements":{"type":"array","items":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/PickupRequirementType"},{"description":"Requirement type"}]},"description":{"type":"string","example":"Driver must be at least 21 years old","description":"Human-readable description of the requirement"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"example":21,"description":"Specific requirement value (e.g., age, fee amount)"}},"required":["type","description"],"description":"Pickup or dropoff requirement"},"example":[{"type":"MINIMUM_AGE","description":"Driver must be at least 21 years old","value":21},{"type":"CREDIT_CARD_REQUIRED","description":"Valid credit card required at pickup"}],"description":"Requirements for vehicle pickup"},"policies":{"$ref":"#/components/schemas/BookingPolicies"},"remarks":{"type":"array","items":{"type":"string"},"example":["Airport pickup available at Terminal 2","Additional driver can be added for €10/day"],"description":"Additional remarks and important information"}},"required":["vehicle","pickupLocation","dropoffLocation","rentalPeriod","insurance","refillPolicy","mileageAllowance","offerToken","usableUntil","provider","price","pickupRequirements","policies"],"description":"Detailed car rental offer with complete information including policies and provider details"},"PickupRequirement":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/PickupRequirementType"},{"description":"Requirement type"}]},"description":{"type":"string","example":"Driver must be at least 21 years old","description":"Human-readable description of the requirement"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"example":21,"description":"Specific requirement value (e.g., age, fee amount)"}},"required":["type","description"],"description":"Pickup or dropoff requirement"},"BookingRequirement":{"type":"string","enum":["DRIVER_NAME","DRIVER_EMAIL","DRIVER_AGE","DRIVER_LICENSE_NUMBER","DRIVER_PHONE","DRIVER_ADDRESS","DRIVER_NATIONALITY","FLIGHT_NUMBER"],"description":"Required information field for completing a booking. Only DRIVER_EMAIL is always required. DRIVER_PHONE and DRIVER_NAME are optional but recommended for provider communication.","example":"DRIVER_EMAIL"},"Upsell":{"type":"object","properties":{"referenceCode":{"type":"string","example":"GPS_DEVICE_01","description":"Unique reference code for this upsell product (use in booking request)"},"category":{"$ref":"#/components/schemas/UpsellCategory"},"name":{"type":"string","example":"Premium GPS Navigation System","description":"Display name of the upsell product"},"description":{"type":"string","example":"TomTom GO Premium with real-time traffic, speed camera alerts, and lifetime map updates","description":"Detailed description of the upsell"},"availability":{"$ref":"#/components/schemas/UpsellAvailability"},"price":{"type":"object","properties":{"amount":{"type":"integer","example":15000,"description":"Price in smallest currency unit. Cents for USD/EUR/GBP (÷100), yen for JPY (÷1), fils for KWD (÷1000). See ISO 4217 for currency decimal places."},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"EUR","description":"ISO 4217 currency code"},"description":{"type":"string","example":"Base rental price","description":"Human-readable description of what this price represents"}},"required":["amount","currency"],"description":"Price information for the upsell. Undefined if no additional cost (free) or pricing not available.","example":{"totalCents":1500,"currencyCode":"EUR","description":"Per rental period"}},"maxQuantity":{"type":"integer","minimum":1,"example":2,"description":"Maximum quantity that can be selected (typically 1 for most items)"},"terms":{"type":"array","items":{"type":"string"},"example":["Device must be returned with rental vehicle","Replacement cost: €200 if lost or damaged"],"description":"Additional terms, restrictions, or conditions specific to this upsell"},"imageUrl":{"type":"string","format":"uri","example":"https://example.com/images/gps-device.jpg","description":"Image URL for the upsell product (e.g., product photo)"}},"required":["referenceCode","category","name","description","availability","maxQuantity"],"description":"Detailed upsell information with full pricing and terms. Represents additional services, coverage, or equipment that can be added to a car rental booking."},"PrebookedCarOffer":{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/Vehicle"},"pickupLocation":{"$ref":"#/components/schemas/LocationDetails"},"dropoffLocation":{"$ref":"#/components/schemas/LocationDetails"},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Date range for rental period"},"insurance":{"$ref":"#/components/schemas/InsuranceCoverage"},"refillPolicy":{"$ref":"#/components/schemas/RefillPolicy"},"mileageAllowance":{"$ref":"#/components/schemas/MileageAllowance"},"usableUntil":{"type":"string","format":"date-time","example":"2025-10-27T16:00:00Z","description":"Token expiration time (ISO 8601). After this, token becomes invalid—start new search. Typically 15-30 minutes from issuance."},"distanceFromSearch":{"type":"number","example":1500,"description":"Distance from search location in meters"},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"deepLinks":{"$ref":"#/components/schemas/DeepLinks"},"price":{"allOf":[{"$ref":"#/components/schemas/DetailedPrice"},{"description":"Detailed price breakdown with categorized costs"}]},"pickupRequirements":{"type":"array","items":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/PickupRequirementType"},{"description":"Requirement type"}]},"description":{"type":"string","example":"Driver must be at least 21 years old","description":"Human-readable description of the requirement"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"example":21,"description":"Specific requirement value (e.g., age, fee amount)"}},"required":["type","description"],"description":"Pickup or dropoff requirement"},"example":[{"type":"MINIMUM_AGE","description":"Driver must be at least 21 years old","value":21},{"type":"CREDIT_CARD_REQUIRED","description":"Valid credit card required at pickup"}],"description":"Requirements for vehicle pickup"},"policies":{"$ref":"#/components/schemas/BookingPolicies"},"remarks":{"type":"array","items":{"type":"string"},"example":["Airport pickup available at Terminal 2","Additional driver can be added for €10/day"],"description":"Additional remarks and important information"},"prebookedOfferToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.prebook...","description":"Token containing the prebooking reference. Use this token as the offerToken in the booking endpoint to complete the booking. Valid until reservedUntil timestamp."},"reservedUntil":{"type":"string","format":"date-time","example":"2025-10-27T15:00:00Z","description":"Timestamp when the prebooking/reservation expires (ISO 8601). Must complete booking before this time. Frontend should calculate and display remaining time."},"reservationSupported":{"type":"boolean","example":true,"description":"Whether the provider supports temporary reservations. If false, the offer may become unavailable before booking completion even if reservedUntil has not passed."},"requiredInformation":{"type":"array","items":{"$ref":"#/components/schemas/BookingRequirement"},"example":["DRIVER_EMAIL"],"description":"List of required information fields needed to complete the booking confirmation. Only DRIVER_EMAIL is always required. DRIVER_PHONE and DRIVER_NAME are optional but recommended for provider communication."},"availableUpsells":{"type":"array","items":{"$ref":"#/components/schemas/Upsell"},"example":[{"referenceCode":"GPS_DEVICE_01","category":"GPS_DEVICE","name":"Premium GPS Navigation System","description":"TomTom GO Premium with real-time traffic, speed camera alerts, and lifetime map updates","availability":"BOOKABLE","price":{"totalCents":1500,"currencyCode":"EUR","description":"Per rental period"},"maxQuantity":2,"terms":["Device must be returned with rental vehicle","Replacement cost: EUR200 if lost or damaged"],"imageUrl":"https://example.com/images/gps-device.jpg"}],"description":"Available upsells with full details including pricing. These optional extras, equipment, or services can be selected during booking creation by including their referenceCode in the booking request. Only upsells with availability 'BOOKABLE' should be included in booking selections."},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"PRICE_INCREASED","description":"Machine-readable warning code"},"message":{"type":"string","example":"The price has increased by €10.00 since the original search","description":"Human-readable warning message"},"severity":{"$ref":"#/components/schemas/WarningSeverity"},"field":{"type":"string","example":"pricing.total","description":"Related field (if applicable)"}},"required":["code","message","severity"],"description":"Warning related to API response (non-blocking issues or important notices).\n\nWarnings communicate important information that doesn't prevent the operation from completing but may require user attention or UI adjustments.\n\n## Severity Levels\n\n- **INFO**: Informational message (e.g., \"Reservation expires in 10 minutes\")\n- **WARNING**: Important notice requiring attention (e.g., price changes, limited availability)\n- **CRITICAL**: Critical issue that may affect booking completion (e.g., offer about to expire)\n\n## Car Rental Warning Codes\n\nThe following codes are specific to car rental and car sharing bookings:\n\n| Code | Description |\n|------|-------------|\n| TIME_ROUNDED | Requested time was rounded to provider's time slots |\n| PRICE_CHANGED | Price has changed since last request |\n| PRICE_INCREASED | Price increased from previous offer |\n| PRICE_DECREASED | Price decreased from previous offer |\n| LIMITED_AVAILABILITY | Low stock remaining |\n| PICKUP_LOCATION_CHANGED | Pickup location details updated |\n| RETURN_LOCATION_CHANGED | Return location details updated |\n| FEATURE_UNAVAILABLE | Requested feature not available |\n| POLICY_CHANGED | Rental policy or terms updated |\n| VEHICLE_SUBSTITUTED | Different vehicle model provided |\n| MILEAGE_ADJUSTED | Mileage allowance adjusted |\n| INSURANCE_CHANGED | Insurance coverage level changed |\n| ADDITIONAL_FEES_MAY_APPLY | Extra fees may be charged |\n| OPERATING_HOURS_CHANGED | Operating hours restricted or changed |\n| REFILL_POLICY_CHANGED | Fuel/refill policy differs from requested |\n| AGE_RESTRICTION_APPLIES | Age restrictions or fees apply |\n| ONE_WAY_FEE_APPLIES | One-way rental fee applies |\n| OTHER | Other provider-specific warning |\n\n**Note**: Warning codes may vary by modality type. Additional codes may be introduced for other mobility types in future versions."},"example":[{"code":"PRICE_CHANGED","message":"The price has increased by EUR10.00 since the original search","severity":"warning"}],"description":"Warnings related to the prebooking. Examples: Price changed, offer details updated, limited availability"}},"required":["vehicle","pickupLocation","dropoffLocation","rentalPeriod","insurance","refillPolicy","mileageAllowance","usableUntil","provider","price","pickupRequirements","policies","prebookedOfferToken","reservedUntil","reservationSupported","requiredInformation"],"description":"Prebooked car offer extending DetailedCarOffer with prebooking-specific fields. Includes all offer details (vehicle, pricing, policies, pickup requirements) plus reservation timing, required booking information, full upsell pricing, and any warnings."},"SelectedUpsell":{"type":"object","properties":{"referenceCode":{"type":"string","example":"GPS_DEVICE_01","description":"Reference code from the available upsells (must match Upsell.referenceCode from prebook response)"},"quantity":{"type":"integer","minimum":1,"example":1,"description":"Quantity to book (must be between 1 and Upsell.maxQuantity)"}},"required":["referenceCode","quantity"],"description":"Selected upsell for booking. Only include upsells with availability 'BOOKABLE' (not 'BOOKABLE_ON_PICKUP', 'INCLUDED', or 'ALWAYS_INCLUDED')."},"Driver":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"example":"John Doe","description":"Driver's full name (optional but recommended for provider communication)"},"email":{"type":"string","format":"email","example":"john.doe@example.com","description":"Driver's email address"},"phoneNumber":{"type":"string","minLength":1,"example":"+49123456789","description":"Driver's phone number (optional but recommended for provider contact)"},"age":{"type":"integer","minimum":18,"maximum":120,"example":35,"description":"Driver's age"},"licenseNumber":{"type":"string","example":"D1234567890","description":"Driver's license number"},"address":{"type":"object","properties":{"street":{"type":"string","example":"Hauptstraße 123"},"city":{"type":"string","example":"Berlin"},"postalCode":{"type":"string","example":"10115"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"required":["street","city","postalCode","countryCode"],"description":"Driver's address"},"flightNumber":{"type":"string","example":"LH1234","description":"Flight number for airport pickups"},"nationality":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"required":["email"],"description":"Driver information for booking"},"BookingStatus":{"type":"string","enum":["PENDING","CONFIRMED","IN_PROGRESS","COMPLETED","CANCELLED","FAILED","REQUIRES_CONFIRMATION"],"description":"Current status of the booking","example":"CONFIRMED"},"VehicleAction":{"type":"string","enum":["UNLOCK","LOCK"],"description":"Vehicle action type for remote vehicle control","example":"UNLOCK"},"BookingRequest":{"type":"object","properties":{"offerToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.prebook...","description":"Token from the prebook response or search response to reference prebooking or offer directly. Get this by calling the prebook endpoint first to view full pricing, available upsells, and lock in the offer. Alternatively you can use the offerToken from search result, as long as you've already shown the price to the client previously."},"driver":{"allOf":[{"$ref":"#/components/schemas/Driver"},{"description":"Driver information"}]},"selectedUpsells":{"type":"array","items":{"$ref":"#/components/schemas/SelectedUpsell"},"example":[{"referenceCode":"GPS_DEVICE_01","quantity":1},{"referenceCode":"CHILD_SEAT_01","quantity":2}],"description":"Optional list of selected upsells to add to the booking. Only include upsells with availability 'BOOKABLE' from the prebook response. Each selected upsell must have a valid referenceCode from the availableUpsells array. Note: Upsell pricing is only available through the prebook endpoint."},"notes":{"type":"string","maxLength":500,"description":"Additional notes or special requests"}},"required":["driver"],"additionalProperties":false,"description":"Request to create a new booking. Two booking flows are supported:\n\n**Recommended: Prebook Flow** (Search → Prebook → Book)\n- Use `prebookedOfferToken` from the prebook response for offerToken reference\n- Provides locked pricing, available upsells with pricing, and requiredInformation fields\n- Best user experience with guaranteed availability (if provider supports reservations)\n\n**Direct Booking Flow** (Search → Book)\n- Use `offerToken` directly from search results or offer details for offerToken reference\n- Requires that you already showed the `price` information to the client\n- Skips prebooking step but loses benefits: no locked pricing, no upsell pricing, no requiredInformation\n- Note: Offer details do NOT include requiredInformation - therefore collect all potentially required driver fields"},"CancelRequest":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Reason for cancellation"}},"additionalProperties":false,"description":"Request to cancel a booking"},"UpdateRequest":{"type":"object","properties":{"driver":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"example":"John Doe","description":"Driver's full name (optional but recommended for provider communication)"},"email":{"type":"string","format":"email","example":"john.doe@example.com","description":"Driver's email address"},"phoneNumber":{"type":"string","minLength":1,"example":"+49123456789","description":"Driver's phone number (optional but recommended for provider contact)"},"age":{"type":"integer","minimum":18,"maximum":120,"example":35,"description":"Driver's age"},"licenseNumber":{"type":"string","example":"D1234567890","description":"Driver's license number"},"address":{"type":"object","properties":{"street":{"type":"string","example":"Hauptstraße 123"},"city":{"type":"string","example":"Berlin"},"postalCode":{"type":"string","example":"10115"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"required":["street","city","postalCode","countryCode"],"description":"Driver's address"},"flightNumber":{"type":"string","example":"LH1234","description":"Flight number for airport pickups"},"nationality":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"description":"Updated driver information"},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"New rental period. Check `policies.changes.changeTypes` for RENTAL_TIMES availability before attempting to change times."},"notes":{"type":"string","maxLength":500,"description":"Updated notes or special requests"}},"additionalProperties":false,"description":"Request to update booking information.\n\n**Supported update types:**\n- `driver`: Update driver information (name, email, phone, etc.)\n- `rentalPeriod`: Change pickup/return times (requires provider support)\n- `notes`: Update booking notes\n\n**Important:** Before changing rental times, check `GET /cars/bookings/{id}` response for `policies.changes.changeTypes` to verify RENTAL_TIMES is available."},"VehicleActionRequest":{"type":"object","properties":{"action":{"allOf":[{"$ref":"#/components/schemas/VehicleAction"},{"description":"Action to perform on the vehicle"}]},"pin":{"type":"string","minLength":1,"maxLength":20,"example":"1234","description":"PIN for UNLOCK action when the booking requires PIN authentication (unlockRequiresPin=true). Ignored for LOCK action."}},"required":["action"],"additionalProperties":false,"description":"Request to perform a vehicle action (lock/unlock)"},"CarBooking":{"type":"object","properties":{"bookingId":{"type":"string","description":"Unique booking identifier"},"status":{"allOf":[{"$ref":"#/components/schemas/BookingStatus"},{"description":"Current booking status"}]},"confirmationNumber":{"type":"string","description":"Booking confirmation number"},"emailSentTo":{"type":"string","format":"email","description":"Email where confirmation was sent"},"voucherUrl":{"type":"string","format":"uri","description":"URL to download booking voucher"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"PRICE_INCREASED","description":"Machine-readable warning code"},"message":{"type":"string","example":"The price has increased by €10.00 since the original search","description":"Human-readable warning message"},"severity":{"$ref":"#/components/schemas/WarningSeverity"},"field":{"type":"string","example":"pricing.total","description":"Related field (if applicable)"}},"required":["code","message","severity"],"description":"Warning related to API response (non-blocking issues or important notices).\n\nWarnings communicate important information that doesn't prevent the operation from completing but may require user attention or UI adjustments.\n\n## Severity Levels\n\n- **INFO**: Informational message (e.g., \"Reservation expires in 10 minutes\")\n- **WARNING**: Important notice requiring attention (e.g., price changes, limited availability)\n- **CRITICAL**: Critical issue that may affect booking completion (e.g., offer about to expire)\n\n## Car Rental Warning Codes\n\nThe following codes are specific to car rental and car sharing bookings:\n\n| Code | Description |\n|------|-------------|\n| TIME_ROUNDED | Requested time was rounded to provider's time slots |\n| PRICE_CHANGED | Price has changed since last request |\n| PRICE_INCREASED | Price increased from previous offer |\n| PRICE_DECREASED | Price decreased from previous offer |\n| LIMITED_AVAILABILITY | Low stock remaining |\n| PICKUP_LOCATION_CHANGED | Pickup location details updated |\n| RETURN_LOCATION_CHANGED | Return location details updated |\n| FEATURE_UNAVAILABLE | Requested feature not available |\n| POLICY_CHANGED | Rental policy or terms updated |\n| VEHICLE_SUBSTITUTED | Different vehicle model provided |\n| MILEAGE_ADJUSTED | Mileage allowance adjusted |\n| INSURANCE_CHANGED | Insurance coverage level changed |\n| ADDITIONAL_FEES_MAY_APPLY | Extra fees may be charged |\n| OPERATING_HOURS_CHANGED | Operating hours restricted or changed |\n| REFILL_POLICY_CHANGED | Fuel/refill policy differs from requested |\n| AGE_RESTRICTION_APPLIES | Age restrictions or fees apply |\n| ONE_WAY_FEE_APPLIES | One-way rental fee applies |\n| OTHER | Other provider-specific warning |\n\n**Note**: Warning codes may vary by modality type. Additional codes may be introduced for other mobility types in future versions."},"description":"Warnings about the booking"},"message":{"type":"string","description":"Status message for pending or failed bookings"}},"required":["bookingId","status"],"description":"Car booking data"},"BookedUpsell":{"type":"object","properties":{"referenceCode":{"type":"string","example":"CHILD_SEAT_7035,7034","description":"Reference code of the booked upsell"},"category":{"allOf":[{"$ref":"#/components/schemas/UpsellCategory"},{"example":"CHILD_SEAT"}]},"name":{"type":"string","example":"Kindersitz (15-36 kg)","description":"Display name of the booked upsell"},"quantity":{"type":"integer","minimum":1,"example":2,"description":"Quantity that was booked"},"price":{"type":"object","properties":{"amount":{"type":"integer","example":15000,"description":"Price in smallest currency unit. Cents for USD/EUR/GBP (÷100), yen for JPY (÷1), fils for KWD (÷1000). See ISO 4217 for currency decimal places."},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"EUR","description":"ISO 4217 currency code"},"description":{"type":"string","example":"Base rental price","description":"Human-readable description of what this price represents"}},"required":["amount","currency"],"description":"Price per unit for this upsell","example":{"amount":0,"currency":"EUR"}}},"required":["referenceCode","category","name","quantity"],"description":"Upsell that was booked with the rental. Contains the resolved details from the booking including name, category, and price."},"DetailedCarBooking":{"type":"object","properties":{"bookingId":{"type":"string","description":"Unique booking identifier"},"status":{"allOf":[{"$ref":"#/components/schemas/BookingStatus"},{"description":"Current booking status"}]},"confirmationNumber":{"type":"string","description":"Booking confirmation number"},"vehicle":{"allOf":[{"$ref":"#/components/schemas/Vehicle"},{"description":"Vehicle details from the booking"}]},"pickupLocation":{"allOf":[{"$ref":"#/components/schemas/LocationDetails"},{"description":"Pickup location"}]},"dropoffLocation":{"allOf":[{"$ref":"#/components/schemas/LocationDetails"},{"description":"Dropoff location"}]},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Rental period"},"offerPrice":{"allOf":[{"$ref":"#/components/schemas/DetailedPrice"},{"description":"Original pricing from when the offer was booked. Represents estimated costs based on the planned trip duration and conditions at booking time."}]},"chargedRate":{"allOf":[{"$ref":"#/components/schemas/DetailedPrice"},{"description":"Actual amount that will be charged. This may differ from offerPricing as it reflects real usage (e.g., actual kilometers driven, extended rental duration, or additional services used during the rental)."}]},"insurance":{"allOf":[{"$ref":"#/components/schemas/InsuranceCoverage"},{"description":"Insurance coverage included"}]},"refillPolicy":{"allOf":[{"$ref":"#/components/schemas/RefillPolicy"},{"description":"Refueling/recharging policy"}]},"mileageAllowance":{"allOf":[{"$ref":"#/components/schemas/MileageAllowance"},{"description":"Mileage allowance"}]},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"pickupRequirements":{"type":"array","items":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/PickupRequirementType"},{"description":"Requirement type"}]},"description":{"type":"string","example":"Driver must be at least 21 years old","description":"Human-readable description of the requirement"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"example":21,"description":"Specific requirement value (e.g., age, fee amount)"}},"required":["type","description"],"description":"Pickup or dropoff requirement"},"description":"Requirements for vehicle pickup"},"bookedUpsells":{"type":"array","items":{"$ref":"#/components/schemas/BookedUpsell"},"description":"Upsells that were booked with this rental (e.g., child seats, GPS)"},"remarks":{"type":"array","items":{"type":"string"},"description":"Additional remarks and important information"},"driver":{"allOf":[{"$ref":"#/components/schemas/Driver"},{"description":"Driver information"}]},"actualVehicle":{"type":"object","properties":{"licensePlate":{"type":"string","description":"License plate of assigned vehicle"},"imageUrl":{"type":"string","format":"uri","description":"Photo of the actual vehicle"}},"description":"Actual vehicle assigned (when available)"},"policies":{"allOf":[{"$ref":"#/components/schemas/BookingPolicies"},{"description":"Cancellation and change policies"}]},"supportedVehicleActions":{"type":"array","items":{"$ref":"#/components/schemas/VehicleAction"},"description":"Vehicle actions supported for this booking (e.g., UNLOCK, LOCK)"},"unlockRequiresPin":{"type":"boolean","description":"When true, a PIN must be provided in the vehicle-action request to unlock the vehicle. The PIN is typically displayed on the vehicle or provided by the rental station."},"cancellation":{"type":"object","properties":{"cancelledAt":{"type":"string","format":"date-time","description":"When the booking was cancelled"},"cancellationFee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Cancellation fee charged"}]},"refundAmount":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Amount refunded"}]},"reason":{"type":"string","description":"Cancellation reason"}},"required":["cancelledAt"],"description":"Cancellation details (if cancelled)"},"createdAt":{"type":"string","format":"date-time","description":"When the booking was created"},"lastModifiedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"PRICE_INCREASED","description":"Machine-readable warning code"},"message":{"type":"string","example":"The price has increased by €10.00 since the original search","description":"Human-readable warning message"},"severity":{"$ref":"#/components/schemas/WarningSeverity"},"field":{"type":"string","example":"pricing.total","description":"Related field (if applicable)"}},"required":["code","message","severity"],"description":"Warning related to API response (non-blocking issues or important notices).\n\nWarnings communicate important information that doesn't prevent the operation from completing but may require user attention or UI adjustments.\n\n## Severity Levels\n\n- **INFO**: Informational message (e.g., \"Reservation expires in 10 minutes\")\n- **WARNING**: Important notice requiring attention (e.g., price changes, limited availability)\n- **CRITICAL**: Critical issue that may affect booking completion (e.g., offer about to expire)\n\n## Car Rental Warning Codes\n\nThe following codes are specific to car rental and car sharing bookings:\n\n| Code | Description |\n|------|-------------|\n| TIME_ROUNDED | Requested time was rounded to provider's time slots |\n| PRICE_CHANGED | Price has changed since last request |\n| PRICE_INCREASED | Price increased from previous offer |\n| PRICE_DECREASED | Price decreased from previous offer |\n| LIMITED_AVAILABILITY | Low stock remaining |\n| PICKUP_LOCATION_CHANGED | Pickup location details updated |\n| RETURN_LOCATION_CHANGED | Return location details updated |\n| FEATURE_UNAVAILABLE | Requested feature not available |\n| POLICY_CHANGED | Rental policy or terms updated |\n| VEHICLE_SUBSTITUTED | Different vehicle model provided |\n| MILEAGE_ADJUSTED | Mileage allowance adjusted |\n| INSURANCE_CHANGED | Insurance coverage level changed |\n| ADDITIONAL_FEES_MAY_APPLY | Extra fees may be charged |\n| OPERATING_HOURS_CHANGED | Operating hours restricted or changed |\n| REFILL_POLICY_CHANGED | Fuel/refill policy differs from requested |\n| AGE_RESTRICTION_APPLIES | Age restrictions or fees apply |\n| ONE_WAY_FEE_APPLIES | One-way rental fee applies |\n| OTHER | Other provider-specific warning |\n\n**Note**: Warning codes may vary by modality type. Additional codes may be introduced for other mobility types in future versions."},"description":"Warnings about the booking"}},"required":["bookingId","status","vehicle","pickupLocation","dropoffLocation","rentalPeriod","offerPrice","chargedRate","insurance","refillPolicy","mileageAllowance","provider","driver","policies","createdAt","lastModifiedAt"],"description":"Complete car booking details with flattened offer information"},"CancelCarBookingData":{"type":"object","properties":{"bookingId":{"type":"string","description":"Cancelled booking identifier"},"status":{"type":"string","enum":["CANCELLED"],"description":"New booking status"},"cancelledAt":{"type":"string","format":"date-time","description":"Cancellation timestamp"},"cancellationFee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Cancellation fee charged"}]},"refundAmount":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Amount to be refunded"}]},"confirmationNumber":{"type":"string","description":"Cancellation confirmation number"}},"required":["bookingId","status","cancelledAt"],"description":"Car booking cancellation data"},"UpdateCarBookingData":{"type":"object","properties":{"bookingId":{"type":"string","description":"Updated booking identifier"},"status":{"allOf":[{"$ref":"#/components/schemas/BookingStatus"},{"description":"Current booking status"}]},"lastModifiedAt":{"type":"string","format":"date-time","description":"Update timestamp"},"changeFee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Additional fee for changes"}]},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"PRICE_INCREASED","description":"Machine-readable warning code"},"message":{"type":"string","example":"The price has increased by €10.00 since the original search","description":"Human-readable warning message"},"severity":{"$ref":"#/components/schemas/WarningSeverity"},"field":{"type":"string","example":"pricing.total","description":"Related field (if applicable)"}},"required":["code","message","severity"],"description":"Warning related to API response (non-blocking issues or important notices).\n\nWarnings communicate important information that doesn't prevent the operation from completing but may require user attention or UI adjustments.\n\n## Severity Levels\n\n- **INFO**: Informational message (e.g., \"Reservation expires in 10 minutes\")\n- **WARNING**: Important notice requiring attention (e.g., price changes, limited availability)\n- **CRITICAL**: Critical issue that may affect booking completion (e.g., offer about to expire)\n\n## Car Rental Warning Codes\n\nThe following codes are specific to car rental and car sharing bookings:\n\n| Code | Description |\n|------|-------------|\n| TIME_ROUNDED | Requested time was rounded to provider's time slots |\n| PRICE_CHANGED | Price has changed since last request |\n| PRICE_INCREASED | Price increased from previous offer |\n| PRICE_DECREASED | Price decreased from previous offer |\n| LIMITED_AVAILABILITY | Low stock remaining |\n| PICKUP_LOCATION_CHANGED | Pickup location details updated |\n| RETURN_LOCATION_CHANGED | Return location details updated |\n| FEATURE_UNAVAILABLE | Requested feature not available |\n| POLICY_CHANGED | Rental policy or terms updated |\n| VEHICLE_SUBSTITUTED | Different vehicle model provided |\n| MILEAGE_ADJUSTED | Mileage allowance adjusted |\n| INSURANCE_CHANGED | Insurance coverage level changed |\n| ADDITIONAL_FEES_MAY_APPLY | Extra fees may be charged |\n| OPERATING_HOURS_CHANGED | Operating hours restricted or changed |\n| REFILL_POLICY_CHANGED | Fuel/refill policy differs from requested |\n| AGE_RESTRICTION_APPLIES | Age restrictions or fees apply |\n| ONE_WAY_FEE_APPLIES | One-way rental fee applies |\n| OTHER | Other provider-specific warning |\n\n**Note**: Warning codes may vary by modality type. Additional codes may be introduced for other mobility types in future versions."},"description":"Warnings about the update"}},"required":["bookingId","status","lastModifiedAt"],"description":"Car booking update data"},"VehicleActionData":{"type":"object","properties":{"bookingId":{"type":"string","description":"Booking identifier"},"action":{"allOf":[{"$ref":"#/components/schemas/VehicleAction"},{"description":"Action that was requested"}]},"acceptedAt":{"type":"string","format":"date-time","description":"When the action was accepted"}},"required":["bookingId","action","acceptedAt"],"description":"Vehicle action acceptance data"},"ModalityIndependentBookingSummary":{"type":"object","properties":{"bookingId":{"type":"string","example":"bc_A1B2C3D4E","description":"Unique booking identifier"},"status":{"type":"string","example":"CONFIRMED","description":"Current booking status"},"createdAt":{"type":"string","example":"2025-01-15T10:30:00Z","description":"Booking creation timestamp (ISO 8601)"},"bookingType":{"type":"string","enum":["cars"]},"pickupLocation":{"type":"string","example":"Berlin Central Station","description":"Pickup location name"},"returnLocation":{"type":"string","example":"Munich Airport","description":"Return location name"},"pickupDateTime":{"type":"string","example":"2025-02-01T10:00:00Z","description":"Pickup date and time (ISO 8601)"},"returnDateTime":{"type":"string","example":"2025-02-05T18:00:00Z","description":"Return date and time (ISO 8601)"},"totalPrice":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Total rental price"}]},"vehicleMake":{"type":"string","example":"BMW","description":"Vehicle make"},"vehicleModel":{"type":"string","example":"3 Series","description":"Vehicle model"}},"required":["bookingId","status","createdAt","bookingType","pickupLocation","returnLocation","pickupDateTime","returnDateTime","totalPrice","vehicleMake","vehicleModel"],"description":"Booking summary for car rentals"},"BookingListData":{"type":"object","properties":{"bookings":{"type":"array","items":{"type":"object","properties":{"bookingId":{"type":"string","example":"bc_A1B2C3D4E","description":"Unique booking identifier"},"status":{"type":"string","example":"CONFIRMED","description":"Current booking status"},"createdAt":{"type":"string","example":"2025-01-15T10:30:00Z","description":"Booking creation timestamp (ISO 8601)"},"bookingType":{"type":"string","enum":["cars"]},"pickupLocation":{"type":"string","example":"Berlin Central Station","description":"Pickup location name"},"returnLocation":{"type":"string","example":"Munich Airport","description":"Return location name"},"pickupDateTime":{"type":"string","example":"2025-02-01T10:00:00Z","description":"Pickup date and time (ISO 8601)"},"returnDateTime":{"type":"string","example":"2025-02-05T18:00:00Z","description":"Return date and time (ISO 8601)"},"totalPrice":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Total rental price"}]},"vehicleMake":{"type":"string","example":"BMW","description":"Vehicle make"},"vehicleModel":{"type":"string","example":"3 Series","description":"Vehicle model"}},"required":["bookingId","status","createdAt","bookingType","pickupLocation","returnLocation","pickupDateTime","returnDateTime","totalPrice","vehicleMake","vehicleModel"],"description":"Booking summary for car rentals"}},"pagination":{"allOf":[{"$ref":"#/components/schemas/PaginationMeta"},{"description":"Pagination metadata"}]}},"required":["bookings","pagination"],"description":"Booking list data payload"},"ProviderCapabilityLevel":{"type":"string","enum":["SEARCH_ONLY","SEARCH_AND_BOOKING","FULL_SERVICE"],"description":"Level of service capabilities offered by the provider","example":"FULL_SERVICE"},"MobilityMode":{"type":"string","enum":["CAR"],"description":"Supported mobility mode","example":"CAR"},"MobilityProviderMinimal":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.png","description":"URL to provider's logo image (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider's website URL"},"supportedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"example":["DE","FR","IT","ES"],"description":"List of supported countries (ISO 3166-1 alpha-2 codes)"},"capabilityLevel":{"allOf":[{"$ref":"#/components/schemas/ProviderCapabilityLevel"},{"description":"Level of service capabilities offered by this provider"}]}},"required":["id","name","capabilityLevel"],"description":"Basic information about a mobility service provider"},"MobilityProviderDetailed":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.png","description":"URL to provider's logo image (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider's website URL"},"supportedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"example":["DE","FR","IT","ES"],"description":"List of supported countries (ISO 3166-1 alpha-2 codes)"},"capabilityLevel":{"allOf":[{"$ref":"#/components/schemas/ProviderCapabilityLevel"},{"description":"Level of service capabilities offered by this provider"}]},"description":{"type":"string","example":"Carsharing service operating in multiple German cities","description":"Provider description"},"modes":{"type":"array","items":{"$ref":"#/components/schemas/MobilityMode"},"example":["CAR"],"description":"Supported mobility modes"},"termsOfServicesUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/terms","description":"Terms of service URL"},"privacyPolicyUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/privacy","description":"Privacy policy URL"},"generalContactInfo":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"support@stadtmobil.de","description":"Contact email address"},"phoneNr":{"type":"string","example":"+49 711 12345 67","description":"Contact phone number"},"contactFormUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/contact","description":"URL to contact form"},"contactPerson":{"type":"object","properties":{"firstName":{"type":"string","example":"John","description":"Contact person's first name"},"lastName":{"type":"string","example":"Smith","description":"Contact person's last name"},"role":{"type":"string","example":"Customer Support Manager","description":"Contact person's role or title"}},"description":"Contact person information"}},"required":["email"],"description":"General contact information"},"supportContactInfo":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"support@stadtmobil.de","description":"Contact email address"},"phoneNr":{"type":"string","example":"+49 711 12345 67","description":"Contact phone number"},"contactFormUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/contact","description":"URL to contact form"},"contactPerson":{"type":"object","properties":{"firstName":{"type":"string","example":"John","description":"Contact person's first name"},"lastName":{"type":"string","example":"Smith","description":"Contact person's last name"},"role":{"type":"string","example":"Customer Support Manager","description":"Contact person's role or title"}},"description":"Contact person information"}},"required":["email"],"description":"Support contact information"},"salesContactInfo":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"support@stadtmobil.de","description":"Contact email address"},"phoneNr":{"type":"string","example":"+49 711 12345 67","description":"Contact phone number"},"contactFormUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/contact","description":"URL to contact form"},"contactPerson":{"type":"object","properties":{"firstName":{"type":"string","example":"John","description":"Contact person's first name"},"lastName":{"type":"string","example":"Smith","description":"Contact person's last name"},"role":{"type":"string","example":"Customer Support Manager","description":"Contact person's role or title"}},"description":"Contact person information"}},"required":["email"],"description":"Sales contact information"},"marketing":{"type":"object","properties":{"colors":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["PRIMARY","SECONDARY","ACCENT"],"example":"PRIMARY","description":"Color category"},"color":{"type":"string","example":"#FF5F00","description":"Hex color code"}},"required":["category","color"],"description":"Brand color information"},"description":"Brand colors"}},"description":"Marketing and branding information"},"supportedLanguages":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"example":["en","de","fr","es"],"description":"List of supported languages (ISO 639-1 codes)"}},"required":["id","name","capabilityLevel","generalContactInfo"],"description":"Detailed information about a mobility service provider"},"MobilityProvidersListData":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.png","description":"URL to provider's logo image (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider's website URL"},"supportedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"example":["DE","FR","IT","ES"],"description":"List of supported countries (ISO 3166-1 alpha-2 codes)"},"capabilityLevel":{"allOf":[{"$ref":"#/components/schemas/ProviderCapabilityLevel"},{"description":"Level of service capabilities offered by this provider"}]}},"required":["id","name","capabilityLevel"],"description":"Basic information about a mobility service provider"},"description":"List of mobility service providers"},"pagination":{"allOf":[{"$ref":"#/components/schemas/PaginationMeta"},{"description":"Pagination metadata"}]}},"required":["providers","pagination"],"description":"Mobility providers list data payload"},"StationService":{"type":"string","enum":["PICKUP","DROPOFF"],"description":"Available services at the station","example":"PICKUP"},"Station":{"type":"object","properties":{"placeId":{"allOf":[{"$ref":"#/components/schemas/PlaceId"},{"example":"p_a4cd2f829a292229d","description":"Unique place identifier for use in car search requests"}]},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"name":{"type":"string","example":"Berlin Central Station","description":"Station name (e.g., 'Downtown Station', 'Airport Terminal 2')"},"address":{"type":"object","properties":{"street":{"type":"string","example":"Europaplatz 1","description":"Street address"},"city":{"type":"string","example":"Berlin","description":"City name"},"postalCode":{"type":"string","example":"10557","description":"Postal/ZIP code"},"country":{"type":"string","example":"Germany","description":"Country name"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"required":["city","country","countryCode"],"description":"Physical address"},"coordinates":{"$ref":"#/components/schemas/Coordinates"},"distanceMeters":{"type":["number","null"],"minimum":0,"example":1250,"description":"Distance in meters from search center point (for coordinate searches) or null for bounding box searches"},"operatingHours":{"type":["string","null"],"example":"24/7","description":"Operating hours description (e.g., '24/7', 'Mon-Fri 08:00-18:00'). May be null if not provided by provider."},"availableServices":{"type":"array","items":{"$ref":"#/components/schemas/StationService"},"example":["PICKUP","DROPOFF"],"description":"Services available at this station (pickup, dropoff, or both)"},"additionalInfo":{"type":"string","example":"Terminal A, Level 3","description":"Additional location information (e.g., 'Terminal A, Level 3', 'Inside parking garage')"},"offerCount":{"type":"integer","minimum":0,"example":15,"description":"Number of available offers at this station (only included when pickupDate and returnDate are provided in request). This is an estimate and does not guarantee availability."}},"required":["placeId","provider","name","address","coordinates","distanceMeters","operatingHours","availableServices"],"description":"Car rental station/location information"},"StationSearchContext":{"type":"object","properties":{"searchCenter":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Center point of the search (for coordinate-based searches) or center of bounding box"}]},"searchRadiusMeters":{"type":"number","exclusiveMinimum":0,"description":"Search radius in meters (only for coordinate-based searches with radius)"},"boundingBox":{"type":"object","properties":{"southwest":{"$ref":"#/components/schemas/Coordinates"},"northeast":{"$ref":"#/components/schemas/Coordinates"}},"required":["southwest","northeast"],"description":"Bounding box used for search (only for bounding box searches)"}},"description":"Information about the search area and parameters"},"StationSearchData":{"type":"object","properties":{"stations":{"type":"array","items":{"type":"object","properties":{"placeId":{"allOf":[{"$ref":"#/components/schemas/PlaceId"},{"example":"p_a4cd2f829a292229d","description":"Unique place identifier for use in car search requests"}]},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"name":{"type":"string","example":"Berlin Central Station","description":"Station name (e.g., 'Downtown Station', 'Airport Terminal 2')"},"address":{"type":"object","properties":{"street":{"type":"string","example":"Europaplatz 1","description":"Street address"},"city":{"type":"string","example":"Berlin","description":"City name"},"postalCode":{"type":"string","example":"10557","description":"Postal/ZIP code"},"country":{"type":"string","example":"Germany","description":"Country name"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"required":["city","country","countryCode"],"description":"Physical address"},"coordinates":{"$ref":"#/components/schemas/Coordinates"},"distanceMeters":{"type":["number","null"],"minimum":0,"example":1250,"description":"Distance in meters from search center point (for coordinate searches) or null for bounding box searches"},"operatingHours":{"type":["string","null"],"example":"24/7","description":"Operating hours description (e.g., '24/7', 'Mon-Fri 08:00-18:00'). May be null if not provided by provider."},"availableServices":{"type":"array","items":{"$ref":"#/components/schemas/StationService"},"example":["PICKUP","DROPOFF"],"description":"Services available at this station (pickup, dropoff, or both)"},"additionalInfo":{"type":"string","example":"Terminal A, Level 3","description":"Additional location information (e.g., 'Terminal A, Level 3', 'Inside parking garage')"},"offerCount":{"type":"integer","minimum":0,"example":15,"description":"Number of available offers at this station (only included when pickupDate and returnDate are provided in request). This is an estimate and does not guarantee availability."}},"required":["placeId","provider","name","address","coordinates","distanceMeters","operatingHours","availableServices"],"description":"Car rental station/location information"},"description":"List of stations matching search criteria"},"searchContext":{"$ref":"#/components/schemas/StationSearchContext"},"pagination":{"allOf":[{"$ref":"#/components/schemas/CursorPaginationMeta"},{"description":"Cursor-based pagination information"}]}},"required":["stations","searchContext","pagination"],"description":"Station search results data"},"MicroMobilityVehicleType":{"type":"string","enum":["SCOOTER","BICYCLE","MOPED","CARGO_BICYCLE","OTHER"],"description":"Type of micro mobility vehicle","example":"SCOOTER"},"PropulsionType":{"type":"string","enum":["HUMAN","ELECTRIC_ASSIST","ELECTRIC","COMBUSTION"],"description":"Type of propulsion system","example":"ELECTRIC"},"ZoneType":{"type":"string","enum":["SERVICE_AREA","PARKING_ZONE","NO_PARKING_ZONE","NO_RIDE_ZONE","SLOW_ZONE","PREFERRED_PARKING"],"description":"Type of geofencing zone","example":"SERVICE_AREA"},"VehicleLocation":{"type":"object","properties":{"latitude":{"type":"number","example":48.7758,"description":"Latitude in decimal degrees (WGS84)"},"longitude":{"type":"number","example":9.1829,"description":"Longitude in decimal degrees (WGS84)"},"lastUpdated":{"type":"string","format":"date-time","example":"2025-01-15T10:30:00Z","description":"When location was last updated"}},"required":["latitude","longitude","lastUpdated"],"description":"Real-time vehicle location"},"MicroMobilityVehicleDetails":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/MicroMobilityVehicleType"},{"description":"Type of vehicle"}]},"propulsionType":{"allOf":[{"$ref":"#/components/schemas/PropulsionType"},{"description":"Propulsion type"}]},"name":{"type":"string","example":"Dott E-Scooter Gen 4","description":"Vehicle model name from provider"},"imageUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.de/vehicles/dott/scooter.jpg","description":"URL to vehicle image"},"maxRangeMeters":{"type":"integer","exclusiveMinimum":0,"example":35000,"description":"Maximum range when fully charged (meters)"}},"required":["type","propulsionType"],"description":"Detailed vehicle information"},"MicroMobilityProviderDisplay":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.de/providers/dott.svg","description":"URL to provider logo"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"},"supportEmail":{"type":"string","format":"email","example":"support@ridedott.com","description":"Support email address"},"supportPhone":{"type":"string","example":"+49 800 123 4567","description":"Support phone number"}},"required":["id","name","logoUrl"],"description":"Provider information with support contacts"},"PricingSegment":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"example":0,"description":"Starting unit (minute or kilometer) for this segment"},"rate":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Price per interval unit"}]},"interval":{"type":"integer","exclusiveMinimum":0,"example":1,"description":"Billing interval (e.g., 1 = per minute/km)"},"end":{"type":"integer","example":30,"description":"Ending unit for this segment (null = unlimited)"}},"required":["start","rate","interval"],"description":"A segment of tiered pricing (e.g., first 30 minutes at one rate, then another)"},"PricingPlanSummary":{"type":"object","properties":{"planId":{"type":"string","description":"Unique pricing plan identifier"},"name":{"type":"string","description":"Display name of the plan"},"description":{"type":"string","description":"Detailed plan description"},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"EUR","description":"ISO 4217 currency code"},"isTaxable":{"type":"boolean","description":"Whether prices include/are subject to tax"},"unlockFee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"One-time unlock fee"}]},"perMinuteRate":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Per-minute rate summary (first segment). Use perMinutePricing for full details."}]},"perKmRate":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Per-km rate summary (first segment). Use perKmPricing for full details."}]},"perMinutePricing":{"type":"array","items":{"$ref":"#/components/schemas/PricingSegment"},"description":"Detailed per-minute pricing segments (progressive pricing)"},"perKmPricing":{"type":"array","items":{"$ref":"#/components/schemas/PricingSegment"},"description":"Detailed per-kilometer pricing segments"}},"required":["planId","name","currency","unlockFee"],"description":"Pricing plan for this vehicle. May be unavailable for some providers."},"MicroMobilityVehicle":{"type":"object","properties":{"vehicleId":{"type":"string","example":"aeece12e-38c0-42c5-8a61-bbb70a5a69d3","description":"Unique vehicle identifier"},"vehicle":{"$ref":"#/components/schemas/MicroMobilityVehicleDetails"},"vehicleType":{"allOf":[{"$ref":"#/components/schemas/MicroMobilityVehicleType"},{"description":"Type of vehicle"}]},"propulsionType":{"allOf":[{"$ref":"#/components/schemas/PropulsionType"},{"description":"Propulsion type"}]},"location":{"allOf":[{"$ref":"#/components/schemas/VehicleLocation"},{"description":"Current vehicle location"}]},"isAvailable":{"type":"boolean","example":true,"description":"Vehicle can be rented right now"},"isReserved":{"type":"boolean","example":false,"description":"Vehicle is currently reserved by another user"},"isDisabled":{"type":"boolean","example":false,"description":"Vehicle is out of service"},"batteryPercent":{"type":"number","minimum":0,"maximum":100,"example":85,"description":"Battery level 0-100"},"currentRangeMeters":{"type":"number","example":12000,"description":"Estimated remaining range in meters"},"provider":{"$ref":"#/components/schemas/MicroMobilityProviderDisplay"},"pricingPlan":{"$ref":"#/components/schemas/PricingPlanSummary"},"vehicleToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiJ9...","description":"Encrypted token for subsequent operations. Valid for a short time (typically 5 minutes). Required for reserve or start trip."},"tokenValidUntil":{"type":"string","format":"date-time","example":"2025-01-15T10:35:00Z","description":"Token expiration time"},"distanceFromSearch":{"type":"number","example":150,"description":"Distance from search location in meters"},"deepLinks":{"type":"object","properties":{"android":{"type":"string","format":"uri","description":"Android app deep link"},"ios":{"type":"string","format":"uri","description":"iOS app deep link"},"web":{"type":"string","format":"uri","description":"Web booking link"}},"description":"Deep links to provider app for booking (when API booking not available)"}},"required":["vehicleId","vehicle","vehicleType","propulsionType","location","isAvailable","isReserved","isDisabled","provider","vehicleToken","tokenValidUntil"],"description":"Available micro mobility vehicle with real-time status and pricing"},"PricingPlanDetailed":{"type":"object","properties":{"planId":{"type":"string","description":"Unique pricing plan identifier"},"providerId":{"type":"string","description":"Provider this plan belongs to"},"name":{"type":"string","description":"Display name of the plan"},"description":{"type":"string","description":"Plan description"},"unlockFee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"One-time unlock fee"}]},"perMinuteRate":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Per-minute rate"}]},"perKmRate":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Per-kilometer rate"}]},"currency":{"type":"string","example":"EUR","description":"ISO 4217 currency code"},"taxIncluded":{"type":"boolean","default":true,"description":"Whether prices include tax"},"validFrom":{"type":"string","format":"date-time","description":"Plan validity start"},"validUntil":{"type":"string","format":"date-time","description":"Plan validity end"}},"required":["planId","providerId","name","unlockFee","perMinuteRate","currency"],"description":"Detailed pricing plan information"},"ProviderSummary":{"type":"object","properties":{"providerId":{"type":"string","example":"dott-stuttgart","description":"Provider identifier (slug format)"},"providerName":{"type":"string","example":"Dott Stuttgart","description":"Provider display name"},"vehicleCount":{"type":"number","example":15,"description":"Number of vehicles from this provider"},"error":{"type":"string","description":"Error message if provider had issues"}},"required":["providerId","providerName","vehicleCount"],"description":"Summary of results from a provider"},"MicroMobilitySearchRequest":{"type":"object","properties":{"location":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"example":48.7758,"description":"Search center latitude"},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":9.1829,"description":"Search center longitude"}},"required":["latitude","longitude"]},"radiusMeters":{"type":"number","exclusiveMinimum":0,"maximum":5000,"example":500,"description":"Search radius in meters (default: 500, max: 5000)"},"vehicleTypes":{"type":"array","items":{"$ref":"#/components/schemas/MicroMobilityVehicleType"},"example":["SCOOTER","BICYCLE"],"description":"Filter by vehicle types"},"providers":{"type":"array","items":{"type":"string"},"example":["dott-stuttgart"],"description":"Filter by provider IDs"},"minBatteryPercent":{"type":"number","minimum":0,"maximum":100,"example":20,"description":"Minimum battery level"},"minRangeMeters":{"type":"number","exclusiveMinimum":0,"example":5000,"description":"Minimum remaining range in meters"},"limit":{"type":"number","exclusiveMinimum":0,"maximum":100,"example":20,"description":"Maximum results to return (default: 20, max: 100)"},"cursor":{"type":"string","example":"eyJvZmZzZXQiOjIwfQ==","description":"Pagination cursor from previous response. Use to fetch the next page of results."}},"required":["location"],"description":"Request to search for micro mobility vehicles"},"MicroMobilitySearchResult":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/MicroMobilityVehicle"},"description":"Found vehicles from all providers, sorted by distance from search location"},"searchLocation":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]},"searchRadius":{"type":"number","description":"Actual search radius used"},"lastUpdated":{"type":"string","format":"date-time","description":"When vehicle data was last fetched"},"providersSummary":{"type":"array","items":{"$ref":"#/components/schemas/ProviderSummary"},"description":"Summary of results per provider"},"pagination":{"allOf":[{"$ref":"#/components/schemas/CursorPaginationMeta"},{"description":"Cursor-based pagination information"}]}},"required":["results","searchLocation","searchRadius","lastUpdated","providersSummary","pagination"],"description":"Search result data with vehicles from all configured providers"},"ZoneRules":{"type":"object","properties":{"maxSpeedKmh":{"type":"number","description":"Maximum speed in km/h"},"rideAllowed":{"type":"boolean","default":true,"description":"Whether riding is allowed"},"parkingAllowed":{"type":"boolean","default":true,"description":"Whether parking is allowed"},"message":{"type":"string","description":"User-facing message about this zone"}},"description":"Rules that apply within a zone"},"Zone":{"type":"object","properties":{"zoneId":{"type":"string","description":"Unique zone identifier"},"providerId":{"type":"string","description":"Provider this zone belongs to"},"name":{"type":"string","description":"Human-readable zone name"},"type":{"allOf":[{"$ref":"#/components/schemas/ZoneType"},{"description":"Zone type"}]},"geometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"]}],"description":"Zone boundary as GeoJSON"},"rules":{"allOf":[{"$ref":"#/components/schemas/ZoneRules"},{"description":"Rules that apply in this zone"}]}},"required":["zoneId","providerId","name","type","geometry","rules"],"description":"Geofencing zone definition"},"PTTransportMode":{"type":"string","enum":["SUBWAY","TRAM","BUS","TRAIN","SUBURBAN_RAIL","HIGH_SPEED_RAIL","FERRY","CABLE_CAR","FUNICULAR","ON_DEMAND","WALK"],"description":"Public transport mode","example":"TRAIN"},"PTAccessibilityFeature":{"type":"string","enum":["WHEELCHAIR_ACCESSIBLE","LOW_FLOOR","RAMP_AVAILABLE","ELEVATOR","STEP_FREE","AUDIO_ANNOUNCEMENTS","VISUAL_DISPLAYS","TACTILE_GUIDANCE","STROLLER_SPACE","BICYCLE_ALLOWED"],"description":"Accessibility feature available on vehicles or stops","example":"WHEELCHAIR_ACCESSIBLE"},"PTRealTimeStatus":{"type":"string","enum":["ON_TIME","EARLY","SLIGHTLY_DELAYED","DELAYED","CANCELLED","PARTIALLY_CANCELLED","NO_DATA"],"description":"Real-time status of journey or leg","example":"ON_TIME"},"PTTicketType":{"type":"string","enum":["SINGLE","DAY_PASS","MULTI_TRIP","WEEKLY_PASS","MONTHLY_PASS","GROUP_TICKET","FIRST_CLASS","BICYCLE_TICKET"],"description":"Type of public transport ticket","example":"SINGLE"},"PTBookingStatus":{"type":"string","enum":["PENDING","CONFIRMED","USED","CANCELLED","EXPIRED","FAILED"],"description":"Status of a public transport booking","example":"CONFIRMED"},"PTSortBy":{"type":"string","enum":["DEPARTURE_TIME","ARRIVAL_TIME","DURATION","TRANSFERS","PRICE"],"description":"Sorting options for journey search results","example":"DEPARTURE_TIME"},"PTWarningCode":{"type":"string","enum":["DELAY","CANCELLATION","PLATFORM_CHANGE","ROUTE_DEVIATION","SERVICE_DISRUPTION","ACCESSIBILITY_LIMITED","ELEVATOR_OUT_OF_SERVICE","ESCALATOR_OUT_OF_SERVICE","SHORT_TRANSFER_TIME","TRANSFER_NOT_GUARANTEED","LAST_CONNECTION","ALTERNATIVE_ROUTE","LIMITED_AVAILABILITY","PRICE_CHANGE","BOOKING_REQUIRED","PARTIAL_RESULTS","DATA_OUTDATED"],"description":"Warning code specific to public transport","example":"DELAY"},"PTWarning":{"type":"object","properties":{"code":{"allOf":[{"$ref":"#/components/schemas/PTWarningCode"},{"description":"Warning code"}]},"severity":{"allOf":[{"$ref":"#/components/schemas/WarningSeverity"},{"description":"Severity level"}]},"message":{"type":"string","description":"Human-readable warning message","example":"Train is delayed by 10 minutes"},"affectedLegIndex":{"type":"integer","description":"Index of affected leg (if leg-specific)","example":0}},"required":["code","severity","message"],"description":"Public transport warning or notice"},"TransportMode":{"type":"string","enum":["SUBWAY","TRAM","BUS","TRAIN","SUBURBAN_RAIL","HIGH_SPEED_RAIL","FERRY","CABLE_CAR","FUNICULAR","ON_DEMAND","WALK"],"description":"Public transport mode","example":"TRAIN"},"AccessibilityFeature":{"type":"string","enum":["WHEELCHAIR_ACCESSIBLE","LOW_FLOOR","RAMP_AVAILABLE","ELEVATOR","STEP_FREE","AUDIO_ANNOUNCEMENTS","VISUAL_DISPLAYS","TACTILE_GUIDANCE","STROLLER_SPACE","BICYCLE_ALLOWED"],"description":"Accessibility feature available on vehicles or stops","example":"WHEELCHAIR_ACCESSIBLE"},"PTStop":{"type":"object","properties":{"id":{"type":"string","description":"Stop identifier","example":"de:08111:6115"},"name":{"type":"string","description":"Stop name","example":"Stuttgart Hauptbahnhof"},"coordinates":{"$ref":"#/components/schemas/Coordinates"},"platform":{"type":"string","description":"Platform/track/bay information","example":"Gleis 5"},"locality":{"type":"string","description":"City or locality","example":"Stuttgart"},"transportModes":{"type":"array","items":{"$ref":"#/components/schemas/TransportMode"},"description":"Available transport modes","example":["TRAIN","SUBURBAN_RAIL"]},"accessibility":{"type":"array","items":{"$ref":"#/components/schemas/AccessibilityFeature"},"description":"Accessibility features"}},"required":["id","name"],"description":"Public transport stop information"},"RealTimeStatus":{"type":"string","enum":["ON_TIME","EARLY","SLIGHTLY_DELAYED","DELAYED","CANCELLED","PARTIALLY_CANCELLED","NO_DATA"],"description":"Current status","example":"ON_TIME"},"PTRealTimeInfo":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/RealTimeStatus"},"delayMinutes":{"type":"integer","description":"Delay in minutes (negative for early)","example":5},"scheduledDepartureAt":{"type":"string","format":"date-time","description":"Originally scheduled departure datetime","example":"2025-01-15T14:30:00Z"},"actualDepartureAt":{"type":"string","format":"date-time","description":"Actual/predicted datetime of departure","example":"2025-01-15T14:35:00Z"},"platform":{"type":"string","description":"Current platform (may differ from scheduled)","example":"Gleis 7"},"message":{"type":"string","description":"Additional real-time message","example":"Verspätung wegen Bauarbeiten"}},"required":["status"],"description":"Real-time status information"},"PTCO2Comparison":{"type":"object","properties":{"emissionsGrams":{"type":"number","description":"CO2 emissions in grams for this journey","example":1200},"carEmissionsGrams":{"type":"number","description":"Equivalent car journey emissions in grams","example":8500},"savingsPercent":{"type":"number","description":"Percentage of CO2 saved compared to car","example":86}},"required":["emissionsGrams","carEmissionsGrams","savingsPercent"],"description":"CO2 emissions comparison with car travel"},"PTLineInfo":{"type":"object","properties":{"id":{"type":"string","description":"Line identifier","example":"vvs:S1"},"name":{"type":"string","description":"Line name/number","example":"S1"},"direction":{"type":"string","description":"Direction/terminus","example":"Herrenberg"},"operator":{"type":"string","description":"Operating company","example":"S-Bahn Stuttgart"},"color":{"type":"string","description":"Line color (hex)","example":"#4CAF50"},"textColor":{"type":"string","description":"Text color (hex)","example":"#FFFFFF"}},"required":["id","name"],"description":"Transit line information"},"TicketType":{"type":"string","enum":["SINGLE","DAY_PASS","MULTI_TRIP","WEEKLY_PASS","MONTHLY_PASS","GROUP_TICKET","FIRST_CLASS","BICYCLE_TICKET"],"description":"Type of ticket","example":"SINGLE"},"PTTicketOption":{"type":"object","properties":{"ticketType":{"$ref":"#/components/schemas/TicketType"},"name":{"type":"string","description":"Display name","example":"Einzelfahrschein"},"description":{"type":"string","description":"Description","example":"Gültig für eine einfache Fahrt"},"price":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Price for this ticket option"}]},"isRefundable":{"type":"boolean","description":"Whether ticket can be refunded"},"isChangeable":{"type":"boolean","description":"Whether travel time can be changed"},"validityMinutes":{"type":"integer","description":"How long ticket is valid (minutes)","example":120}},"required":["ticketType","name","price"],"description":"Available ticket option for booking"},"DateTimeType":{"type":"string","enum":["DEPARTURE","ARRIVAL"],"description":"Whether this is departure or arrival time","example":"DEPARTURE"},"TravelDateTime":{"type":"object","properties":{"dateTime":{"type":"string","format":"date-time","description":"Date and time in ISO 8601 format","example":"2025-01-15T14:30:00Z"},"type":{"$ref":"#/components/schemas/DateTimeType"}},"required":["dateTime","type"],"description":"Travel date/time with departure/arrival indicator"},"Travelers":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"default":1,"description":"Number of adult travelers","example":1},"children":{"type":"integer","minimum":0,"default":0,"description":"Number of children (typically 6-14)","example":0},"infants":{"type":"integer","minimum":0,"default":0,"description":"Number of infants (typically 0-5)","example":0},"seniors":{"type":"integer","minimum":0,"default":0,"description":"Number of seniors","example":0},"bicycles":{"type":"integer","minimum":0,"default":0,"description":"Number of bicycles to transport","example":0}},"description":"Traveler count information"},"JourneySearchFilters":{"type":"object","properties":{"transportModes":{"type":"array","items":{"$ref":"#/components/schemas/TransportMode"},"description":"Include only these transport modes","example":["TRAIN","SUBURBAN_RAIL","BUS"]},"excludedModes":{"type":"array","items":{"$ref":"#/components/schemas/TransportMode"},"description":"Exclude these transport modes","example":["FERRY"]},"maxTransfers":{"type":"integer","minimum":0,"maximum":10,"description":"Maximum number of transfers","example":2},"minTransferTime":{"type":"integer","minimum":0,"maximum":60,"description":"Minimum transfer time in minutes","example":5},"maxWalkingDistance":{"type":"integer","minimum":0,"maximum":5000,"description":"Maximum walking distance in meters","example":1000},"accessibility":{"type":"array","items":{"$ref":"#/components/schemas/AccessibilityFeature"},"description":"Required accessibility features","example":["WHEELCHAIR_ACCESSIBLE"]},"directOnly":{"type":"boolean","description":"Only return direct connections (no transfers)","example":false},"bicycleTransport":{"type":"boolean","description":"Journey must allow bicycle transport","example":false}},"description":"Filters for journey search"},"JourneySearchRequest":{"type":"object","properties":{"origin":{"oneOf":[{"$ref":"#/components/schemas/CoordinateSearch"},{"$ref":"#/components/schemas/AddressSearch"},{"$ref":"#/components/schemas/PlaceIdSearch"}],"discriminator":{"propertyName":"type","mapping":{"coordinates":"#/components/schemas/CoordinateSearch","address":"#/components/schemas/AddressSearch","place":"#/components/schemas/PlaceIdSearch"}},"description":"Origin location (coordinates, address, or stop ID from stops search)","example":{"type":"place","placeId":"p_8f3d9a2b"}},"destination":{"oneOf":[{"$ref":"#/components/schemas/CoordinateSearch"},{"$ref":"#/components/schemas/AddressSearch"},{"$ref":"#/components/schemas/PlaceIdSearch"}],"discriminator":{"propertyName":"type","mapping":{"coordinates":"#/components/schemas/CoordinateSearch","address":"#/components/schemas/AddressSearch","place":"#/components/schemas/PlaceIdSearch"}},"description":"Destination location (coordinates, address, or stop ID from stops search)","example":{"type":"address","address":"Stuttgart Flughafen"}},"dateTime":{"allOf":[{"$ref":"#/components/schemas/TravelDateTime"},{"description":"Travel date/time"}]},"travelers":{"allOf":[{"$ref":"#/components/schemas/Travelers"},{"description":"Traveler information"}]},"filters":{"allOf":[{"$ref":"#/components/schemas/JourneySearchFilters"},{"description":"Optional journey filters"}]},"sortBy":{"allOf":[{"$ref":"#/components/schemas/PTSortBy"},{"description":"Sort order for results (default: DEPARTURE_TIME)"}]},"cursor":{"type":"string","description":"Pagination cursor from previous response","example":"eyJ0eXAiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..example"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":50,"description":"Number of results (default: 10, max: 50)","example":10}},"required":["origin","destination","dateTime"],"description":"Journey search request parameters"},"LineInfo":{"type":"object","properties":{"id":{"type":"string","description":"Line identifier","example":"vvs:S1"},"name":{"type":"string","description":"Line name/number","example":"S1"},"direction":{"type":"string","description":"Direction/terminus","example":"Herrenberg"},"operator":{"type":"string","description":"Operating company","example":"S-Bahn Stuttgart"},"color":{"type":"string","description":"Line color (hex)","example":"#4CAF50"},"textColor":{"type":"string","description":"Text color (hex)","example":"#FFFFFF"}},"required":["id","name"],"description":"Line information (not present for walking legs)"},"RealTimeInfo":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/RealTimeStatus"},"delayMinutes":{"type":"integer","description":"Delay in minutes (negative for early)","example":5},"scheduledDepartureAt":{"type":"string","format":"date-time","description":"Originally scheduled departure datetime","example":"2025-01-15T14:30:00Z"},"actualDepartureAt":{"type":"string","format":"date-time","description":"Actual/predicted datetime of departure","example":"2025-01-15T14:35:00Z"},"platform":{"type":"string","description":"Current platform (may differ from scheduled)","example":"Gleis 7"},"message":{"type":"string","description":"Additional real-time message","example":"Verspätung wegen Bauarbeiten"}},"required":["status"],"description":"Real-time information for this leg"},"JourneyLeg":{"type":"object","properties":{"legIndex":{"type":"integer","description":"Zero-based index of this leg in the journey","example":0},"mode":{"allOf":[{"$ref":"#/components/schemas/TransportMode"},{"description":"Transport mode for this leg"}]},"line":{"$ref":"#/components/schemas/LineInfo"},"origin":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Departure stop"}]},"destination":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Arrival stop"}]},"departure":{"type":"string","format":"date-time","description":"Scheduled departure time","example":"2025-01-15T14:30:00Z"},"arrival":{"type":"string","format":"date-time","description":"Scheduled arrival time","example":"2025-01-15T14:45:00Z"},"durationMinutes":{"type":"integer","description":"Duration in minutes","example":15},"distanceMeters":{"type":"integer","description":"Distance in meters","example":5200},"realTime":{"$ref":"#/components/schemas/RealTimeInfo"},"accessibility":{"type":"array","items":{"$ref":"#/components/schemas/AccessibilityFeature"},"description":"Accessibility features on this leg"},"remarks":{"type":"array","items":{"type":"string"},"description":"Additional remarks or notices"}},"required":["legIndex","mode","origin","destination","departure","arrival","durationMinutes"],"description":"Single leg/segment of a journey"},"CO2Comparison":{"type":"object","properties":{"emissionsGrams":{"type":"number","description":"CO2 emissions in grams for this journey","example":1200},"carEmissionsGrams":{"type":"number","description":"Equivalent car journey emissions in grams","example":8500},"savingsPercent":{"type":"number","description":"Percentage of CO2 saved compared to car","example":86}},"required":["emissionsGrams","carEmissionsGrams","savingsPercent"],"description":"CO2 comparison with car travel"},"PTDeepLinks":{"type":"object","properties":{"android":{"type":"string","format":"uri","example":"https://play.google.com/store/apps/details?id=de.vvs"},"ios":{"type":"string","format":"uri","example":"https://apps.apple.com/app/vvs/id123456"},"web":{"type":"string","format":"uri","example":"https://www.vvs.de/tickets"}},"description":"Deep links to provider app/website for booking"},"PTProviderDisplay":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","description":"URL to provider logo","example":"https://cdn.adapt2move.de/providers/vvs.svg"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"},"supportEmail":{"type":"string","format":"email","description":"Support email address","example":"info@vvs.de"},"supportPhone":{"type":"string","description":"Support phone number","example":"+49 711 19449"},"deepLinks":{"$ref":"#/components/schemas/PTDeepLinks"}},"required":["id","name","logoUrl"],"description":"Transport provider information"},"Journey":{"type":"object","properties":{"journeyToken":{"type":"string","description":"Encrypted journey token (use for details/booking)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6..."},"origin":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Journey origin"}]},"destination":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Journey destination"}]},"departure":{"type":"string","format":"date-time","description":"Departure time from origin","example":"2025-01-15T14:30:00Z"},"arrival":{"type":"string","format":"date-time","description":"Arrival time at destination","example":"2025-01-15T15:45:00Z"},"durationMinutes":{"type":"integer","description":"Total journey duration in minutes","example":75},"transfers":{"type":"integer","description":"Number of transfers/changes","example":1},"legs":{"type":"array","items":{"$ref":"#/components/schemas/JourneyLeg"},"description":"Journey legs"},"price":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Indicative price (if available)"}]},"co2Comparison":{"$ref":"#/components/schemas/CO2Comparison"},"realTimeStatus":{"allOf":[{"$ref":"#/components/schemas/RealTimeInfo"},{"description":"Overall journey real-time status"}]},"accessibility":{"type":"array","items":{"$ref":"#/components/schemas/AccessibilityFeature"},"description":"Accessibility features available throughout journey"},"isBookable":{"type":"boolean","description":"Whether this journey can be booked through the provider","example":false},"usableUntil":{"type":"string","format":"date-time","description":"When this journey token expires","example":"2025-01-15T14:00:00Z"},"provider":{"$ref":"#/components/schemas/PTProviderDisplay"}},"required":["journeyToken","origin","destination","departure","arrival","durationMinutes","transfers","legs","isBookable","provider"],"description":"Complete public transport journey"},"JourneySearchResponseData":{"type":"object","properties":{"journeys":{"type":"array","items":{"$ref":"#/components/schemas/Journey"},"description":"List of journey options"},"pagination":{"type":"object","properties":{"earlierCursor":{"type":"string","description":"Cursor for fetching earlier journeys","example":"ZWFybGllci1jdXJzb3I="},"laterCursor":{"type":"string","description":"Cursor for fetching later journeys","example":"bGF0ZXItY3Vyc29y"},"hasEarlier":{"type":"boolean","description":"Whether earlier journeys are available","example":true},"hasLater":{"type":"boolean","description":"Whether later journeys are available","example":true}},"required":["hasEarlier","hasLater"],"description":"Pagination information"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PTWarning"},"description":"Search-level warnings"}},"required":["journeys","pagination"],"description":"Journey search response data"},"IntermediateStop":{"type":"object","properties":{"stop":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Stop information"}]},"arrivalAt":{"type":"string","format":"date-time","description":"Scheduled arrival time","example":"2025-01-15T14:35:00Z"},"departureAt":{"type":"string","format":"date-time","description":"Scheduled departure time","example":"2025-01-15T14:36:00Z"},"realTime":{"type":"object","properties":{"arrivalDelay":{"type":"integer","description":"Arrival delay in minutes","example":2},"departureDelay":{"type":"integer","description":"Departure delay in minutes","example":3},"platform":{"type":"string","description":"Actual platform","example":"Gleis 3"},"isCancelled":{"type":"boolean","description":"Stop is cancelled/skipped"}},"description":"Real-time information for this stop"}},"required":["stop"],"description":"Intermediate stop with real-time data"},"DetailedJourneyLeg":{"type":"object","properties":{"legIndex":{"type":"integer","description":"Zero-based index of this leg","example":0},"mode":{"allOf":[{"$ref":"#/components/schemas/TransportMode"},{"description":"Transport mode"}]},"line":{"allOf":[{"$ref":"#/components/schemas/LineInfo"},{"description":"Line information"}]},"origin":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Departure stop"}]},"destination":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Arrival stop"}]},"departureAt":{"type":"string","format":"date-time","description":"Scheduled departure time","example":"2025-01-15T14:30:00Z"},"arrivalAt":{"type":"string","format":"date-time","description":"Scheduled arrival time","example":"2025-01-15T15:00:00Z"},"durationMinutes":{"type":"integer","description":"Duration in minutes","example":30},"distanceMeters":{"type":"integer","description":"Distance in meters"},"realTime":{"allOf":[{"$ref":"#/components/schemas/RealTimeInfo"},{"description":"Real-time information"}]},"accessibility":{"type":"array","items":{"$ref":"#/components/schemas/AccessibilityFeature"},"description":"Accessibility features"},"intermediateStops":{"type":"array","items":{"$ref":"#/components/schemas/IntermediateStop"},"description":"All intermediate stops with real-time data"},"vehicleInfo":{"type":"object","properties":{"vehicleType":{"type":"string","description":"Vehicle type","example":"Triebwagen ET 430"},"vehicleNumber":{"type":"string","description":"Vehicle/train number","example":"S1 23456"},"amenities":{"type":"array","items":{"type":"string"},"description":"Available amenities","example":["WiFi","Steckdosen","Klimaanlage"]},"occupancy":{"type":"string","enum":["LOW","MEDIUM","HIGH","VERY_HIGH","UNKNOWN"],"description":"Expected occupancy level","example":"MEDIUM"}},"description":"Vehicle information"},"serviceAlerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Alert ID"},"title":{"type":"string","description":"Alert title","example":"Bauarbeiten"},"description":{"type":"string","description":"Alert description","example":"Wegen Bauarbeiten kann es zu Verspätungen kommen."},"url":{"type":"string","format":"uri","description":"More information URL"}},"required":["id","title","description"]},"description":"Service alerts affecting this leg"},"remarks":{"type":"array","items":{"type":"string"},"description":"Additional remarks"}},"required":["legIndex","mode","origin","destination","departureAt","arrivalAt","durationMinutes","intermediateStops"],"description":"Detailed journey leg with all intermediate stops"},"TicketOption":{"type":"object","properties":{"ticketType":{"$ref":"#/components/schemas/TicketType"},"name":{"type":"string","description":"Display name","example":"Einzelfahrschein"},"description":{"type":"string","description":"Description","example":"Gültig für eine einfache Fahrt"},"price":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Price for this ticket option"}]},"isRefundable":{"type":"boolean","description":"Whether ticket can be refunded"},"isChangeable":{"type":"boolean","description":"Whether travel time can be changed"},"validityMinutes":{"type":"integer","description":"How long ticket is valid (minutes)","example":120}},"required":["ticketType","name","price"],"description":"Available ticket option for booking"},"DetailedJourney":{"type":"object","properties":{"journeyToken":{"type":"string","description":"Journey token (for booking)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6..."},"origin":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Journey origin"}]},"destination":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Journey destination"}]},"departureAt":{"type":"string","format":"date-time","description":"Departure time","example":"2025-01-15T14:30:00Z"},"arrivalAt":{"type":"string","format":"date-time","description":"Arrival time","example":"2025-01-15T15:45:00Z"},"durationMinutes":{"type":"integer","description":"Total duration in minutes","example":75},"transfers":{"type":"integer","description":"Number of transfers","example":1},"legs":{"type":"array","items":{"$ref":"#/components/schemas/DetailedJourneyLeg"},"description":"Detailed journey legs"},"ticketOptions":{"type":"array","items":{"$ref":"#/components/schemas/TicketOption"},"description":"Available ticket options for booking"},"co2Comparison":{"allOf":[{"$ref":"#/components/schemas/CO2Comparison"},{"description":"CO2 comparison"}]},"accessibility":{"type":"array","items":{"$ref":"#/components/schemas/AccessibilityFeature"},"description":"Accessibility features"},"accessibilityNotes":{"type":"array","items":{"type":"string"},"description":"Additional accessibility information","example":["Aufzug am Hauptbahnhof außer Betrieb"]},"isBookable":{"type":"boolean","description":"Whether journey can be booked","example":false},"bookableUntil":{"type":"string","format":"date-time","description":"Deadline for booking","example":"2025-01-15T14:00:00Z"},"validUntil":{"type":"string","format":"date-time","description":"When this information expires","example":"2025-01-15T14:25:00Z"},"fareZones":{"type":"array","items":{"type":"string"},"description":"Fare zones traversed","example":["Zone 1","Zone 2"]},"tariffDescription":{"type":"string","description":"Description of applicable tariff","example":"VVS Tarif - 2 Zonen"},"remarks":{"type":"array","items":{"type":"string"},"description":"Journey-level remarks"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PTWarning"},"description":"Warnings and alerts"},"provider":{"$ref":"#/components/schemas/PTProviderDisplay"}},"required":["journeyToken","origin","destination","departureAt","arrivalAt","durationMinutes","transfers","legs","isBookable","provider"],"description":"Complete detailed journey information"},"JourneyDetailsRequest":{"type":"object","properties":{"journeyToken":{"type":"string","description":"Journey token from search results","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6..."}},"required":["journeyToken"],"description":"Request for detailed journey information"},"StopSearchResult":{"type":"object","properties":{"id":{"type":"string","description":"Stop identifier","example":"de:08111:6115"},"placeId":{"type":"string","description":"Place ID for use in journey search","example":"p_8f3d9a2b"},"name":{"type":"string","description":"Stop name","example":"Stuttgart Hauptbahnhof"},"coordinates":{"$ref":"#/components/schemas/Coordinates"},"locality":{"type":"string","description":"City or locality","example":"Stuttgart"},"transportModes":{"type":"array","items":{"$ref":"#/components/schemas/TransportMode"},"description":"Available transport modes","example":["TRAIN","SUBURBAN_RAIL","SUBWAY","BUS"]},"accessibility":{"type":"array","items":{"$ref":"#/components/schemas/AccessibilityFeature"},"description":"Accessibility features","example":["WHEELCHAIR_ACCESSIBLE","ELEVATOR"]},"parentStation":{"type":"object","properties":{"id":{"type":"string","description":"Parent station ID"},"name":{"type":"string","description":"Parent station name"}},"required":["id","name"],"description":"Parent station (if this is a platform/bay)"},"distanceMeters":{"type":"integer","description":"Distance from search coordinates","example":150},"matchScore":{"type":"number","description":"Relevance score (for text search)"}},"required":["id","placeId","name","transportModes"],"description":"Single stop search result"},"StopSearchResponseData":{"type":"object","properties":{"stops":{"type":"array","items":{"$ref":"#/components/schemas/StopSearchResult"},"description":"List of stops"},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean","description":"Whether more results are available","example":false},"nextCursor":{"type":"string","description":"Cursor for the next page of results — present when hasMore is true"}},"required":["hasMore"],"description":"Pagination information"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PTWarning"},"description":"Search-level warnings"}},"required":["stops","pagination"],"description":"Stop search response data"},"DepartureInfo":{"type":"object","properties":{"tripRef":{"type":"string","description":"Reference to the trip (for trip details lookup)","example":"vvs:trip:123456"},"line":{"allOf":[{"$ref":"#/components/schemas/LineInfo"},{"description":"Line information"}]},"mode":{"allOf":[{"$ref":"#/components/schemas/TransportMode"},{"description":"Transport mode"}]},"destination":{"type":"string","description":"Final destination of this departure","example":"Herrenberg"},"scheduledDepartureAt":{"type":"string","format":"date-time","description":"Scheduled departure time","example":"2025-01-15T14:35:00Z"},"realTime":{"allOf":[{"$ref":"#/components/schemas/RealTimeInfo"},{"description":"Real-time status and updates"}]},"platform":{"type":"string","description":"Platform/track/bay number (e.g., Steig 3)","example":"3"}},"required":["line","mode","destination","scheduledDepartureAt"],"description":"Information about a single departure from a stop. Check realTime.status for cancellation status."},"DepartureStopInfo":{"type":"object","properties":{"id":{"type":"string","description":"Stop identifier","example":"de:08111:6115"},"name":{"type":"string","description":"Stop name","example":"Stuttgart Hauptbahnhof"}},"required":["id","name"],"description":"Simplified stop information in departure context"},"DepartureSearchResponseData":{"type":"object","properties":{"stop":{"allOf":[{"$ref":"#/components/schemas/DepartureStopInfo"},{"description":"Stop information"}]},"departures":{"type":"array","items":{"$ref":"#/components/schemas/DepartureInfo"},"description":"List of upcoming departures"},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean","description":"Whether more departures are available","example":false}},"required":["hasMore"],"description":"Pagination information"},"attribution":{"type":"string","description":"Attribution text (if required by data provider)","example":"Data provided by VVS"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PTWarning"},"description":"Search-level warnings"}},"required":["stop","departures","pagination"],"description":"Response data containing upcoming departures from a stop"},"TravelerInfo":{"type":"object","properties":{"fullName":{"type":"string","description":"Full name as it should appear on ticket","example":"Max Mustermann"},"email":{"type":"string","format":"email","description":"Contact email","example":"max@example.com"},"phone":{"type":"string","description":"Contact phone number","example":"+49151..."},"dateOfBirth":{"type":"string","format":"date","description":"Date of birth (for age-based pricing)","example":"1990-05-15"},"reductionCard":{"type":"object","properties":{"type":{"type":"string","description":"Reduction card type","example":"BahnCard 50"},"number":{"type":"string","description":"Card number"}},"required":["type"],"description":"Reduction/discount card"}},"required":["fullName"],"description":"Traveler information for booking"},"PTTravelerRequirement":{"type":"string","enum":["TRAVELER_NAME","TRAVELER_EMAIL","TRAVELER_PHONE","TRAVELER_DATE_OF_BIRTH","REDUCTION_CARD"],"description":"Information required for completing a booking","example":"TRAVELER_NAME"},"PTPrebookRequest":{"type":"object","properties":{"journeyToken":{"type":"string","description":"Journey token from search/details","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6..."},"ticketType":{"allOf":[{"$ref":"#/components/schemas/TicketType"},{"description":"Selected ticket type"}]},"travelers":{"type":"array","items":{"$ref":"#/components/schemas/TravelerInfo"},"minItems":1,"description":"Traveler information"}},"required":["journeyToken","ticketType","travelers"],"description":"Public transport prebooking request"},"TravelerRequirement":{"type":"string","enum":["TRAVELER_NAME","TRAVELER_EMAIL","TRAVELER_PHONE","TRAVELER_DATE_OF_BIRTH","REDUCTION_CARD"],"description":"Information required for completing a booking","example":"TRAVELER_NAME"},"PTPrebookResponseData":{"type":"object","properties":{"prebookedJourneyToken":{"type":"string","description":"Token for completing booking","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6..."},"ticketType":{"allOf":[{"$ref":"#/components/schemas/TicketType"},{"description":"Selected ticket type"}]},"travelers":{"type":"array","items":{"$ref":"#/components/schemas/TravelerInfo"},"description":"Traveler information"},"totalPrice":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Total price for all travelers"}]},"priceBreakdown":{"type":"array","items":{"type":"object","properties":{"travelerIndex":{"type":"integer","description":"Index of traveler"},"price":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Price for this traveler"}]},"description":{"type":"string","description":"Price description","example":"Erwachsener, 2 Zonen"}},"required":["travelerIndex","price"]},"description":"Price breakdown per traveler"},"reservedUntil":{"type":"string","format":"date-time","description":"Reservation expiry time","example":"2025-01-15T14:45:00Z"},"reservationSupported":{"type":"boolean","description":"Whether provider truly reserves the booking","example":true},"requiredInformation":{"type":"array","items":{"$ref":"#/components/schemas/TravelerRequirement"},"description":"Additional information needed for final booking"},"ticketOptions":{"type":"array","items":{"$ref":"#/components/schemas/TicketOption"},"description":"Available ticket upgrades"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PTWarning"},"description":"Prebooking warnings"}},"required":["prebookedJourneyToken","ticketType","travelers","totalPrice","reservedUntil","reservationSupported","requiredInformation"],"description":"Public transport prebooking response data"},"PTBookingRequest":{"type":"object","properties":{"journeyToken":{"type":"string","description":"Journey token (prebooked or original)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6..."},"ticketType":{"allOf":[{"$ref":"#/components/schemas/TicketType"},{"description":"Selected ticket type"}]},"travelers":{"type":"array","items":{"$ref":"#/components/schemas/TravelerInfo"},"minItems":1,"description":"Traveler information"},"paymentMethod":{"type":"string","description":"Payment method identifier"},"notes":{"type":"string","description":"Additional notes"}},"required":["journeyToken","ticketType","travelers"],"description":"Public transport booking request"},"PTTicket":{"type":"object","properties":{"ticketId":{"type":"string","description":"Unique ticket identifier","example":"TKT-123456"},"ticketType":{"$ref":"#/components/schemas/TicketType"},"travelerName":{"type":"string","description":"Name on ticket","example":"Max Mustermann"},"qrCode":{"type":"string","description":"QR code data for mobile ticket"},"barcode":{"type":"string","description":"Barcode data"},"pdfUrl":{"type":"string","format":"uri","description":"URL to download ticket PDF","example":"https://tickets.adapt2move.com/TKT-123456.pdf"},"validFrom":{"type":"string","format":"date-time","description":"Ticket validity start","example":"2025-01-15T14:30:00Z"},"validUntil":{"type":"string","format":"date-time","description":"Ticket validity end","example":"2025-01-15T16:30:00Z"},"fareZones":{"type":"array","items":{"type":"string"},"description":"Valid fare zones","example":["Zone 1","Zone 2"]}},"required":["ticketId","ticketType","travelerName","validFrom","validUntil"],"description":"Individual ticket information"},"PTBookingResponseData":{"type":"object","properties":{"bookingId":{"type":"string","description":"Unique booking identifier","example":"BK-PT-123456"},"status":{"allOf":[{"$ref":"#/components/schemas/PTBookingStatus"},{"description":"Booking status"}]},"confirmationNumber":{"type":"string","description":"Provider confirmation number","example":"VVS-2025-ABC123"},"origin":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Journey origin"}]},"destination":{"allOf":[{"$ref":"#/components/schemas/PTStop"},{"description":"Journey destination"}]},"departureAt":{"type":"string","format":"date-time","description":"Departure time","example":"2025-01-15T14:30:00Z"},"arrivalAt":{"type":"string","format":"date-time","description":"Arrival time","example":"2025-01-15T15:45:00Z"},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/PTTicket"},"description":"Issued tickets"},"totalPrice":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Total price charged"}]},"emailSentTo":{"type":"string","format":"email","description":"Email where confirmation was sent","example":"max@example.com"},"bookedAt":{"type":"string","format":"date-time","description":"Booking timestamp","example":"2025-01-15T14:00:00Z"},"cancellationPolicy":{"type":"object","properties":{"isRefundable":{"type":"boolean","description":"Whether booking can be cancelled for refund"},"refundableUntil":{"type":"string","format":"date-time","description":"Deadline for full refund"},"cancellationFee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Fee for cancellation"}]}},"required":["isRefundable"],"description":"Cancellation policy"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PTWarning"},"description":"Booking warnings"}},"required":["bookingId","status","origin","destination","departureAt","arrivalAt","tickets","totalPrice","bookedAt"],"description":"Public transport booking response data"},"PTCancelBookingRequest":{"type":"object","properties":{"bookingId":{"type":"string","description":"Booking ID to cancel","example":"BK-PT-123456"},"reason":{"type":"string","description":"Cancellation reason"}},"required":["bookingId"],"description":"Public transport booking cancellation request"},"PTCancelBookingResponseData":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether cancellation was successful"},"bookingId":{"type":"string","description":"Cancelled booking ID"},"refundAmount":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Amount to be refunded"}]},"cancellationFee":{"allOf":[{"$ref":"#/components/schemas/Price"},{"description":"Cancellation fee charged"}]},"message":{"type":"string","description":"Additional message"}},"required":["success","bookingId"],"description":"Public transport booking cancellation response data"},"TileResolution":{"type":"string","enum":["overview","summary","detailed"],"description":"Tile resolution level based on zoom:\n- **overview** (z0-12): Service areas (provider coverage zones)\n- **summary** (z13-15): Service areas + station/stop markers (no live data)\n- **detailed** (z16+): Individual vehicles/stations/stops with booking tokens","example":"detailed"},"TileSourceStatusValue":{"type":"string","enum":["OK","PARTIAL","ERROR","TIMEOUT"],"description":"Status of a data source fetch","example":"OK"},"TileSourceStatus":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/TileSourceStatusValue"},{"description":"Fetch result status"}]},"message":{"type":"string","example":"Provider timeout after 4000ms","description":"Error or warning message if status is not OK"},"fetchedAt":{"type":"string","format":"date-time","example":"2025-01-15T10:30:00Z","description":"When this source's data was fetched"},"cacheTtlSeconds":{"type":"integer","example":30,"description":"Cache TTL in seconds. Undefined = live data."},"dataAgeSeconds":{"type":"integer","example":5,"description":"Age of data in seconds (now - fetchedAt)"}},"required":["status","fetchedAt"],"description":"Status of a data source in the tile response"},"TileQuery":{"type":"object","properties":{"types":{"type":"string","example":"pt,micromobility,carsharing,carRental,ridesharing","description":"Comma-separated mobility types to include. Default: all types. Options: pt, micromobility, carsharing, carRental, ridesharing"},"stopIds":{"type":"string","example":"de:08111:6115,de:08111:6118","description":"Comma-separated stop IDs. When provided, only these stops are returned (disables bbox discovery)"},"transportModes":{"type":"string","example":"SUBURBAN_RAIL,BUS","description":"Comma-separated transport modes to filter PT departures"},"timeWindowMinutes":{"type":"integer","minimum":1,"maximum":120,"example":60,"description":"Time window for departures in minutes (default: 60, max: 120)"},"departuresPerStop":{"type":"integer","minimum":1,"maximum":20,"example":5,"description":"Max departures to return per stop (default: 5, max: 20)"},"maxStops":{"type":"integer","minimum":1,"maximum":20,"example":10,"description":"Max stops to return (default: 10, max: 20)"},"stationIds":{"type":"string","example":"station-123,station-456","description":"Comma-separated carsharing station IDs. When provided, only these stations are returned"},"vehicleTypes":{"type":"string","example":"SCOOTER,BICYCLE","description":"Comma-separated vehicle types to filter"},"minBatteryPercent":{"type":["number","null"],"minimum":0,"maximum":100,"example":20,"description":"Minimum battery level (0-100)"},"limit":{"type":"integer","minimum":1,"maximum":200,"example":100,"description":"Max vehicles/stations to return (default: 100, max: 200)"},"forceDetailed":{"type":"string","description":"Set to 'true' to force detailed resolution (with departures) at zoom levels 13-15. Requires z >= 13."},"debug":{"type":"string","description":"Set to 'true' to include spatial cache debug metadata in the response"}}},"TileServiceAreaGeometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["BoundingBox"]},"boundingBox":{"$ref":"#/components/schemas/BoundingBox"}},"required":["type","boundingBox"]},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"GeoJSON Polygon coordinates [[[lon, lat], ...]]"}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}},"description":"GeoJSON MultiPolygon coordinates [[[[lon, lat], ...]], ...]"}},"required":["type","coordinates"]}],"description":"Geometry of a service area, either as a bounding box or GeoJSON polygon/multi-polygon"},"TileMobilityType":{"type":"string","enum":["PT","MICROMOBILITY","CARSHARING","CAR_RENTAL","RIDESHARING"],"description":"Type of mobility service","example":"MICROMOBILITY"},"TileServiceArea":{"type":"object","properties":{"providerId":{"type":"string","example":"tier","description":"Provider identifier"},"providerName":{"type":"string","example":"TIER","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.de/providers/tier.svg","description":"Provider logo URL"},"mobilityType":{"$ref":"#/components/schemas/TileMobilityType"},"geometry":{"allOf":[{"$ref":"#/components/schemas/TileServiceAreaGeometry"},{"description":"Service area geometry (bounding box or GeoJSON polygon)"}]},"approximateCount":{"type":"integer","example":1250,"description":"Approximate number of vehicles/stations in this area"}},"required":["providerId","providerName","logoUrl","mobilityType","geometry"],"description":"A provider's service coverage area"},"TilePTDeparture":{"type":"object","properties":{"line":{"type":"string","example":"S1","description":"Line name/number"},"direction":{"type":"string","example":"Herrenberg","description":"Direction/terminus"},"mode":{"allOf":[{"$ref":"#/components/schemas/TransportMode"},{"description":"Transport mode"}]},"scheduledAt":{"type":"string","format":"date-time","example":"2025-01-15T10:30:00Z","description":"Scheduled departure time"},"expectedAt":{"type":"string","format":"date-time","example":"2025-01-15T10:35:00Z","description":"Expected/predicted departure time (if real-time data available)"},"delayMinutes":{"type":"integer","example":5,"description":"Delay in minutes (negative for early)"},"platform":{"type":"string","example":"Gleis 5","description":"Platform/track/bay"},"cancelled":{"type":"boolean","example":false,"description":"Whether this departure is cancelled"},"lineColor":{"type":"string","example":"#0066cc","description":"Line color from transit authority (if available)"}},"required":["line","direction","mode","scheduledAt"],"description":"A single departure from a stop"},"TilePTStop":{"type":"object","properties":{"stopId":{"type":"string","example":"de:08111:6115","description":"Stop identifier"},"name":{"type":"string","example":"Stuttgart Hauptbahnhof","description":"Stop name"},"coordinates":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Stop location"}]},"transportModes":{"type":"array","items":{"$ref":"#/components/schemas/TransportMode"},"description":"Transport modes available at this stop (e.g. BUS, TRAM, SUBURBAN_RAIL)"},"departures":{"type":"array","items":{"$ref":"#/components/schemas/TilePTDeparture"},"description":"Upcoming departures"}},"required":["stopId","name","coordinates","transportModes","departures"],"description":"A public transport stop with upcoming departures"},"TilePTProductType":{"type":"string","enum":["DEUTSCHLANDTICKET","MONTHLY_PASS","ANNUAL_PASS","DAY_PASS","JOB_TICKET","OTHER"],"description":"Type of subscription/ticket product","example":"DEUTSCHLANDTICKET"},"TilePricePeriod":{"type":"string","enum":["day","month","year"],"description":"Billing period","example":"month"},"TilePTProduct":{"type":"object","properties":{"productId":{"type":"string","example":"vvs-deutschlandticket","description":"Use with POST /public-transport/subscriptions"},"name":{"type":"string","example":"Deutschland-Ticket","description":"Product display name"},"type":{"$ref":"#/components/schemas/TilePTProductType"},"price":{"type":"object","properties":{"amount":{"type":"number","example":4900,"description":"Price in cents"},"currency":{"type":"string","example":"EUR","description":"Currency code"},"period":{"$ref":"#/components/schemas/TilePricePeriod"}},"required":["amount","currency","period"],"description":"Pricing information"},"validityArea":{"type":"string","example":"Germany-wide","description":"Area where the ticket is valid"},"description":{"type":"string","example":"Unlimited travel on local and regional public transport","description":"Product description"}},"required":["productId","name","type","price","validityArea"],"description":"A subscription/ticket product available in the area"},"TileVehicleType":{"type":"string","enum":["SCOOTER","BICYCLE","MOPED","CARGO_BICYCLE","OTHER"],"description":"Type of vehicle","example":"SCOOTER"},"TileMicromobilityVehicle":{"type":"object","properties":{"vehicleId":{"type":"string","example":"aeece12e-38c0-42c5-8a61-bbb70a5a69d3","description":"Unique vehicle identifier"},"vehicleToken":{"type":"string","example":"enc_v1_xyz...","description":"Encrypted token for vehicle actions (5 min validity)"},"coordinates":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Vehicle location"}]},"vehicleType":{"$ref":"#/components/schemas/TileVehicleType"},"batteryPercent":{"type":"number","minimum":0,"maximum":100,"example":85,"description":"Battery level (0-100)"},"providerId":{"type":"string","example":"tier","description":"Reference to provider in the providers map"},"estimatedRangeKm":{"type":"number","example":25,"description":"Estimated range in km (calculated from battery)"},"pricingHint":{"type":"string","example":"1€ + 0,25€/min","description":"Indicative pricing (static per provider)"},"bookingUrl":{"type":"string","format":"uri","example":"https://tier.app/open?lat=48.78&lng=9.18","description":"Resolved booking deep link"}},"required":["vehicleId","vehicleToken","coordinates","vehicleType","providerId"],"description":"A micromobility vehicle for map display with token for future actions"},"TileFuelType":{"type":"string","enum":["ELECTRIC","DIESEL","PETROL","HYBRID","PLUGIN_HYBRID","OTHER"],"description":"Fuel/energy type","example":"ELECTRIC"},"TileCarFeature":{"type":"string","enum":["AIR_CONDITIONING","GPS_NAVIGATION","BLUETOOTH","APPLE_CARPLAY","WINTER_TIRES","FOUR_WHEEL_DRIVE","CHILD_SEAT","ISOFIX"],"description":"Vehicle feature/equipment","example":"AIR_CONDITIONING"},"TileCarsharingAvailableVehicle":{"type":"object","properties":{"vehicleCategory":{"type":"string","example":"COMPACT","description":"Vehicle category (e.g., COMPACT, MIDSIZE)"},"offerToken":{"type":"string","example":"enc_v1_abc...","description":"Encrypted token for booking flow (15-30 min validity)"},"usableUntil":{"type":"string","format":"date-time","example":"2025-01-15T12:30:00Z","description":"When this offer expires"},"make":{"type":"string","example":"Mercedes-Benz","description":"Vehicle manufacturer"},"model":{"type":"string","example":"A-Class","description":"Vehicle model name"},"fuelType":{"$ref":"#/components/schemas/TileFuelType"},"seats":{"type":"integer","example":5,"description":"Number of passenger seats"},"features":{"type":"array","items":{"$ref":"#/components/schemas/TileCarFeature"},"example":["AIR_CONDITIONING","GPS_NAVIGATION","BLUETOOTH"],"description":"Vehicle features/equipment"},"imageUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.de/static/images/mercedes-benz-aclass-640x400","description":"Vehicle image URL"},"estimatedRangeKm":{"type":"number","example":250,"description":"Estimated range in km (electric/hybrid only)"},"pricingHint":{"type":"string","example":"ab 2,50€/h + 0,24€/km","description":"Indicative pricing"},"bookingUrl":{"type":"string","format":"uri","example":"https://buchen.stadtmobil.de/","description":"Booking link"},"licensePlate":{"type":"string","example":"S-SM 1234","description":"Vehicle license plate"}},"required":["vehicleCategory","offerToken","usableUntil"],"description":"An available vehicle at a carsharing station with booking token"},"TileCarsharingStation":{"type":"object","properties":{"stationId":{"type":"string","example":"sm-stuttgart-hbf","description":"Station identifier"},"name":{"type":"string","example":"Stuttgart Hauptbahnhof","description":"Station name"},"coordinates":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Station location"}]},"availableVehicles":{"type":"array","items":{"$ref":"#/components/schemas/TileCarsharingAvailableVehicle"},"description":"Available vehicles with booking tokens"},"providerId":{"type":"string","example":"stadtmobil-stuttgart","description":"Reference to provider in the providers map"},"availableCount":{"type":"integer","example":3,"description":"Number of currently available vehicles"},"totalCapacity":{"type":"integer","example":8,"description":"Total station capacity (if known)"}},"required":["stationId","name","coordinates","availableVehicles","providerId","availableCount"],"description":"A carsharing station for map display with booking tokens"},"TileCarRentalStation":{"type":"object","properties":{"stationId":{"type":"string","example":"sixt-stuttgart-hbf","description":"Station identifier"},"name":{"type":"string","example":"SIXT Stuttgart Hauptbahnhof","description":"Station name"},"coordinates":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Station location"}]},"providerId":{"type":"string","example":"sixt","description":"Reference to provider in the providers map"}},"required":["stationId","name","coordinates","providerId"],"description":"A car rental station for map display (location only)"},"TransportModeStyle":{"type":"object","properties":{"color":{"type":"string","example":"#009933","description":"Hex color for this transport mode"},"label":{"type":"string","example":"S-Bahn","description":"Display name"},"shortLabel":{"type":"string","example":"S","description":"Short label for compact UI"}},"required":["color","label","shortLabel"],"description":"Display style for a transport mode"},"TileProviderInfo":{"type":"object","properties":{"name":{"type":"string","example":"TIER","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.de/providers/tier.svg","description":"Provider logo URL (absent when no logo is available)"},"iconUrl":{"type":"string","example":"/logos/providers/tier-icon.svg","description":"Compact provider icon URL for map markers (falls back to logoUrl when absent)"},"brandColor":{"type":"string","example":"#00b0a0","description":"Primary brand color (hex) for UI accents"},"category":{"type":"string","enum":["MICROMOBILITY","CARSHARING","CAR_RENTAL","RIDESHARING"],"example":"MICROMOBILITY","description":"Mobility category of the provider"},"vehicleTypes":{"type":"array","items":{"type":"string"},"example":["SCOOTER","BICYCLE"],"description":"Vehicle types offered by this provider"},"deepLinkTemplate":{"type":"string","example":"https://tier.app/open?lat={lat}&lng={lng}","description":"URL template for booking deep links. Variables: {lat}, {lng}, {vehicleId}, {stationId}"}},"required":["name"],"description":"Provider branding information (without ID, as ID is the map key)"},"TileProvidersMap":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TileProviderInfo"},"description":"Provider information keyed by provider ID","example":{"tier":{"name":"TIER","logoUrl":"https://cdn.adapt2move.de/providers/tier.svg"}}},"TileRidesharingVehicle":{"type":"object","properties":{"model":{"type":"string","example":"VW ID.3","description":"Vehicle model"},"color":{"type":"string","example":"Blau","description":"Vehicle color"},"numberPlate":{"type":"string","example":"BB - LK - 42","description":"License plate"},"type":{"type":"string","enum":["FUEL","ELECTRIC","HYBRID","OTHER"],"example":"ELECTRIC","description":"Drive type"}},"required":["model","color","numberPlate","type"],"description":"Vehicle information"},"TileRidesharingDeparture":{"type":"object","properties":{"driverName":{"type":"string","example":"Miriam S.","description":"Driver display name"},"avatarUrl":{"type":"string","format":"uri","example":"https://testserver.ridebee.com/api/staticImages/1773658056719.png","description":"Driver avatar URL"},"vehicle":{"$ref":"#/components/schemas/TileRidesharingVehicle"},"destinationAddress":{"type":"string","example":"71116 Gärtringen, Deutschland","description":"Destination address"},"routeType":{"type":"string","enum":["FLEX","FIXED"],"example":"FLEX","description":"FLEX = flexible departure window, FIXED = fixed route with waypoints"},"earliestDeparture":{"type":"string","format":"date-time","example":"2026-04-01T13:15:00.000Z","description":"Earliest possible departure"},"latestDeparture":{"type":"string","format":"date-time","example":"2026-04-01T17:15:00.000Z","description":"Latest possible departure"},"seats":{"type":"integer","example":4,"description":"Number of available seats"},"distanceKm":{"type":"number","example":23.8,"description":"Distance in kilometers"},"durationMinutes":{"type":"integer","example":20,"description":"Estimated duration in minutes"},"deepLink":{"type":"string","format":"uri","example":"http://testserver.stuttgart-faehrt-mit.de/public/travelPattern/offer/6662ba8afb8daaaee35fe49e","description":"Link to ride offer"}},"required":["driverName","vehicle","destinationAddress","routeType","earliestDeparture","latestDeparture","seats","distanceKm","durationMinutes","deepLink"],"description":"A ridesharing departure for tile display"},"TileRidesharingStop":{"type":"object","properties":{"stopId":{"type":"string","example":"6662ba70fb8daaaee35fe483","description":"Stop identifier"},"name":{"type":"string","example":"HOME","description":"Stop name"},"coordinates":{"allOf":[{"$ref":"#/components/schemas/Coordinates"},{"description":"Stop location"}]},"address":{"type":"string","example":"71116 Gaertringen, Deutschland","description":"Formatted address"},"departures":{"type":"array","items":{"$ref":"#/components/schemas/TileRidesharingDeparture"},"description":"Upcoming ride offers"}},"required":["stopId","name","coordinates","address","departures"],"description":"A ridesharing stop with upcoming ride offers"},"TileData":{"type":"object","properties":{"tile":{"type":"object","properties":{"z":{"type":"integer","minimum":0,"maximum":22,"description":"Zoom level"},"x":{"type":"integer","minimum":0,"description":"Tile X coordinate"},"y":{"type":"integer","minimum":0,"description":"Tile Y coordinate"}},"required":["z","x","y"],"description":"Tile coordinates"},"boundingBox":{"allOf":[{"$ref":"#/components/schemas/BoundingBox"},{"description":"Geographic bounds of this tile"}]},"resolution":{"allOf":[{"$ref":"#/components/schemas/TileResolution"},{"description":"Resolution level based on zoom (overview z0-12, summary z13-15, detailed z16+)"}]},"serviceAreas":{"type":"array","items":{"$ref":"#/components/schemas/TileServiceArea"},"description":"Provider coverage areas (overview and summary resolution)"},"publicTransport":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/TileSourceStatus"},{"description":"Fetch status for PT data"}]},"stops":{"type":"array","items":{"$ref":"#/components/schemas/TilePTStop"},"description":"Stops with departures. At summary: stops with empty departures[]. At detailed: full departure data."},"availableProducts":{"type":"array","items":{"$ref":"#/components/schemas/TilePTProduct"},"description":"Subscription/ticket products available for the area (detailed only)"},"transportModeStyles":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TransportModeStyle"},"description":"Display styles per transport mode (colors, labels) — regional scheme"}},"required":["status","stops"],"description":"Public transport data (summary: stops only, detailed: stops + departures)"},"micromobility":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/TileSourceStatus"},{"description":"Fetch status for micromobility data"}]},"providers":{"$ref":"#/components/schemas/TileProvidersMap"},"vehicles":{"type":"array","items":{"$ref":"#/components/schemas/TileMicromobilityVehicle"},"description":"Available vehicles with tokens"},"totalAvailable":{"type":"integer","example":42,"description":"Total available vehicles in the area (may be > returned count)"}},"required":["status","providers","vehicles","totalAvailable"],"description":"Micromobility data (detailed only — summary uses service areas)"},"carsharing":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/TileSourceStatus"},{"description":"Fetch status for carsharing data"}]},"providers":{"$ref":"#/components/schemas/TileProvidersMap"},"availabilityWindow":{"type":"object","properties":{"from":{"type":"string","format":"date-time","example":"2025-01-15T10:10:00Z","description":"Availability window start (now + 10 min)"},"to":{"type":"string","format":"date-time","example":"2025-01-15T12:20:00Z","description":"Availability window end (now + 2h10min)"}},"required":["from","to"],"description":"The time window for which availability was checked (detailed only)"},"stations":{"type":"array","items":{"$ref":"#/components/schemas/TileCarsharingStation"},"description":"Stations. At summary: station markers with empty availableVehicles[]. At detailed: full vehicle offers."}},"required":["status","providers","stations"],"description":"Carsharing data (summary: station locations, detailed: stations + vehicle offers)"},"carRental":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/TileSourceStatus"},{"description":"Fetch status for car rental data"}]},"providers":{"$ref":"#/components/schemas/TileProvidersMap"},"stations":{"type":"array","items":{"$ref":"#/components/schemas/TileCarRentalStation"},"description":"Station locations (no availability - booking requires date selection)"}},"required":["status","providers","stations"],"description":"Car rental data (summary + detailed — already lightweight)"},"ridesharing":{"type":"object","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/TileSourceStatus"},{"description":"Fetch status for ridesharing data"}]},"stops":{"type":"array","items":{"$ref":"#/components/schemas/TileRidesharingStop"},"description":"Ridesharing stops with departure information"}},"required":["status","stops"],"description":"Ridesharing data (detailed only — stops with ride offers)"}},"required":["tile","boundingBox","resolution"],"description":"Mobility data for a single map tile with zoom-adaptive resolution.\n\n**Resolution Levels:**\n- **overview** (z0-12): Service areas showing provider coverage zones\n- **summary** (z13-15): Service areas + station/stop markers (static data, no live API calls)\n- **detailed** (z16+): Individual vehicles/stations/stops with booking tokens (live data)\n\nEach section has its own `status` field indicating success/failure.\nHTTP 200 is returned even with partial failures — check individual status fields.\nHTTP 503 is only returned if ALL requested sources fail."},"TileResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TileData"},"meta":{"allOf":[{"$ref":"#/components/schemas/Metadata"},{"description":"Response metadata"}]}},"required":["success","data","meta"],"description":"Successful tile response with mobility data"},"CarSearchRequest":{"type":"object","properties":{"pickup":{"oneOf":[{"$ref":"#/components/schemas/CoordinateSearch"},{"$ref":"#/components/schemas/AddressSearch"},{"$ref":"#/components/schemas/PlaceIdSearch"}],"discriminator":{"propertyName":"type","mapping":{"coordinates":"#/components/schemas/CoordinateSearch","address":"#/components/schemas/AddressSearch","place":"#/components/schemas/PlaceIdSearch"}},"description":"Pickup location (coordinates, address, or place ID from station search)","example":{"type":"address","address":"Stuttgart Flughafen"}},"dropoff":{"oneOf":[{"$ref":"#/components/schemas/CoordinateSearch"},{"$ref":"#/components/schemas/AddressSearch"},{"$ref":"#/components/schemas/PlaceIdSearch"}],"discriminator":{"propertyName":"type","mapping":{"coordinates":"#/components/schemas/CoordinateSearch","address":"#/components/schemas/AddressSearch","place":"#/components/schemas/PlaceIdSearch"}},"description":"Dropoff location (if different from pickup for one-way rentals)"},"dates":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Rental period","example":{"start":"2030-02-01T10:00:00Z","end":"2030-02-03T10:00:00Z"}},"estimatedKilometers":{"type":"integer","exclusiveMinimum":0,"example":500,"description":"Estimated trip distance in kilometers. When provided, enables detailed price breakdowns including fuel estimates."},"filters":{"allOf":[{"$ref":"#/components/schemas/CarFilters"},{"description":"Optional search filters"}]},"sortBy":{"allOf":[{"$ref":"#/components/schemas/SortBy"},{"description":"Sort order for results (default: RECOMMENDED)"}]},"cursor":{"type":"string","example":"eyJ0eXAiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..example","description":"Pagination cursor from previous response for fetching next page"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":100,"example":20,"description":"Number of results per page (default: 20, max: 100)"}},"required":["pickup","dates"],"additionalProperties":false,"description":"Car search request parameters"},"OfferDetailsRequest":{"type":"object","properties":{"offerToken":{"type":"string","minLength":1,"maxLength":4096,"example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"Offer token from search results. This token identifies the specific offer to retrieve details for."},"estimatedKilometers":{"type":"integer","exclusiveMinimum":0,"example":500,"description":"Estimated trip distance in kilometers for pricing calculation. If provided, this value takes precedence over any previously used value. Use this to refresh pricing with a new distance estimate."}},"required":["offerToken"],"additionalProperties":false,"description":"Request body for retrieving offer details"},"PrebookRequest":{"type":"object","properties":{"offerToken":{"type":"string","minLength":1,"maxLength":4096,"example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"Offer token from search results. This token identifies the specific offer to prebook and contains all necessary booking context."},"estimatedKilometers":{"type":"integer","exclusiveMinimum":0,"example":500,"description":"Estimated trip distance in kilometers for pricing calculation. If provided, this value takes precedence over any previously used value (tracked by offerToken). Use this to provide or refresh the distance estimate for accurate pricing."}},"required":["offerToken"],"additionalProperties":false,"description":"Request body for prebooking a car rental offer"},"JourneySearchResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/JourneySearchResponseData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Journey search response"},"JourneyDetailsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/DetailedJourney"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Detailed journey response"},"StopSearchResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/StopSearchResponseData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Stop search response"},"DepartureSearchResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/DepartureSearchResponseData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Departure search response"},"PTPrebookResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PTPrebookResponseData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Public transport prebooking response"},"PTBookingResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PTBookingResponseData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Public transport booking response"},"PTCancelBookingResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PTCancelBookingResponseData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Public transport booking cancellation response"}},"parameters":{}},"paths":{"/cars/stations":{"get":{"summary":"Search Car Rental Stations","description":"Search for car rental stations/locations where vehicles can be picked up or dropped off.\n\n⚠️ **IMPORTANT RATE LIMITING NOTICE:**\nThis endpoint is NOT designed for autocomplete search functionality. Each request counts towards your API rate limit. Using this endpoint for autocomplete can quickly exhaust your rate limit and result in unexpected service disruption.\n\n**Recommended Usage Flow:**\n1. User provides approximate location (address or coordinates)\n2. Call this endpoint ONCE to get nearby stations\n3. Present results to user for selection\n4. Use selected station's `placeId` in car search requests for better performance\n\n**Offer Counts:**\nWhen both `pickupDate` and `returnDate` query parameters are provided, the response includes estimated offer counts at each station. These counts are estimates and do not guarantee availability (because of internal caching strategies).","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","minimum":-90,"maximum":90,"example":48.6899,"description":"Latitude in decimal degrees (for coordinate search). Example: 48.6899 (Stuttgart Airport)"},"required":false,"description":"Latitude in decimal degrees (for coordinate search). Example: 48.6899 (Stuttgart Airport)","name":"latitude","in":"query"},{"schema":{"type":"number","minimum":-180,"maximum":180,"example":9.222,"description":"Longitude in decimal degrees (for coordinate search). Example: 9.222 (Stuttgart Airport)"},"required":false,"description":"Longitude in decimal degrees (for coordinate search). Example: 9.222 (Stuttgart Airport)","name":"longitude","in":"query"},{"schema":{"type":"string","description":"Human-readable address to search (will be geocoded internally). Example: \"Stuttgart Flughafen\""},"required":false,"description":"Human-readable address to search (will be geocoded internally). Example: \"Stuttgart Flughafen\"","name":"address","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":50000,"example":5000,"description":"Search radius in meters (max: 50km, ignored when walkingTimeMinutes is given) - only for coordinate/address search"},"required":false,"description":"Search radius in meters (max: 50km, ignored when walkingTimeMinutes is given) - only for coordinate/address search","name":"radiusMeters","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":60,"description":"Maximum walking time in minutes (alternative to radius) - only for coordinate/address search"},"required":false,"description":"Maximum walking time in minutes (alternative to radius) - only for coordinate/address search","name":"walkingTimeMinutes","in":"query"},{"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Southwest corner latitude (for bounding box search)"},"required":false,"description":"Southwest corner latitude (for bounding box search)","name":"swLatitude","in":"query"},{"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Southwest corner longitude (for bounding box search)"},"required":false,"description":"Southwest corner longitude (for bounding box search)","name":"swLongitude","in":"query"},{"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Northeast corner latitude (for bounding box search)"},"required":false,"description":"Northeast corner latitude (for bounding box search)","name":"neLatitude","in":"query"},{"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Northeast corner longitude (for bounding box search)"},"required":false,"description":"Northeast corner longitude (for bounding box search)","name":"neLongitude","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"Pickup date/time in ISO 8601 format. Must be in the future. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC. When provided with returnDate, response includes available offer counts per station."}]},"required":false,"description":"Pickup date/time in ISO 8601 format. Must be in the future. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC. When provided with returnDate, response includes available offer counts per station.","name":"pickupDate","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"Return date/time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC. Must be provided together with pickupDate for offer counts.","example":"2030-02-05T10:00:00Z"}]},"required":false,"description":"Return date/time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC. Must be provided together with pickupDate for offer counts.","name":"returnDate","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of provider IDs to filter results (optional, returns all providers if omitted). Example: 'sixt,enterprise'"},"required":false,"description":"Comma-separated list of provider IDs to filter results (optional, returns all providers if omitted). Example: 'sixt,enterprise'","name":"providers","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"description":"Pagination cursor from previous response","name":"cursor","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"description":"Number of results per page (default: 20, max: 100)"},"required":false,"description":"Number of results per page (default: 20, max: 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful station search returning available locations","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/StationSearchData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Successful station search response"}}}},"400":{"description":"Invalid request parameters (validation failed)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"invalid_location":{"summary":"Invalid Location Coordinates","value":{"success":false,"error":{"code":"INVALID_LOCATION","message":"Invalid coordinates: latitude must be between -90 and 90","details":{"field":"location.coordinates.latitude","value":95}},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}},"invalid_date_range":{"summary":"Invalid Date Range","value":{"success":false,"error":{"code":"INVALID_DATE_RANGE","message":"returnDate must be after pickupDate"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"rate_limit":{"summary":"Rate Limit Exceeded","value":{"success":false,"error":{"code":"RATE_LIMIT_EXCEEDED","message":"API rate limit exceeded. Please reduce request frequency and avoid using this endpoint for autocomplete functionality."},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}}}}}},"500":{"description":"Internal server error or service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/cars":{"post":{"summary":"Search Vehicles","description":"Search for available rental and car sharing vehicles based on location, dates, and optional filters. Returns a paginated list of offers with vehicle specifications and availability. Detailed price breakdowns are only included when estimatedKilometers is provided in the request.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Search parameters including pickup/dropoff location and rental period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarSearchRequest"},"examples":{"stuttgart_address":{"summary":"Stuttgart Airport (by address)","value":{"pickup":{"type":"address","address":"Stuttgart Flughafen"},"dates":{"start":"2030-02-01T10:00:00Z","end":"2030-02-03T10:00:00Z"},"limit":10}},"munich_coordinates":{"summary":"Munich Center (by coordinates)","value":{"pickup":{"type":"coordinates","coordinates":{"latitude":48.1351,"longitude":11.582},"radiusMeters":5000},"dates":{"start":"2030-02-01T10:00:00Z","end":"2030-02-03T10:00:00Z"},"estimatedKilometers":200,"limit":10}},"berlin_with_filters":{"summary":"Berlin (with price sorting)","value":{"pickup":{"type":"address","address":"Berlin Hauptbahnhof"},"dates":{"start":"2030-02-01T10:00:00Z","end":"2030-02-05T10:00:00Z"},"estimatedKilometers":500,"sortBy":"PRICE_LOW_TO_HIGH","limit":20}}}}}},"responses":{"200":{"description":"Successful search returning available vehicles","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CarSearchResult"},"meta":{"allOf":[{"$ref":"#/components/schemas/Metadata"},{"description":"Response metadata"}]}},"required":["success","data","meta"],"description":"Successful car search response"}}}},"400":{"description":"Invalid request parameters (validation failed)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error or service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"provider_timeout":{"summary":"Provider Service Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Search request timed out while connecting to car rental providers"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"service_unavailable":{"summary":"Service Temporarily Unavailable","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Car search service is temporarily unavailable due to maintenance"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_error":{"summary":"Provider Integration Error","value":{"success":false,"error":{"code":"PROVIDER_ERROR","message":"Unable to process search request due to provider system error"},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"internal_error":{"summary":"Internal Processing Error","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An internal error occurred while processing your search request"},"meta":{"requestId":"req_stu901vwx234-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}}},"/cars/offer":{"post":{"summary":"Get Offer Details","description":"Retrieve detailed information about a specific car rental or sharing offer, including complete vehicle specifications, provider details, rental policies, and terms and conditions.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferDetailsRequest"}}}},"responses":{"200":{"description":"Successful retrieval of offer details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/Vehicle"},"pickupLocation":{"$ref":"#/components/schemas/LocationDetails"},"dropoffLocation":{"$ref":"#/components/schemas/LocationDetails"},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"Date range for rental period"},"insurance":{"$ref":"#/components/schemas/InsuranceCoverage"},"refillPolicy":{"$ref":"#/components/schemas/RefillPolicy"},"mileageAllowance":{"$ref":"#/components/schemas/MileageAllowance"},"offerToken":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"Encrypted token for booking (single-use). Updates with each API call—always use latest. Valid until usableUntil timestamp. Required for prebook and booking operations."},"usableUntil":{"type":"string","format":"date-time","example":"2025-10-27T16:00:00Z","description":"Token expiration time (ISO 8601). After this, token becomes invalid—start new search. Typically 15-30 minutes from issuance."},"distanceFromSearch":{"type":"number","example":1500,"description":"Distance from search location in meters"},"provider":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.svg","description":"Provider logo URL (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider website URL"}},"required":["id","name"],"description":"Provider information"},"deepLinks":{"$ref":"#/components/schemas/DeepLinks"},"availableUpsells":{"type":"array","items":{"$ref":"#/components/schemas/UpsellSummary"},"example":[{"referenceCode":"GPS_DEVICE_01","category":"GPS_DEVICE","name":"Premium GPS Navigation System","description":"TomTom GO Premium with real-time traffic updates","availability":"BOOKABLE","hasPricing":true},{"referenceCode":"CHILD_SEAT_01","category":"CHILD_SEAT","name":"Child Safety Seat","availability":"BOOKABLE","hasPricing":true}],"description":"Summary of available upsells (optional extras, equipment, services). Shows basic info without pricing details. Use prebook endpoint to get complete upsell information with pricing."},"price":{"allOf":[{"$ref":"#/components/schemas/DetailedPrice"},{"description":"Detailed price breakdown with categorized costs"}]},"pickupRequirements":{"type":"array","items":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/PickupRequirementType"},{"description":"Requirement type"}]},"description":{"type":"string","example":"Driver must be at least 21 years old","description":"Human-readable description of the requirement"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"example":21,"description":"Specific requirement value (e.g., age, fee amount)"}},"required":["type","description"],"description":"Pickup or dropoff requirement"},"example":[{"type":"MINIMUM_AGE","description":"Driver must be at least 21 years old","value":21},{"type":"CREDIT_CARD_REQUIRED","description":"Valid credit card required at pickup"}],"description":"Requirements for vehicle pickup"},"policies":{"$ref":"#/components/schemas/BookingPolicies"},"remarks":{"type":"array","items":{"type":"string"},"example":["Airport pickup available at Terminal 2","Additional driver can be added for €10/day"],"description":"Additional remarks and important information"}},"required":["vehicle","pickupLocation","dropoffLocation","rentalPeriod","insurance","refillPolicy","mileageAllowance","offerToken","usableUntil","provider","price","pickupRequirements","policies"],"description":"Detailed car rental offer"},"meta":{"allOf":[{"$ref":"#/components/schemas/Metadata"},{"description":"Response metadata"}]}},"required":["success","data","meta"],"description":"Successful offer details response"}}}},"400":{"description":"Invalid offer token or request body","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Offer not found or expired","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error or service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"offer_token_processing_error":{"summary":"Offer Token Processing Error","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Unable to process offer token due to internal decryption error"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_unavailable":{"summary":"Provider Service Unavailable","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Car rental provider service is currently unavailable"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"offer_retrieval_timeout":{"summary":"Offer Retrieval Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Request timed out while retrieving offer details from provider"},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_authentication_error":{"summary":"Provider Authentication Error","value":{"success":false,"error":{"code":"PROVIDER_ERROR","message":"Authentication failed with car rental provider system"},"meta":{"requestId":"req_stu901vwx234-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}}},"/cars/prebook":{"post":{"summary":"Prebook Vehicle","description":"Create a preliminary booking reservation for a vehicle offer. This locks the price and availability for a limited time. Returns reservation details and required information needed to complete the booking.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrebookRequest"}}}},"responses":{"200":{"description":"Existing prebooking returned (idempotent duplicate request). Same response format as 201.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PrebookedCarOffer"},"meta":{"allOf":[{"$ref":"#/components/schemas/Metadata"},{"description":"Response metadata"}]}},"required":["success","data","meta"],"description":"Successful prebooking response with flattened offer structure for optimal checkout UX. Contains all vehicle, pricing, policy, and upsell information needed for the checkout flow."}}}},"201":{"description":"New prebooking created successfully with reservation details and list of required information","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PrebookedCarOffer"},"meta":{"allOf":[{"$ref":"#/components/schemas/Metadata"},{"description":"Response metadata"}]}},"required":["success","data","meta"],"description":"Successful prebooking response with flattened offer structure for optimal checkout UX. Contains all vehicle, pricing, policy, and upsell information needed for the checkout flow."}}}},"400":{"description":"Invalid offer token or request body","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Offer not found or no longer available","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error or service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"prebooking_system_failure":{"summary":"Prebooking System Failure","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Prebooking system is currently experiencing technical difficulties"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"reservation_timeout":{"summary":"Reservation Request Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Reservation request timed out while communicating with provider"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_capacity_error":{"summary":"Provider System Overloaded","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Provider system is temporarily overloaded, please try again later"},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"offer_token_expired_during_processing":{"summary":"Offer Token Expired During Processing","value":{"success":false,"error":{"code":"PROVIDER_ERROR","message":"Offer token expired while attempting to create reservation"},"meta":{"requestId":"req_stu901vwx234-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}}},"/cars/bookings":{"post":{"summary":"Create Car Booking","description":"Create a new car rental or sharing booking. Two booking flows are supported:\n\n**Recommended: Prebook Flow** (Search → Prebook → Book) - Use the `offerToken` from the prebook response. This flow provides locked pricing (if provider supports reservations), available upsells with pricing, and tells you exactly which driver information fields are required via `requiredInformation`.\n\n**Direct Booking Flow** (Search → Book) - Use the `offerToken` directly from search results or offer details. This skips the prebook step but note that offer details do NOT include `requiredInformation` - you must collect all potentially required driver information fields. Also requires that a price was already shown to the client (i.e., `estimatedKilometers` was provided during search).\n\nProvide driver information, selected upsells (optional), and notes to complete the booking. Payment is handled automatically through your organization's configured payment method.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Booking request with driver information and optional notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingRequest"}}}},"responses":{"200":{"description":"Booking created and confirmed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CarBooking"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Response after creating a booking"}}}},"201":{"description":"Booking accepted but pending confirmation (status: PENDING) or requires user action via callbackUrl (status: REQUIRES_CONFIRMATION)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CarBooking"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Response after creating a booking"}}}},"400":{"description":"Invalid request parameters (validation failed or invalid offer token)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Offer not found or expired","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error or booking failed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"booking_processing_failure":{"summary":"Booking Processing Failure","value":{"success":false,"error":{"code":"BOOKING_FAILED","message":"Unable to complete booking due to internal processing error"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"payment_system_error":{"summary":"Payment System Error","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Payment processing system is currently unavailable"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_booking_timeout":{"summary":"Provider Booking Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Booking request timed out while processing with car rental provider"},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_system_maintenance":{"summary":"Provider System Under Maintenance","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Car rental provider system is temporarily unavailable for maintenance"},"meta":{"requestId":"req_stu901vwx234-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"database_connection_error":{"summary":"Database Connection Error","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Unable to save booking due to database connection issues"},"meta":{"requestId":"req_vyz345abc678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}}},"/cars/bookings/{bookingId}":{"get":{"summary":"Get Car Booking Details","description":"Retrieve complete details of an existing car rental booking by its ID. This endpoint is specific to car rental bookings and provides car-specific information.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Unique car booking identifier","example":"bc_A1B2C3D4E"},"required":true,"description":"Unique car booking identifier","name":"bookingId","in":"path"}],"responses":{"200":{"description":"Car booking details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/DetailedCarBooking"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Complete booking details including cancellation and change policies.\n\n## Booking Policies\n\nThe `policies` object contains detailed information about what actions can be taken on this booking:\n\n### Cancellation Policy (`policies.cancellation`)\n\n- **availability**: Indicates how cancellation can be performed:\n  - `AVAILABLE_VIA_API`: Can be cancelled through this API\n  - `REQUIRES_MANUAL_CONTACT`: Must contact provider directly (see `manualContact`)\n  - `NOT_AVAILABLE`: Cannot be cancelled\n\n- **deadlines**: Array of time-based cancellation terms, ordered chronologically. Each deadline defines:\n  - `deadline`: ISO 8601 timestamp - terms apply if cancelled before this time\n  - `terms.fee`: Cancellation fee charged (absolute amount in cents)\n  - `terms.refund`: Amount refunded (absolute amount in cents)\n  - `terms.description`: Human-readable explanation of the terms\n\n- **currentTerms**: Terms that apply if cancelled right now (based on current time)\n  - Shows what fee/refund would apply for immediate cancellation\n  - Description explains the current situation (e.g., \"Free cancellation\", \"50% refund\")\n\n- **conditions**: Additional restrictions or information (e.g., refund processing time)\n\n### Change Policy (`policies.changes`)\n\n- **availability**: Overall change availability status (same values as cancellation)\n\n- **changeTypes**: Array of policies for each type of change:\n  - `RENTAL_TIMES`: Modify pickup/dropoff times\n  - `DRIVER_INFO`: Change driver details\n  - `PICKUP_LOCATION`: Change pickup location\n  - `DROPOFF_LOCATION`: Change dropoff location\n  - `VEHICLE_CATEGORY`: Upgrade/downgrade vehicle\n\nEach change type has:\n- `availability`: How this specific change can be made\n- `manualContact`: Contact info when manual action required\n- `currentTerms`: Current fee/terms for this change\n- `conditions`: Restrictions for this change type\n\n### Manual Contact\n\nWhen `availability` is `REQUIRES_MANUAL_CONTACT`, the `manualContact` object provides:\n- `methods`: Array of contact methods (`PHONE`, `EMAIL`, `PROVIDER_WEBSITE`, `IN_PERSON`)\n- `phone`: Phone number to call\n- `email`: Email address to contact\n- `url`: Provider website URL\n- `instructions`: Human-readable instructions for the user\n\n### Usage Examples\n\n**Check if cancellation is possible:**\n```typescript\nif (booking.policies.cancellation.availability === \"AVAILABLE_VIA_API\") {\n  // Can cancel via API\n  const currentFee = booking.policies.cancellation.currentTerms?.fee;\n  const currentRefund = booking.policies.cancellation.currentTerms?.refund;\n}\n```\n\n**Show deadline-based pricing:**\n```typescript\nbooking.policies.cancellation.deadlines?.forEach(deadline => {\n  console.log(`Cancel before ${deadline.deadline}: ${deadline.terms.description}`);\n});\n```\n\n**Handle manual contact requirement:**\n```typescript\nconst driverChange = booking.policies.changes.changeTypes?.find(\n  ct => ct.changeType === \"DRIVER_INFO\"\n);\nif (driverChange?.availability === \"REQUIRES_MANUAL_CONTACT\") {\n  const contact = driverChange.manualContact;\n  // Display contact information to user\n}\n```"}}}},"404":{"description":"Car booking not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"database_query_error":{"summary":"Database Query Error","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Unable to retrieve booking details due to database error"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"booking_data_corruption":{"summary":"Booking Data Corruption","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Booking data appears to be corrupted and cannot be processed"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_sync_failure":{"summary":"Provider Synchronization Failure","value":{"success":false,"error":{"code":"PROVIDER_ERROR","message":"Failed to sync booking details with car rental provider"},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"service_temporarily_unavailable":{"summary":"Service Temporarily Unavailable","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Booking service is temporarily unavailable due to system maintenance"},"meta":{"requestId":"req_stu901vwx234-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}},"patch":{"summary":"Update Car Booking","description":"Update car rental booking information including driver details, rental times, or notes. Time changes require provider support - check `policies.changes.changeTypes` for RENTAL_TIMES availability before attempting.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Unique car booking identifier","example":"bc_A1B2C3D4E"},"required":true,"description":"Unique car booking identifier","name":"bookingId","in":"path"}],"requestBody":{"description":"Updated car booking information","content":{"application/json":{"schema":{"type":"object","properties":{"driver":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"example":"John Doe","description":"Driver's full name (optional but recommended for provider communication)"},"email":{"type":"string","format":"email","example":"john.doe@example.com","description":"Driver's email address"},"phoneNumber":{"type":"string","minLength":1,"example":"+49123456789","description":"Driver's phone number (optional but recommended for provider contact)"},"age":{"type":"integer","minimum":18,"maximum":120,"example":35,"description":"Driver's age"},"licenseNumber":{"type":"string","example":"D1234567890","description":"Driver's license number"},"address":{"type":"object","properties":{"street":{"type":"string","example":"Hauptstraße 123"},"city":{"type":"string","example":"Berlin"},"postalCode":{"type":"string","example":"10115"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"required":["street","city","postalCode","countryCode"],"description":"Driver's address"},"flightNumber":{"type":"string","example":"LH1234","description":"Flight number for airport pickups"},"nationality":{"type":"string","minLength":2,"maxLength":2,"example":"DE","description":"ISO 3166-1 alpha-2 country code"}},"description":"Updated driver information"},"rentalPeriod":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/DatetimeInput"},"end":{"allOf":[{"$ref":"#/components/schemas/DatetimeInput"},{"description":"End date and time in ISO 8601 format. Accepts timezone offsets (e.g., '+01:00'), automatically normalized to UTC.","example":"2030-02-05T10:00:00Z"}]}},"required":["start","end"],"description":"New rental period. Check `policies.changes.changeTypes` for RENTAL_TIMES availability before attempting to change times."},"notes":{"type":"string","maxLength":500,"description":"Updated notes or special requests"}},"additionalProperties":false,"description":"Request to update booking information.\n\n**Supported update types:**\n- `driver`: Update driver information (name, email, phone, etc.)\n- `rentalPeriod`: Change pickup/return times (requires provider support)\n- `notes`: Update booking notes\n\n**Important:** Before changing rental times, check `GET /cars/bookings/{id}` response for `policies.changes.changeTypes` to verify RENTAL_TIMES is available."}}}},"responses":{"200":{"description":"Car booking updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/UpdateCarBookingData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Response after updating a booking"}}}},"400":{"description":"Invalid update request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Car booking not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"booking_update_processing_error":{"summary":"Booking Update Processing Error","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Unable to process booking update due to internal system error"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_update_failure":{"summary":"Provider Update Failure","value":{"success":false,"error":{"code":"PROVIDER_ERROR","message":"Failed to apply booking changes with car rental provider"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"database_update_timeout":{"summary":"Database Update Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Booking update operation timed out due to database performance issues"},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"concurrent_update_conflict":{"summary":"Concurrent Update Conflict","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Booking was modified by another process, please retry your request"},"meta":{"requestId":"req_stu901vwx234-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}}},"/cars/bookings/{bookingId}/cancel":{"post":{"summary":"Cancel Car Booking","description":"Cancel an existing car rental booking. Returns cancellation confirmation with any applicable fees and refund amounts. This endpoint is specific to car rental bookings and applies car-specific cancellation policies.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"bc_A1B2C3D4E","description":"Unique car booking identifier to cancel"},"required":true,"description":"Unique car booking identifier to cancel","name":"bookingId","in":"path"}],"requestBody":{"description":"Car booking cancellation request with optional reason","content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Reason for cancellation"}},"additionalProperties":false,"description":"Request to cancel a booking"}}}},"responses":{"200":{"description":"Car booking cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CancelCarBookingData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Response after cancelling a booking"}}}},"400":{"description":"Invalid cancellation request or car booking cannot be cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Car booking not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"422":{"description":"Booking cannot be cancelled due to business rules (e.g., already cancelled, outside cancellation window, or non-cancellable booking type). The request syntax is valid but the operation violates business constraints.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"already_cancelled":{"summary":"Booking Already Cancelled","value":{"success":false,"error":{"code":"BOOKING_FAILED","message":"Booking has already been cancelled"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"cancellation_window_expired":{"summary":"Cancellation Window Expired","value":{"success":false,"error":{"code":"BOOKING_FAILED","message":"Cancellation is no longer possible for this booking"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"cancellation_processing_failure":{"summary":"Cancellation Processing Failure","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Unable to process booking cancellation due to internal system error"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_cancellation_timeout":{"summary":"Provider Cancellation Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Cancellation request timed out while communicating with car rental provider"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"refund_processing_error":{"summary":"Refund Processing Error","value":{"success":false,"error":{"code":"PROVIDER_ERROR","message":"Booking cancelled but refund processing failed, contact support"},"meta":{"requestId":"req_mno345pqr678-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"provider_system_unavailable":{"summary":"Provider System Unavailable","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Car rental provider cancellation service is temporarily unavailable"},"meta":{"requestId":"req_stu901vwx234-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"database_transaction_failure":{"summary":"Database Transaction Failure","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Database transaction failed during cancellation process"},"meta":{"requestId":"req_vwx567yzd890-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}}},"/cars/bookings/{bookingId}/vehicle-action":{"post":{"summary":"Perform Vehicle Action","description":"Perform a remote vehicle action (LOCK/UNLOCK) on a car rental booking. Returns 202 Accepted - the action will be performed asynchronously without client feedback. The provider will execute the action if supported. For UNLOCK actions, some bookings require a PIN (check `unlockRequiresPin` in booking details). If required but not provided, returns 400 with error code `PIN_REQUIRED`.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"bc_A1B2C3D4E","description":"Unique car booking identifier"},"required":true,"description":"Unique car booking identifier","name":"bookingId","in":"path"}],"requestBody":{"description":"Vehicle action request specifying the action to perform","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"allOf":[{"$ref":"#/components/schemas/VehicleAction"},{"description":"Action to perform on the vehicle"}]},"pin":{"type":"string","minLength":1,"maxLength":20,"example":"1234","description":"PIN for UNLOCK action when the booking requires PIN authentication (unlockRequiresPin=true). Ignored for LOCK action."}},"required":["action"],"additionalProperties":false,"description":"Request to perform a vehicle action (lock/unlock)"}}}},"responses":{"202":{"description":"Vehicle action accepted and will be performed asynchronously. No feedback on completion will be provided.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/VehicleActionData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Response after requesting a vehicle action. Returns 202 Accepted - the action will be performed asynchronously without client feedback."}}}},"400":{"description":"Invalid vehicle action request or PIN required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"pin_required":{"summary":"PIN Required","description":"The booking requires a PIN to unlock the vehicle. Retry with a PIN in the request body.","value":{"success":false,"error":{"code":"PIN_REQUIRED","message":"PIN is required to unlock the vehicle"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}}}}}},"404":{"description":"Car booking not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"action_processing_failure":{"summary":"Action Processing Failure","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"Unable to process vehicle action due to internal system error"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}},"provider_action_timeout":{"summary":"Provider Action Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Vehicle action request timed out while communicating with car rental provider"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}}}}}},"501":{"description":"Vehicle actions not supported by provider","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"operation_not_supported":{"summary":"Operation Not Supported","value":{"success":false,"error":{"code":"OPERATION_NOT_SUPPORTED","message":"Vehicle actions are not supported for this booking"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}}}}}},"503":{"description":"Provider service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"provider_not_configured":{"summary":"Provider Not Configured","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Provider not configured for this organization"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-11-19T14:30:00Z"}}}}}}}}}},"/bookings":{"get":{"summary":"List All Bookings","description":"Retrieve a paginated list of bookings. Currently only supports car rental bookings. Requires 'cars:booking:read' permission. For detailed information, use the modality-specific booking endpoints.","tags":["Cars (Rental & Sharing)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["cars"],"description":"Filter bookings by type (e.g., 'cars')"},"required":false,"description":"Filter bookings by type (e.g., 'cars')","name":"type","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Page number (0-indexed, default: 0)"},"required":false,"description":"Page number (0-indexed, default: 0)","name":"page","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Number of results per page (default: 20, max: 100)"},"required":false,"description":"Number of results per page (default: 20, max: 100)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Filter by booking status"},"required":false,"description":"Filter by booking status","name":"status","in":"query"}],"responses":{"200":{"description":"Bookings list retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/BookingListData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Modality-independent booking list response"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/mobility-providers":{"get":{"summary":"List Providers","description":"List all mobility service providers that are available and enabled for your organization. Returns basic information about each provider including supported capabilities, countries, and contact details.","tags":["Mobility Providers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"example":0,"description":"Page number (0-indexed, default: 0)"},"required":false,"description":"Page number (0-indexed, default: 0)","name":"page","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"example":20,"description":"Number of results per page (default: 20, max: 100)"},"required":false,"description":"Number of results per page (default: 20, max: 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with list of mobility service providers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MobilityProvidersListData"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Response containing list of mobility service providers"}}}},"401":{"description":"Authentication required or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Access forbidden for this organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"internal_error":{"summary":"Internal Processing Error","value":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An internal error occurred while fetching mobility providers"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-11-12T14:30:00Z"}}}}}}}}}},"/mobility-providers/{id}":{"get":{"summary":"Get Provider Details","description":"Get detailed information about a specific mobility service provider including contact information, supported modes, branding details, and organizational capabilities.","tags":["Mobility Providers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"stadtmobil-stuttgart","description":"Unique provider identifier (slug format)"},"required":true,"description":"Unique provider identifier (slug format)","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response with detailed provider information","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","example":"stadtmobil","description":"Unique provider identifier"},"name":{"type":"string","example":"Stadtmobil","description":"Provider display name"},"logoUrl":{"type":"string","format":"uri","example":"https://cdn.adapt2move.com/providers/stadtmobil/logo.png","description":"URL to provider's logo image (absent when no logo is available)"},"websiteUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de","description":"Provider's website URL"},"supportedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"example":["DE","FR","IT","ES"],"description":"List of supported countries (ISO 3166-1 alpha-2 codes)"},"capabilityLevel":{"allOf":[{"$ref":"#/components/schemas/ProviderCapabilityLevel"},{"description":"Level of service capabilities offered by this provider"}]},"description":{"type":"string","example":"Carsharing service operating in multiple German cities","description":"Provider description"},"modes":{"type":"array","items":{"$ref":"#/components/schemas/MobilityMode"},"example":["CAR"],"description":"Supported mobility modes"},"termsOfServicesUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/terms","description":"Terms of service URL"},"privacyPolicyUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/privacy","description":"Privacy policy URL"},"generalContactInfo":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"support@stadtmobil.de","description":"Contact email address"},"phoneNr":{"type":"string","example":"+49 711 12345 67","description":"Contact phone number"},"contactFormUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/contact","description":"URL to contact form"},"contactPerson":{"type":"object","properties":{"firstName":{"type":"string","example":"John","description":"Contact person's first name"},"lastName":{"type":"string","example":"Smith","description":"Contact person's last name"},"role":{"type":"string","example":"Customer Support Manager","description":"Contact person's role or title"}},"description":"Contact person information"}},"required":["email"],"description":"General contact information"},"supportContactInfo":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"support@stadtmobil.de","description":"Contact email address"},"phoneNr":{"type":"string","example":"+49 711 12345 67","description":"Contact phone number"},"contactFormUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/contact","description":"URL to contact form"},"contactPerson":{"type":"object","properties":{"firstName":{"type":"string","example":"John","description":"Contact person's first name"},"lastName":{"type":"string","example":"Smith","description":"Contact person's last name"},"role":{"type":"string","example":"Customer Support Manager","description":"Contact person's role or title"}},"description":"Contact person information"}},"required":["email"],"description":"Support contact information"},"salesContactInfo":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"support@stadtmobil.de","description":"Contact email address"},"phoneNr":{"type":"string","example":"+49 711 12345 67","description":"Contact phone number"},"contactFormUrl":{"type":"string","format":"uri","example":"https://www.stadtmobil.de/contact","description":"URL to contact form"},"contactPerson":{"type":"object","properties":{"firstName":{"type":"string","example":"John","description":"Contact person's first name"},"lastName":{"type":"string","example":"Smith","description":"Contact person's last name"},"role":{"type":"string","example":"Customer Support Manager","description":"Contact person's role or title"}},"description":"Contact person information"}},"required":["email"],"description":"Sales contact information"},"marketing":{"type":"object","properties":{"colors":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["PRIMARY","SECONDARY","ACCENT"],"example":"PRIMARY","description":"Color category"},"color":{"type":"string","example":"#FF5F00","description":"Hex color code"}},"required":["category","color"],"description":"Brand color information"},"description":"Brand colors"}},"description":"Marketing and branding information"},"supportedLanguages":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"example":["en","de","fr","es"],"description":"List of supported languages (ISO 639-1 codes)"}},"required":["id","name","capabilityLevel","generalContactInfo"],"description":"Detailed provider information"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Response containing detailed information about a specific mobility service provider"}}}},"401":{"description":"Authentication required or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Access forbidden for this organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Provider not found or not available for your organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"not_found":{"summary":"Provider Not Found","value":{"success":false,"error":{"code":"NOT_FOUND","message":"Mobility provider not found or not available for your organization"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-11-12T14:30:00Z"}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/micromobility":{"post":{"summary":"[Beta] Search Micro Mobility Vehicles","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nSearch for available micro mobility vehicles (e-scooters, bikes, mopeds) near a location. Returns real-time availability with pricing from multiple providers. Vehicles are sorted by distance from search location.","tags":["Micro Mobility (Scooters & Bikes)"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Search parameters including location and optional filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MicroMobilitySearchRequest"}}}},"responses":{"200":{"description":"Successful search returning available vehicles from all providers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MicroMobilitySearchResult"},"meta":{"allOf":[{"$ref":"#/components/schemas/Metadata"},{"description":"Response metadata"}]}},"required":["success","data","meta"],"description":"Successful micro mobility vehicle search response"}}}},"400":{"description":"Invalid request parameters (validation failed)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error or service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"},"examples":{"provider_timeout":{"summary":"Provider Service Timeout","value":{"success":false,"error":{"code":"TIMEOUT","message":"Search request timed out while connecting to mobility providers"},"meta":{"requestId":"req_abc123def456-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}},"service_unavailable":{"summary":"Service Temporarily Unavailable","value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Micro mobility service is temporarily unavailable"},"meta":{"requestId":"req_xyz789ghi012-1730123456789","timestamp":"2025-10-27T14:30:00Z"}}}}}}}}}},"/micromobility/vehicles/{vehicleId}":{"get":{"summary":"[Beta] Get Vehicle Details","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nGet detailed information about a specific vehicle including real-time location, battery status, and pricing.","tags":["Micro Mobility (Scooters & Bikes)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Encrypted vehicle token from search results (vehicleToken field). Valid for 5 minutes."},"required":true,"description":"Encrypted vehicle token from search results (vehicleToken field). Valid for 5 minutes.","name":"vehicleId","in":"path"}],"responses":{"200":{"description":"Vehicle details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MicroMobilityVehicle"},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Micro mobility vehicle details response"}}}},"404":{"description":"Vehicle not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/micromobility/zones":{"get":{"summary":"[Beta] Get Geofencing Zones","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nGet geofencing zones near a location including service areas, no-parking zones, slow zones, and preferred parking areas.","tags":["Micro Mobility (Scooters & Bikes)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Search center latitude"},"required":true,"description":"Search center latitude","name":"latitude","in":"query"},{"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Search center longitude"},"required":true,"description":"Search center longitude","name":"longitude","in":"query"},{"schema":{"type":"integer","minimum":100,"maximum":10000,"description":"Search radius in meters"},"required":false,"description":"Search radius in meters","name":"radiusMeters","in":"query"},{"schema":{"type":"string","description":"Comma-separated zone types filter"},"required":false,"description":"Comma-separated zone types filter","name":"types","in":"query"},{"schema":{"type":"string","description":"Comma-separated provider IDs filter"},"required":false,"description":"Comma-separated provider IDs filter","name":"providers","in":"query"}],"responses":{"200":{"description":"Geofencing zones in the search area","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"zones":{"type":"array","items":{"$ref":"#/components/schemas/Zone"},"description":"Zones in the search area"},"serviceArea":{"allOf":[{"$ref":"#/components/schemas/Zone"},{"description":"Main service area boundary"}]},"lastUpdated":{"type":"string","format":"date-time","description":"When zone data was last fetched"}},"required":["zones","lastUpdated"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Geofencing zones response"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/micromobility/pricing-plans":{"get":{"summary":"[Beta] Get Pricing Plans","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nGet available pricing plans from micro mobility providers. Includes unlock fees, per-minute rates, and any applicable discounts.","tags":["Micro Mobility (Scooters & Bikes)"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter by provider ID"},"required":false,"description":"Filter by provider ID","name":"providerId","in":"query"}],"responses":{"200":{"description":"Available pricing plans","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/PricingPlanDetailed"},"description":"Available pricing plans"},"lastUpdated":{"type":"string","format":"date-time","description":"When pricing data was last fetched"}},"required":["plans","lastUpdated"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","data","meta"],"description":"Pricing plans response"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/public-transport":{"post":{"summary":"[Beta] Search Journeys","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nSearch for public transport connections between two locations. Returns a list of journey options with real-time information, transfer details, and pricing where available.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Search parameters including origin, destination, and travel time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneySearchRequest"}}}},"responses":{"200":{"description":"Successful search returning available journeys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneySearchResponse"}}}},"400":{"description":"Invalid request parameters (validation failed)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error or service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/public-transport/journey":{"post":{"summary":"[Beta] Get Journey Details","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nGet detailed information about a specific journey including all intermediate stops, real-time updates, ticket options, and accessibility information.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Journey token from search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyDetailsRequest"}}}},"responses":{"200":{"description":"Detailed journey information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyDetailsResponse"}}}},"400":{"description":"Invalid request or token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Journey not found or no longer available","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/public-transport/stops":{"get":{"summary":"[Beta] Search Stops","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nSearch for public transport stops by name or location. Returns stops with their IDs that can be used in journey searches.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"description":"Text search query (stop name)"},"required":false,"description":"Text search query (stop name)","name":"query","in":"query"},{"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for nearby search"},"required":false,"description":"Latitude for nearby search","name":"latitude","in":"query"},{"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for nearby search"},"required":false,"description":"Longitude for nearby search","name":"longitude","in":"query"},{"schema":{"type":"integer","minimum":100,"maximum":50000,"description":"Search radius in meters"},"required":false,"description":"Search radius in meters","name":"radius","in":"query"},{"schema":{"type":"string","description":"Comma-separated transport modes filter"},"required":false,"description":"Comma-separated transport modes filter","name":"modes","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Number of results"},"required":false,"description":"Number of results","name":"limit","in":"query"},{"schema":{"type":"string","enum":["vvs","vesputi","allaboard"],"description":"Provider to use (vvs=Stuttgart region, vesputi=Germany-wide, allaboard=European rail)"},"required":false,"description":"Provider to use (vvs=Stuttgart region, vesputi=Germany-wide, allaboard=European rail)","name":"provider","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"description":"Pagination cursor from previous response","name":"cursor","in":"query"}],"responses":{"200":{"description":"List of matching stops","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopSearchResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/mobility-api/v2/public-transport/departures":{"get":{"summary":"[Beta] Departures","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nGet upcoming departures from a stop. Returns real-time information including delays and platform changes.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Stop/station identifier from stop search"},"required":true,"description":"Stop/station identifier from stop search","name":"stopId","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Departure time to search from (default: now)"},"required":false,"description":"Departure time to search from (default: now)","name":"dateTime","in":"query"},{"schema":{"type":"string","description":"Comma-separated transport modes filter (e.g., TRAIN,BUS)"},"required":false,"description":"Comma-separated transport modes filter (e.g., TRAIN,BUS)","name":"modes","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of departures (default: 20)"},"required":false,"description":"Maximum number of departures (default: 20)","name":"limit","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1440,"description":"Time window in minutes (default: 60, max: 1440)"},"required":false,"description":"Time window in minutes (default: 60, max: 1440)","name":"timeWindowMinutes","in":"query"}],"responses":{"200":{"description":"List of upcoming departures","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartureSearchResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/public-transport/prebook":{"post":{"summary":"[Beta] Prebook Journey","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nCreate a temporary reservation for a journey. Returns pricing, required traveler information, and a token for completing the booking. Only available for providers that support booking.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Journey token and traveler information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTPrebookRequest"}}}},"responses":{"200":{"description":"Existing prebooking returned (idempotent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTPrebookResponse"}}}},"201":{"description":"Prebooking created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTPrebookResponse"}}}},"400":{"description":"Invalid request or token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Journey not available for booking","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/public-transport/bookings":{"post":{"summary":"[Beta] Create Booking","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nComplete a ticket booking. Can use either a prebooked journey token or a direct journey token. Returns tickets with QR codes or PDF links.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Booking details with journey token and traveler information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTBookingRequest"}}}},"responses":{"201":{"description":"Booking created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTBookingResponse"}}}},"400":{"description":"Invalid request or token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Journey or prebooking not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error or booking failed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/public-transport/bookings/{bookingId}":{"get":{"summary":"[Beta] Get Booking Details","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nRetrieve details of an existing public transport booking including ticket information.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Booking identifier"},"required":true,"description":"Booking identifier","name":"bookingId","in":"path"}],"responses":{"200":{"description":"Booking details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTBookingResponse"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/public-transport/bookings/{bookingId}/cancel":{"post":{"summary":"[Beta] Cancel Booking","description":"**Beta**: This endpoint is under active development. Breaking changes may occur.\n\nCancel an existing public transport booking. Refund information is returned if applicable.","tags":["Public Transport"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Booking identifier"},"required":true,"description":"Booking identifier","name":"bookingId","in":"path"}],"requestBody":{"description":"Cancellation details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTCancelBookingRequest"}}}},"responses":{"200":{"description":"Booking cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTCancelBookingResponse"}}}},"400":{"description":"Booking cannot be cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Forbidden - insufficient permissions for this operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}},"/multimodal/tiles/{z}/{x}/{y}":{"get":{"summary":"Get mobility data for a map tile","description":"Returns mobility data for a single map tile using the standard slippy map tile system (z/x/y).\n\n**Dual-Format Support:**\n\nThe endpoint serves both JSON and MVT (Mapbox Vector Tile) formats via the `Accept` header:\n- `Accept: application/json` (default) — Structured JSON response\n- `Accept: application/vnd.mapbox-vector-tile` — Binary MVT protobuf for MapLibre/Mapbox\n\n**Resolution Levels (3 levels):**\n\n| Zoom Level | Resolution | What You Get |\n|------------|------------|--------------|\n| z0-12 | `overview` | Service areas (provider coverage zones) |\n| z13-15 | `summary` | Service areas + station/stop markers (no live data) |\n| z16+ | `detailed` | Individual vehicles/stations/stops with booking tokens |\n\n**Cache Headers:**\n- Overview tiles (z0-12): `Cache-Control: private, max-age=3600`\n- Summary tiles (z13-15): `Cache-Control: private, max-age=300`\n- Detailed tiles (z16+): `Cache-Control: private, max-age=30`\n\n**MVT Layers** (when using MVT format):\n- `vehicles` — Micromobility vehicles (Point)\n- `stations` — Carsharing + car rental stations (Point)\n- `stops` — PT stops with departure data (Point)\n- `service-areas` — Provider coverage zones (Polygon)\n\n**Query Parameters:**\nFilter which mobility types to include using the `types` parameter.\nAdditional per-type parameters available for PT and micromobility.\n\n**Client-Side Usage (Publishable Keys):**\nThis endpoint supports Publishable Keys (`a2m_pk_...`) for direct browser access.\nCreate a publishable key with the `multimodal:explore:read` permission and configure your allowed domains in the Workspace Dashboard.\nThe API validates the `Origin` header and includes CORS headers (`Access-Control-Allow-Origin`, etc.) automatically.","tags":["Multimodal"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"maximum":22,"description":"Tile zoom level"},"required":true,"description":"Tile zoom level","name":"z","in":"path"},{"schema":{"type":"integer","minimum":0,"description":"Tile X coordinate"},"required":true,"description":"Tile X coordinate","name":"x","in":"path"},{"schema":{"type":"integer","minimum":0,"description":"Tile Y coordinate"},"required":true,"description":"Tile Y coordinate","name":"y","in":"path"},{"schema":{"type":"string","example":"pt,micromobility,carsharing,carRental,ridesharing","description":"Comma-separated mobility types to include. Default: all types. Options: pt, micromobility, carsharing, carRental, ridesharing"},"required":false,"description":"Comma-separated mobility types to include. Default: all types. Options: pt, micromobility, carsharing, carRental, ridesharing","name":"types","in":"query"},{"schema":{"type":"string","example":"de:08111:6115,de:08111:6118","description":"Comma-separated stop IDs. When provided, only these stops are returned (disables bbox discovery)"},"required":false,"description":"Comma-separated stop IDs. When provided, only these stops are returned (disables bbox discovery)","name":"stopIds","in":"query"},{"schema":{"type":"string","example":"SUBURBAN_RAIL,BUS","description":"Comma-separated transport modes to filter PT departures"},"required":false,"description":"Comma-separated transport modes to filter PT departures","name":"transportModes","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":120,"example":60,"description":"Time window for departures in minutes (default: 60, max: 120)"},"required":false,"description":"Time window for departures in minutes (default: 60, max: 120)","name":"timeWindowMinutes","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"example":5,"description":"Max departures to return per stop (default: 5, max: 20)"},"required":false,"description":"Max departures to return per stop (default: 5, max: 20)","name":"departuresPerStop","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"example":10,"description":"Max stops to return (default: 10, max: 20)"},"required":false,"description":"Max stops to return (default: 10, max: 20)","name":"maxStops","in":"query"},{"schema":{"type":"string","example":"station-123,station-456","description":"Comma-separated carsharing station IDs. When provided, only these stations are returned"},"required":false,"description":"Comma-separated carsharing station IDs. When provided, only these stations are returned","name":"stationIds","in":"query"},{"schema":{"type":"string","example":"SCOOTER,BICYCLE","description":"Comma-separated vehicle types to filter"},"required":false,"description":"Comma-separated vehicle types to filter","name":"vehicleTypes","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":100,"example":20,"description":"Minimum battery level (0-100)"},"required":false,"description":"Minimum battery level (0-100)","name":"minBatteryPercent","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"example":100,"description":"Max vehicles/stations to return (default: 100, max: 200)"},"required":false,"description":"Max vehicles/stations to return (default: 100, max: 200)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Set to 'true' to force detailed resolution (with departures) at zoom levels 13-15. Requires z >= 13."},"required":false,"description":"Set to 'true' to force detailed resolution (with departures) at zoom levels 13-15. Requires z >= 13.","name":"forceDetailed","in":"query"},{"schema":{"type":"string","description":"Set to 'true' to include spatial cache debug metadata in the response"},"required":false,"description":"Set to 'true' to include spatial cache debug metadata in the response","name":"debug","in":"query"}],"responses":{"200":{"description":"Tile data (JSON or MVT binary)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TileData"},"meta":{"allOf":[{"$ref":"#/components/schemas/Metadata"},{"description":"Response metadata"}]}},"required":["success","data","meta"],"description":"Successful tile response with mobility data"}},"application/vnd.mapbox-vector-tile":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid tile coordinates or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"401":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}},"503":{"description":"All requested data sources unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details (field-specific validation errors, etc.)"}},"required":["code","message"]},"meta":{"$ref":"#/components/schemas/Metadata"}},"required":["success","error","meta"],"description":"Standard error response envelope"}}}}}}}},"webhooks":{}}