Ride inquiry
This guide is written from the perspective of an external integrator. On this page, you means a non-ioki user integrating with ioki Platform.
Ride inquiry is a lightweight availability and estimation check in the Platform API. Use it before ride creation when your integration needs to check whether a trip is likely to be serviceable or when you want to show estimated pickup, drop-off, fare, or app-link information.
This page explains how to use ride inquiry in an integration flow. It supplements the API Docs, which remain the reference for request and response details.
This guide uses the current Platform API version v20210101.
When to use ride inquiry
Use ride inquiry when you want to:
- check whether the product is available at the requested time
- check whether the origin and destination are inside the service area
- check whether the passenger mix and requested resources can be served
- show rough pickup and drop-off estimates before creating a ride
- show an estimated fare when the product supports fare estimation for ride inquiries
- return links into the configured mobile apps
Ride inquiry does not create a ride or booking. Treat the result as advisory. Your integration still needs to create the ride and follow the normal booking flow.
Required context
Before you run a ride inquiry, make sure your integration has access to the product. ioki Platform only accepts the inquiry when both of these conditions are true:
- the authenticated platform can access the product
- the authenticated client can access the product
Send the usual Platform API headers. For the complete flow, see the ride creation flow.
Relevant endpoint:
POST /api/platform/products/{product_id}/ride_inquiry
Request behavior
Ride inquiry is designed to work with incomplete input, so that clients can call it while a user is still building a request.
Keep these integration-specific rules in mind:
- Send both
originanddestinationkeys, even if one side is currentlynull. - A point can use coordinates, a
station_id, or both. - If you send a time, send only one time: either
origin.timeordestination.time. - If neither point includes a time, ioki Platform treats the inquiry as a request for the current time in the product’s time zone.
- The current Platform API request shape does not accept ride option values for ride inquiry.
The API Docs describe the request and response schema. This page focuses on how to interpret the result in an integration flow.
What ioki Platform evaluates
Ride inquiry builds an in-memory ride request and evaluates it against the current product configuration.
Depending on the provided input, the flow can check:
- whether the product is available at the requested time
- whether the origin and destination are inside the relevant service area
- whether the passenger mix and requested resources are valid
- whether ride filters, travel-combination rules, prebooking rules, and lead-time rules allow the request
- whether the configured estimation adapter can return usable estimations
Some checks add assistances instead of stopping the response. For example, zone announcements can be returned even when the inquiry is otherwise usable.
Response signals
Do not treat ride inquiry as a simple success or failure result. A successful API response can still tell you that the requested ride is not currently usable.
Inspect these response areas:
| Response area | What it tells you |
|---|---|
availability | Whether the product is available at the requested time and, when known, the next availability. |
assistances | Localized messages and error codes that explain why the ride might not be possible or what the user should know. |
constraints.area | The currently relevant service area as GeoJSON. |
constraints.unserved_area | The area that is not served at the requested time, when available. |
estimations | Rough pickup, drop-off, fare, metadata, and app-link information, when the product can estimate the trip. |
Assistances
Use assistances as the main troubleshooting signal. Some assistances include an error_code, which means no ride can be created with the provided information. Other assistances are warnings or informational messages.
Common ride inquiry assistance signals include:
| Signal | Meaning |
|---|---|
service_not_available | The product is not available at the requested time. If known, availability.next_availability provides the next service time. This signal includes an error_code. |
origin_outside_of_service_area | The origin is outside the service area at the relevant time. When returned, this signal includes an error_code. |
destination_outside_of_service_area | The destination is outside the service area at the relevant time. When returned, this signal includes an error_code. |
invalid_passenger | The requested passenger mix or passenger options are not valid for the product. This signal includes an error_code. |
invalid_ride_option | One or more requested ride options cannot be fulfilled for the product. This signal includes an error_code. |
ride_not_prebookable | The request uses a future time, but no matching task list allows prebooking. This assistance does not include an error_code. |
lead_time_filtered_all_solutions | Lead-time rules excluded all possible vehicles. This signal includes an error_code. |
resources_exceed_capabilities | No available vehicle can satisfy the requested resources. This signal usually includes an error_code. |
travel_combination_not_served | The selected origin and destination combination matches a configured blacklisted travel combination. This assistance does not include an error_code. |
| Product-specific ride filter message | A product-specific ride filter rejected or warned about the request. Error filters include the filter-specific error_code; warning filters do not. |
Zone announcements can also appear as assistances. They inform the user about a relevant zone and do not necessarily mean that the inquiry failed.
Estimations
Estimations depend on the product’s ride inquiry settings.
| Estimation adapter | Behavior |
|---|---|
| Black Hole Adapter | Returns no estimations. |
| Fixed time with Stations | Returns rough station-based or line-based estimations when enough origin, destination, service area, task list, station, and routing data is available. |
The fixed-time adapter can return:
- a DRT estimation based on the closest usable pickup and drop-off stations
- a line-based estimation when the matching task list uses a line
- pickup and drop-off time windows
- walking duration and walking track information between the requested points and the selected stations
- fare information, only when fare estimation for ride inquiries is enabled on the product
If routing fails, the origin and destination resolve to the same station, no usable station exists, or the calculated pickup time is already in the past, the fixed-time adapter can return no estimations.
App links
If the product has an inquiry universal link configured, estimations can include links into the configured mobile apps. The link uses the requested origin, destination, and eligible time values.
Time values that are too close for the product’s prebooking threshold are not included in generated app links.
How to use the result
After you receive a ride inquiry response:
- Check
availability.available. - Show any relevant
assistancesto the user. - If estimations are present, show the pickup, drop-off, fare, and link information that is relevant for your client.
- If the user continues, create the ride with a payload that matches the product configuration.
Ride inquiry and ride creation run separate checks. A positive ride inquiry does not guarantee that a later ride creation or booking will succeed, especially if time, fleet state, service area configuration, or product settings change between calls.