Documentation Powered by ReDoc

FluidHub Mobility Service Provider API (v22.1.0)

Download OpenAPI specification:Download

Fluidtime: support@fluidtime.com URL: https://www.fluidtime.com/

Fluidtime provides a full-fledged open MaaS Platform. FluidHub acts as a standardization layer, harmonizing data from multiple Transport Service Providers (TSPs), providing it to Mobility Service Providers (MSPs) and thus enabling seamless access to locally-available transportation offerings. The open APIs provides REST endpoints for Mobility Service Provider (MSP) to integrate the service into their ecosystem. It is intended to be used by server-side services.

This API produces and consumes application/json as specified in RFC 7159.

All date and time values are in UTC. Date, time and duration values are represented according to ISO 8601. This api does not support the 24:00:00 notation of time values. Time is allowed to be at a maximum of 23:59:59, not 24:00:00.

Geographic coordinates are referencing the WGS 84.

Polylines are encoded and represented according to Encoded Polyline Algorithm Format

HTTP 1.1 ETag: All calls are subjects to cache handling as specified in RFC 7232.

Caching of responses is achieved by the HTTP 1.1 ETag mechanism and only affects responses which are allowed to be cached.

For Booking related calls, clients should set a read timeout of at least 15 seconds.

Available custom Specification Extensions
(see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#specification-extensions):

  • x-emailValidation
    Annotates the corresponding mutable/immutable springserver model property with @Email for validation (JSR380 Bean Validation 2.0).

  • x-excludeInSignature
    Excludes the corresponding parameter in API stubs.

  • x-format
    Custom format for data types. Supported formats are:

  • x-phoneNumberValidation
    Annotates the corresponding mutable/immutable springserver model property with @PhoneNumber for validation (JSR380 Bean Validation 2.0).

Used abbreviations:

  • transport service provider (TSP)
  • mobility service provider (MSP)
  • mobility service consumer (MSC)

Authentication

MSP

Authentication of a client via an API key sent in the Authorization header. Header value is ignored if authorization is not required by the called API.

Security Scheme Type API Key
Header parameter name: Authorization

Booking

Announcing a booking

A booking must be announced to make the actual booking call idempotent. Returns a nonce required for executing a booking.

Authorizations:
MSP
header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

Request-UUID
string

Request UUID.

Responses

200

Nonce for the booking.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

post /bookings/announce
http://fluidtime.services/api/msp/bookings/announce

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "nonce": "string"
}

Get bookings

Returns all bookings (for a specific user reference, if provided).

Authorizations:
MSP
query Parameters
userId
string

Filters bookings on external user reference as supplied with User-Reference header.

includeStates
Array of strings (BookingState)
Items Enum: "INITIATED" "PENDING" "OPEN" "COMPLETED" "FAILED" "ERROR"

Comma separated list of booking states returned bookings can be in. (Takes precedence over excludeStates)

excludeStates
Array of strings (BookingState)
Items Enum: "INITIATED" "PENDING" "OPEN" "COMPLETED" "FAILED" "ERROR"

Comma separated list of booking state, returned bookings cannot be in.

productTypes
Array of strings (ProductType)
Items Enum: "ITEM" "PARKING" "RIDE" "TICKET" "VEHICLE"

Product types to filter.

tsps
Array of strings

TSP ids of tsps to filter.

startCreationDate
string <date>

Filter for the creation date of a booking (inclusive).

endCreationDate
string <date>

Filter for the creation date of a booking (inclusive).

page
integer <int32> >= 0
Default: 0

Number of the requested page.

pSize
integer <int32> >= 1

Number of elements returned per page.

tspBookingReference
string ^([*][^*]+|[^*]+[*]|[*][^*]+[*]|[^*]+)$

Tsp booking reference to filter. Wildcard (*) is supported at start and end of string

fullTextSearch
string

Searches string (startsWith-search) in booking full text index. Indexed fields are:

  • Booking.id
  • Booking.bookingReference
  • Booking.userReference
  • Booking.data.customer.firstName
  • Booking.data.customer.lastName
  • Booking.data.customer.phoneNumber
  • Booking.product.data.name
  • Booking.product.data.origin.address.name
  • Booking.product.data.destination.address.name
sort
Array of strings
Default: "RELEVANCEDATE_DESC"
Items Enum: "RELEVANCEDATE_ASC" "RELEVANCEDATE_DESC" "CREATEDATE_ASC" "CREATEDATE_DESC" "STATE_ASC" "STATE_DESC" "COMPLETIONREASON_ASC" "COMPLETIONREASON_DESC" "LASTSTATECHANGEDATE_ASC" "LASTSTATECHANGEDATE_DESC"

Sorts the results by the provided parameters. The default sorting of RELEVANCEDATE_DESC is implicitly appended to all queries as well. (e.g. when sorting by TSPNAME_DESC the results will be sorted by TSPNAME_DESC, RELEVANCEDATE_DESC)

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

List of bookings.

400

The provided input parameters are not valid.

404

The requested resource is not available.

422

The request was well-formed but was unable to be followed due to semantic errors.

500

General error.

503

Service is temporarily unavailable.

get /bookings
http://fluidtime.services/api/msp/bookings

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "bookings":
    [
    ],
  • "page":
    {
    }
}

Create a booking

Creates a booking using the previously acquired booking nonce.

The created booking will be in state INITIATED but will not be performed at the TSP until PUT /bookings/{identifier}/perform is called.

Authorizations:
MSP
header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Request Body schema: application/json

Object containing product references and booking information.

additionalBookingData
object (AdditionalBookingData)

Additional data for a request object to book a product.

nonce
required
string non-empty

The announce nonce that was created by /announce.

product
required
object (BookingRequestProduct)

Reference to a bookable product, optionally with add-ons.

Responses

200

Result of the booking.

400

The provided input parameters are not valid.

403

Authentication succeeded, but access to the requested resource was refused.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

post /bookings
http://fluidtime.services/api/msp/bookings

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "additionalBookingData":
    {
    },
  • "nonce": "string",
  • "product":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "booking":
    {
    },
  • "bookingId": "string",
  • "completionReason": "COMPLETED",
  • "cancelable": true,
  • "createDate": "2020-06-16T14:28:45Z",
  • "relevanceDate": "2020-06-16T14:28:45Z",
  • "state": "INITIATED",
  • "lastStateChangeDate": "2020-06-16T14:28:45Z",
  • "updateDate": "2020-06-16T14:28:45Z",
  • "hasBeenPerformed": true,
  • "success": true
}

Deletes/anonymizes bookings

Anonymizes bookings to remove any relations to natural persons (hence GDPR is not applicable any more). The userId will be removed from those bookings.

Authorizations:
MSP
query Parameters
userId
required
string

All bookings having this userId will be anonymized.

header Parameters
Request-UUID
string

Request UUID.

Responses

204

OK

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

delete /bookings
http://fluidtime.services/api/msp/bookings

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "code": "string",
  • "message": "string",
  • "hints":
    [
    ]
}

Get a booking

Returns the details of a specified booking.

Authorizations:
MSP
path Parameters
identifier
required
string non-empty

Non-enumerable identifier.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

Result of the booking.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /bookings/{identifier}
http://fluidtime.services/api/msp/bookings/{identifier}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "booking":
    {
    },
  • "bookingId": "string",
  • "completionReason": "COMPLETED",
  • "cancelable": true,
  • "createDate": "2020-06-16T14:28:45Z",
  • "relevanceDate": "2020-06-16T14:28:45Z",
  • "state": "INITIATED",
  • "lastStateChangeDate": "2020-06-16T14:28:45Z",
  • "updateDate": "2020-06-16T14:28:45Z"
}

Perform a booking

Performs an INITIATED booking at the TSP.

Authorizations:
MSP
path Parameters
identifier
required
string non-empty

Non-enumerable identifier.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

Result of the booking.

400

The provided input parameters are not valid.

403

Authentication succeeded, but access to the requested resource was refused.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

put /bookings/{identifier}/perform
http://fluidtime.services/api/msp/bookings/{identifier}/perform

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "booking":
    {
    },
  • "bookingId": "string",
  • "completionReason": "COMPLETED",
  • "cancelable": true,
  • "createDate": "2020-06-16T14:28:45Z",
  • "relevanceDate": "2020-06-16T14:28:45Z",
  • "state": "INITIATED",
  • "lastStateChangeDate": "2020-06-16T14:28:45Z",
  • "updateDate": "2020-06-16T14:28:45Z",
  • "hasBeenPerformed": true,
  • "success": true
}

Cancel a booking

Cancels a specific booking via its id.

Concurrent cancellations for the same booking id result in a HTTP 409 Conflict for all executions but the first.

Authorizations:
MSP
path Parameters
identifier
required
string non-empty

Non-enumerable identifier.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

Result of the booking.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

put /bookings/{identifier}/cancel
http://fluidtime.services/api/msp/bookings/{identifier}/cancel

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "booking":
    {
    },
  • "bookingId": "string",
  • "completionReason": "COMPLETED",
  • "cancelable": true,
  • "createDate": "2020-06-16T14:28:45Z",
  • "relevanceDate": "2020-06-16T14:28:45Z",
  • "state": "INITIATED",
  • "lastStateChangeDate": "2020-06-16T14:28:45Z",
  • "updateDate": "2020-06-16T14:28:45Z",
  • "hasBeenPerformed": true,
  • "success": true
}

Resolve a problematic booking state.

The intended use for this operation is recovering bookings from problematic states and is not to be used for regular workflows. Furthermore, changes to a booking's state are not propagated to the third-party web-service originally responsible for the booking. (e.g. If set booking state is set to COMPLETED with completion state CANCELLED, the booking is not cancelled at the TSP.)

Bookings can end up in state ERROR, if the MSP API delegating the booking to a thrid-party web-service cannot determine whether the booking has been successful or failed. This state requires manual intervention, because the system cannot determine the booking state within the third-party web-service due to missing the external booking reference.

Bookings can end up in state PENDING, if a rare internal error occurs while the booking is processed by the MSP API. Basically this should not happen and indicates a bug within the booking logic or a sudden forceful end of the process. This state requires manual intervention, because the booking is in an unknown state.

Normally, bookings are OPEN until getting COMPLETED by either active cancellation by the MSC user or being automatically COMPLETED via an automated sync with the third-party web-service when the booking is being accessed. In some cases and with some third-party services the information that a booking is COMPLETED is not available, leading to an indefinitely OPEN booking. This case also requires manual intervention to be resolved.

The following transitions are supported:

  • ERROR -> OPEN
  • ERROR -> COMPLETED (any completion reason)
  • ERROR -> FAILED
  • PENDING -> OPEN
  • PENDING -> COMPLETED (any completion reason)
  • PENDING -> FAILED
  • OPEN -> COMPLETED (any completion reason)
  • OPEN -> FAILED

If the targetState is COMPLETED, the completionReason must be set, otherwise it cannot be set.

Authorizations:
MSP
path Parameters
identifier
required
string non-empty

Non-enumerable identifier.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Request Body schema: application/json

Requested state change.

targetState
required
string (BookingTargetState)
Enum: "OPEN" "COMPLETED" "FAILED"

Manual states to change a booking to.

OPEN: Booking will be set in the state OPEN. Booking will be synchronized with an external provider again - this may lead to a non OPEN state. Properties of a booked product are subject to change.

COMPLETED: The booked product is considered not to change any more. No further interactions with an external booking service regarding this booked product will be conducted. This is a final state.

FAILED: The external booking service could not complete the booking. This is a final state.

completionReason
string (BookingCompletionState)
Enum: "COMPLETED" "CANCELLED"

States of a completion reason.

COMPLETED: The service related to the booked product has been successfully delivered.

CANCELLED: The service related to the booked product has not been and will not be delivered in the future.

Responses

200

Result of the booking.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

422

The request was well-formed but was unable to be followed due to semantic errors.

500

General error.

503

Service is temporarily unavailable.

put /bookings/{identifier}/changeState
http://fluidtime.services/api/msp/bookings/{identifier}/changeState

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "targetState": "OPEN",
  • "completionReason": "COMPLETED"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "booking":
    {
    },
  • "bookingId": "string",
  • "completionReason": "COMPLETED",
  • "cancelable": true,
  • "createDate": "2020-06-16T14:28:45Z",
  • "relevanceDate": "2020-06-16T14:28:45Z",
  • "state": "INITIATED",
  • "lastStateChangeDate": "2020-06-16T14:28:45Z",
  • "updateDate": "2020-06-16T14:28:45Z"
}

Info

Get MSP details

Returns all available MSP details.

Authorizations:
MSP
header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

MSP details.

304

The requested resource was not modified since the last request.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /
http://fluidtime.services/api/msp/

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "description": "string",
  • "languageCode": "st",
  • "privacyPolicyUrl": "string",
  • "supportEmail": "user@example.com",
  • "supportHotline": "string",
  • "supportUrl": "string",
  • "termsOfServiceUrl": "string",
  • "title": "string",
  • "websiteUrl": "string",
  • "icon": "string",
  • "timezone": "string"
}

Get the most suitable leg icon

Returns the most suitable leg icon for the specified parameters. They can be considered as default icons. Apps may use their own icons.

Authorizations:
MSP
query Parameters
modality
string non-empty

General transit modality. See definition of Modality for recognised values.

transportation
string

Mode of transport. See definition of Transportation for recognised values.

serviceCategory
string

Service category of a transit service. See definition of ServiceCategory for recognised values.

serviceRange
string

Scale of the operating area of a transit service. See definition of ServiceRange for recognised values.

header Parameters
User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

Returns the the most suitable leg icon in PNG format.

304

The requested resource was not modified since the last request.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /legIcon
http://fluidtime.services/api/msp/legIcon

Response samples

Content type
image/png
No sample

Get available TSPs

Returns all available TSPs for the specified MSP.

Authorizations:
MSP
query Parameters
sort
string
Default: "RELEVANCE_DESC"
Enum: "RELEVANCE_ASC" "RELEVANCE_DESC"

Determines the sort order of the resulting tsps.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

List of TSPs.

304

The requested resource was not modified since the last request.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /tsps
http://fluidtime.services/api/msp/tsps

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get a specific TSP

Returns details of a specific TSP available for a specific MSP.

Authorizations:
MSP
path Parameters
identifier
required
string non-empty

Non-enumerable identifier.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

TSP details.

304

The requested resource was not modified since the last request.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /tsps/{identifier}
http://fluidtime.services/api/msp/tsps/{identifier}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "serviceProvider": true,
  • "retired": true,
  • "supportsBooking": true,
  • "supportsLocations": true,
  • "supportsRouting": true,
  • "supportsSituations": true,
  • "color": "string",
  • "description": "string",
  • "languageCode": "st",
  • "privacyPolicyUrl": "string",
  • "productSelectionWorkflow": "ITEM",
  • "supportEmail": "user@example.com",
  • "supportHotline": "string",
  • "supportUrl": "string",
  • "termsOfServiceUrl": "string",
  • "title": "string",
  • "applyLegStyling": true,
  • "websiteUrl": "string",
  • "icon": "string",
  • "logo": "string",
  • "operatingArea":
    {
    },
  • "locationGroups":
    [
    ]
}

Journey

Get journey details

Returns the specified journey including the visited stops. A journey is used for departure monitors to provide the route of single vehicles together with the scheduled and estimated times of arrival and departure at preceding or subsequent stops.

Authorizations:
MSP
path Parameters
identifier
required
string non-empty

A string which uniquely identifies a journey. The journeyPointId of a stop in a location can be used for this parameter.

query Parameters
mode
string
Enum: "PRE" "SUB"

Specifies whether the preceding or subsequent stops, in relation to the stop specified by identifier, should be included in the journey response. If parameter is omitted, all stops are included in the response.

header Parameters
User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

get /journeys/{identifier}
http://fluidtime.services/api/msp/journeys/{identifier}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "journeyPoints":
    [
    ],
  • "situations":
    [
    ],
  • "transitService":
    {
    }
}

Location

Returns location candidates for implementing an autocomplete search.

This should be used for autocomplete searches instead of other /locations* endpoints.

Results are sorted by decreasing relevance in relation to the search term specified by the name parameter.

Authorizations:
MSP
query Parameters
name
required
string

Filter locations by name.

considerAddresses
boolean
Default: false

If set to true, addresses are also considered for the search.

latLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits. The coordinate is used as reference for regional biasing of search result. If not set, results do not consider any regional preferences.

limit
integer <int32> [ 1 .. 1000 ]

Maximum number of returned location candidates. If not set, a default limit of N is applied, where N depends on the service configuration and defaults to 10.

searchSession
string <uuid>

Defines a search session to optimise costs, if an external provider supports this.

A search session begins with the user requesting location candidates as part of a location autocomplete search and ends with requesting location details via location id. The search session is generated by the server. Each session can have multiple location autocomplete requests followed by exactly one location details request. A session is considered complete thereafter.

An ongoing search session will expire after some time depending on the external provider.

locationGroups
Array of strings

A comma separated list of TSP specific location group ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible location groups are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown location group ids will be ignored and do not result in an error.

productSelectionEligible
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is eligible for product selection.

If this parameter is omitted, no filter is applied. If INCLUDE, only locations eligible for product selection will be returned. If EXCLUDE, only locations not eligible for product selection will be returned.

time
string <date-time>

Reference time used to determine the availability of locations with time based constraints. If set, only "open" locations will be returned for this point in time.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /locationsAutocomplete
http://fluidtime.services/api/msp/locationsAutocomplete

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "candidates":
    [
    ],
  • "searchSession": "string"
}

Get a location via coordinate.

Converts a coordinate into a location.

Authorizations:
MSP
query Parameters
latLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Reference coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /locationByCoordinate
http://fluidtime.services/api/msp/locationByCoordinate

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "location":
    {
    }
}

Get locations within a specified radius

Returns locations witin a radius around a center coordinate.

The value of cLatLng is considered the geographic center of the location request for sorting returned locations.

If a zoomLevel is provided and the parameter reductionMode is set to UNIFORM, only an approximately uniformly distributed subset of locations (adjustable via service configuration and per location group) is returned.

If you are looking for locations in an autocomplete context or addresses, GET /locationsAutocomplete has to be used instead.

Authorizations:
MSP
query Parameters
cLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Center coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

radius
required
integer <int32> [ 10 .. 100000 ]

Radius of the search area around the center coordinate in meters.

name
string non-empty

Filter by name.

iD
string
Default: "NONE"
Enum: "NONE" "WALK" "LD"

Use WALK or LD to include the walking distance or the linear distance between the centroid of the request's geographical location boundary and the locations in the result. If parameter idLatLng is set, its value is used instead of the centroid of the request's geographical location boundary. If WALK is used, only the first N locations are considered for the distance calculation. If no valid walking route could be found, the travel distance is omitted. The value of N depends on the service configuration and defaults to 10. NONE to not include any distance calculations due to the additional costs.

idLatLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Reference coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits. If parameter iD is set and not NONE, either this parameter is used as reference parameter for calculation of location distances, or if this parameter is omitted the centroid of the location request geometry is used.

sort
string
Default: "AUTO"
Enum: "AUTO" "CENTER"

Returned locations are always sorted by the distance to a reference coordinate. The preferred coordinate to be used as the reference coordinate for determining the sort order can be specified by this parameter.

AUTO: If parameter iD (include distance) is not set to NONE and idLatLng is specified, idLatLng is chosen as the reference coordinate for sorting, otherwise the geographic center of the location request is chosen as the reference coordinate for sorting. CENTER: The geographic center of the location request is chosen as the reference coordinate for sorting.

interactable
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is defined as interactable. If this parameter is omitted, no filter is applied. If INCLUDE, only locations defined as interactable will be returned. If EXCLUDE, only locations not defined as interactable will be returned.

limit
integer <int32> >= 1

Maximum number of returned locations.

locationGroups
Array of strings

A comma separated list of TSP specific location group ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible location groups are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown location group ids will be ignored and do not result in an error.

time
string <date-time>

Reference time used to determine the availability of locations with time based constraints. If set, only "open" locations will be returned for this point in time.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

productSelectionEligible
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is eligible for product selection.

If this parameter is omitted, no filter is applied. If INCLUDE, only locations eligible for product selection will be returned. If EXCLUDE, only locations not eligible for product selection will be returned.

reductionMode
string
Default: "CLUSTER"
Enum: "CLUSTER" "UNIFORM"

This parameter only applies if a zoomLevel is provided and determines how the resulting locations are reduced so they can be displayed for the given zoom level. If omitted or explicitly set to CLUSTER, locations are clustered, if needed. If set to UNIFORM, an approximately uniformly distributed subset of locations (adjustable via service configuration and per location group) is returned.

zoomLevel
integer [ 0 .. 20 ]

Current zoom level of the web map used for clustering and deciding whether records are included in the result. If the zoom level parameter is not specified, no clustering or filtering will occur. Depending on the web map, zoom level may be in the range from 0 to 20. Please refer to http://wiki.openstreetmap.org/wiki/Zoom_levels and https://developers.google.com/maps/documentation/javascript/maxzoom

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /locationsByRadius
http://fluidtime.services/api/msp/locationsByRadius

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "locations":
    [
    ]
}

Get locations within a specified bounding box

Returns locations within a bounding box specified by two coordinates.

The calculated center of the request's bounding box is considered the geographic center of the location request for sorting returned locations.

If a zoomLevel is provided and the parameter reductionMode is set to UNIFORM, only an approximately uniformly distributed subset of locations (adjustable via service configuration and per location group) is returned.

If you are looking for locations in an autocomplete context or addresses, GET /locationsAutocomplete has to be used instead.

Authorizations:
MSP
query Parameters
neLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

North-east boundary coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

swLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

South-west boundary coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

name
string non-empty

Filter by name.

iD
string
Default: "NONE"
Enum: "NONE" "WALK" "LD"

Use WALK or LD to include the walking distance or the linear distance between the centroid of the request's geographical location boundary and the locations in the result. If parameter idLatLng is set, its value is used instead of the centroid of the request's geographical location boundary. If WALK is used, only the first N locations are considered for the distance calculation. If no valid walking route could be found, the travel distance is omitted. The value of N depends on the service configuration and defaults to 10. NONE to not include any distance calculations due to the additional costs.

idLatLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Reference coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits. If parameter iD is set and not NONE, either this parameter is used as reference parameter for calculation of location distances, or if this parameter is omitted the centroid of the location request geometry is used.

sort
string
Default: "AUTO"
Enum: "AUTO" "CENTER"

Returned locations are always sorted by the distance to a reference coordinate. The preferred coordinate to be used as the reference coordinate for determining the sort order can be specified by this parameter.

AUTO: If parameter iD (include distance) is not set to NONE and idLatLng is specified, idLatLng is chosen as the reference coordinate for sorting, otherwise the geographic center of the location request is chosen as the reference coordinate for sorting. CENTER: The geographic center of the location request is chosen as the reference coordinate for sorting.

interactable
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is defined as interactable. If this parameter is omitted, no filter is applied. If INCLUDE, only locations defined as interactable will be returned. If EXCLUDE, only locations not defined as interactable will be returned.

limit
integer <int32> >= 1

Maximum number of returned locations.

locationGroups
Array of strings

A comma separated list of TSP specific location group ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible location groups are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown location group ids will be ignored and do not result in an error.

time
string <date-time>

Reference time used to determine the availability of locations with time based constraints. If set, only "open" locations will be returned for this point in time.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

productSelectionEligible
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is eligible for product selection.

If this parameter is omitted, no filter is applied. If INCLUDE, only locations eligible for product selection will be returned. If EXCLUDE, only locations not eligible for product selection will be returned.

reductionMode
string
Default: "CLUSTER"
Enum: "CLUSTER" "UNIFORM"

This parameter only applies if a zoomLevel is provided and determines how the resulting locations are reduced so they can be displayed for the given zoom level. If omitted or explicitly set to CLUSTER, locations are clustered, if needed. If set to UNIFORM, an approximately uniformly distributed subset of locations (adjustable via service configuration and per location group) is returned.

zoomLevel
integer [ 0 .. 20 ]

Current zoom level of the web map used for clustering and deciding whether records are included in the result. If the zoom level parameter is not specified, no clustering or filtering will occur. Depending on the web map, zoom level may be in the range from 0 to 20. Please refer to http://wiki.openstreetmap.org/wiki/Zoom_levels and https://developers.google.com/maps/documentation/javascript/maxzoom

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

422

The request was well-formed but was unable to be followed due to semantic errors.

500

General error.

503

Service is temporarily unavailable.

get /locationsByBoundingbox
http://fluidtime.services/api/msp/locationsByBoundingbox

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "locations":
    [
    ]
}

Get locations within a specified rectangle on a geographic projection

Returns locations within a rectangle specified by four coordinates designating its corners. The coordinates have to be sorted by longitude from west to east. The order of 2 coordinates with the same longitude can be arbitrary. This definition of the coordinates' sequence is necessary to detect a rectangle which crosses the antimeridian.

The calculated center of the request's rectangle is considered the geographic center of the location request for sorting returned locations.

If a zoomLevel is provided and the parameter reductionMode is set to UNIFORM, only an approximately uniformly distributed subset of locations (adjustable via service configuration and per location group) is returned.

If you are looking for locations in an autocomplete context or addresses, GET /locationsAutocomplete has to be used instead.

Authorizations:
MSP
query Parameters
latLng0
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Most western corner coordinate of the rectangle.

latLng1
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Second most western corner coordinate of the rectangle.

latLng2
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Second most eastern corner coordinate of the rectangle.

latLng3
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Most eastern corner coordinate of the rectangle.

name
string non-empty

Filter by name.

iD
string
Default: "NONE"
Enum: "NONE" "WALK" "LD"

Use WALK or LD to include the walking distance or the linear distance between the centroid of the request's geographical location boundary and the locations in the result. If parameter idLatLng is set, its value is used instead of the centroid of the request's geographical location boundary. If WALK is used, only the first N locations are considered for the distance calculation. If no valid walking route could be found, the travel distance is omitted. The value of N depends on the service configuration and defaults to 10. NONE to not include any distance calculations due to the additional costs.

idLatLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Reference coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits. If parameter iD is set and not NONE, either this parameter is used as reference parameter for calculation of location distances, or if this parameter is omitted the centroid of the location request geometry is used.

sort
string
Default: "AUTO"
Enum: "AUTO" "CENTER"

Returned locations are always sorted by the distance to a reference coordinate. The preferred coordinate to be used as the reference coordinate for determining the sort order can be specified by this parameter.

AUTO: If parameter iD (include distance) is not set to NONE and idLatLng is specified, idLatLng is chosen as the reference coordinate for sorting, otherwise the geographic center of the location request is chosen as the reference coordinate for sorting. CENTER: The geographic center of the location request is chosen as the reference coordinate for sorting.

interactable
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is defined as interactable. If this parameter is omitted, no filter is applied. If INCLUDE, only locations defined as interactable will be returned. If EXCLUDE, only locations not defined as interactable will be returned.

limit
integer <int32> >= 1

Maximum number of returned locations.

locationGroups
Array of strings

A comma separated list of TSP specific location group ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible location groups are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown location group ids will be ignored and do not result in an error.

time
string <date-time>

Reference time used to determine the availability of locations with time based constraints. If set, only "open" locations will be returned for this point in time.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

productSelectionEligible
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is eligible for product selection.

If this parameter is omitted, no filter is applied. If INCLUDE, only locations eligible for product selection will be returned. If EXCLUDE, only locations not eligible for product selection will be returned.

reductionMode
string
Default: "CLUSTER"
Enum: "CLUSTER" "UNIFORM"

This parameter only applies if a zoomLevel is provided and determines how the resulting locations are reduced so they can be displayed for the given zoom level. If omitted or explicitly set to CLUSTER, locations are clustered, if needed. If set to UNIFORM, an approximately uniformly distributed subset of locations (adjustable via service configuration and per location group) is returned.

zoomLevel
integer [ 0 .. 20 ]

Current zoom level of the web map used for clustering and deciding whether records are included in the result. If the zoom level parameter is not specified, no clustering or filtering will occur. Depending on the web map, zoom level may be in the range from 0 to 20. Please refer to http://wiki.openstreetmap.org/wiki/Zoom_levels and https://developers.google.com/maps/documentation/javascript/maxzoom

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

422

The request was well-formed but was unable to be followed due to semantic errors.

500

General error.

503

Service is temporarily unavailable.

get /locationsByRectangle
http://fluidtime.services/api/msp/locationsByRectangle

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "locations":
    [
    ]
}

Get locations near a reference coordinate

Returns a specified number of locations near a given reference coordinate cLatLng.

The value of cLatLng is considered the geographic center of the location request for sorting returned locations.

If you are looking for locations in an autocomplete context or addresses, GET /locationsAutocomplete has to be used instead.

Authorizations:
MSP
query Parameters
cLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Center coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

limit
integer <int32> [ 1 .. 1000 ]
Default: 10

Maximum number of returned locations.

name
string non-empty

Filter by name.

iD
string
Default: "NONE"
Enum: "NONE" "WALK" "LD"

Use WALK or LD to include the walking distance or the linear distance between the centroid of the request's geographical location boundary and the locations in the result. If parameter idLatLng is set, its value is used instead of the centroid of the request's geographical location boundary. If WALK is used, only the first N locations are considered for the distance calculation. If no valid walking route could be found, the travel distance is omitted. The value of N depends on the service configuration and defaults to 10. NONE to not include any distance calculations due to the additional costs.

idLatLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Reference coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits. If parameter iD is set and not NONE, either this parameter is used as reference parameter for calculation of location distances, or if this parameter is omitted the centroid of the location request geometry is used.

sort
string
Default: "AUTO"
Enum: "AUTO" "CENTER"

Returned locations are always sorted by the distance to a reference coordinate. The preferred coordinate to be used as the reference coordinate for determining the sort order can be specified by this parameter.

AUTO: If parameter iD (include distance) is not set to NONE and idLatLng is specified, idLatLng is chosen as the reference coordinate for sorting, otherwise the geographic center of the location request is chosen as the reference coordinate for sorting. CENTER: The geographic center of the location request is chosen as the reference coordinate for sorting.

interactable
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is defined as interactable. If this parameter is omitted, no filter is applied. If INCLUDE, only locations defined as interactable will be returned. If EXCLUDE, only locations not defined as interactable will be returned.

locationGroups
Array of strings

A comma separated list of TSP specific location group ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible location groups are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown location group ids will be ignored and do not result in an error.

time
string <date-time>

Reference time used to determine the availability of locations with time based constraints. If set, only "open" locations will be returned for this point in time.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

productSelectionEligible
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is eligible for product selection.

If this parameter is omitted, no filter is applied. If INCLUDE, only locations eligible for product selection will be returned. If EXCLUDE, only locations not eligible for product selection will be returned.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /locationsNearby
http://fluidtime.services/api/msp/locationsNearby

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "locations":
    [
    ]
}

Get a location by its name Deprecated

Returns a specific number of locations by the specified parameters.

If parameter iD (include distance) is specified, locations are sorted by the distance to idLatLng.

If you are looking for locations in an autocomplete context or addresses, GET /locationsAutocomplete has to be used instead.

Marked as deprecated. Use GET /locationsAutocomplete instead.

Authorizations:
MSP
query Parameters
name
required
string non-empty

Filter locations by name.

iD
string
Default: "NONE"
Enum: "NONE" "WALK" "LD"

Use WALK or LD to include the walking distance or the linear distance between the centroid of the request's geographical location boundary and the locations in the result. If parameter idLatLng is set, its value is used instead of the centroid of the request's geographical location boundary. If WALK is used, only the first N locations are considered for the distance calculation. If no valid walking route could be found, the travel distance is omitted. The value of N depends on the service configuration and defaults to 10. NONE to not include any distance calculations due to the additional costs.

idLatLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Reference coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits. If parameter iD is set and not NONE, either this parameter is used as reference parameter for calculation of location distances, or if this parameter is omitted the centroid of the location request geometry is used.

interactable
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is defined as interactable. If this parameter is omitted, no filter is applied. If INCLUDE, only locations defined as interactable will be returned. If EXCLUDE, only locations not defined as interactable will be returned.

locationGroups
Array of strings

A comma separated list of TSP specific location group ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible location groups are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown location group ids will be ignored and do not result in an error.

time
string <date-time>

Reference time used to determine the availability of locations with time based constraints. If set, only "open" locations will be returned for this point in time.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

productSelectionEligible
string
Enum: "INCLUDE" "EXCLUDE"

Filters the resulting locations on whether the corresponding location group is eligible for product selection.

If this parameter is omitted, no filter is applied. If INCLUDE, only locations eligible for product selection will be returned. If EXCLUDE, only locations not eligible for product selection will be returned.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /locations
http://fluidtime.services/api/msp/locations

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "locations":
    [
    ]
}

Get location details

Returns the details of the location specified by the given identifier. If departure monitor data is available to the location, it is contained by the stop attribute in the result. A location may include bookable products including additional information for that product. They are attached, if a product can be booked based on a location (e.g. car sharing cars) and no route is required (like for ride hailing products).

Authorizations:
MSP
path Parameters
identifier
required
string non-empty

A string which uniquely identifies a location.

query Parameters
searchSession
string <uuid>

Defines a search session to optimise costs, if an external provider supports this.

A search session begins with the user requesting location candidates as part of a location autocomplete search and ends with requesting location details via location id. The search session is generated by the server. Each session can have multiple location autocomplete requests followed by exactly one location details request. A session is considered complete thereafter.

An ongoing search session will expire after some time depending on the external provider.

ttWindow
string ^([-+]?)P(?:([-+]?[0-9]+)D)?(T(?:([-+]?[0-9]+)H)?(?:([-+]?[0-9]+)M)?(?:([-+]?[0-9]+)(?:[.,]([0-9]{0,9}))?S)?)?$

Positive duration from now on establishing a time window within arrival and departure times of transit services should be included, if available for the specified location.

ttMaxTimes
integer <int32> [ 1 .. 500 ]
Default: 30

Maximum number of stop time entries per transit service timetable to be included, if available for the specified location.

ttMode
string
Default: "CHRONOLOGICAL"
Enum: "CHRONOLOGICAL" "SERVICE"

Determines the format in which departure and arrival times for a stop are returned.

CHRONOLOGICAL: Departure and arrival times are returned as a flat list in chronological order in stop.timetable.

SERVICE: Departure and arrival times are grouped by transit service and returned in stop.schedule.

ttType
string
Enum: "ALL" "ARR" "DEP"

Filters stop time types of timetable entries. Either all time types, only arrival times or only departure times can be selected.

ttTransportationTypes
Array of strings (Transportation)
Items Enum: "WALK" "BIKE" "MOTORCYCLE" "CAR" "BUS" "COACH" "TROLLEY_BUS" "CABLE_CAR" "FUNICULAR" "ROPEWAY" "ELEVATOR" "ESCALATOR" "MOVING_WALKWAY" "TRAIN" "TRAM" "SUBWAY" "MONORAIL" "COG_RAIL" "BOAT" "FERRY" "PLANE" "SCOOTER"

Transportation types to include.

ttTransitServices
Array of strings

Id of transit services to include.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

get /locations/{identifier}
http://fluidtime.services/api/msp/locations/{identifier}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "address":
    {
    },
  • "bikesharingStation":
    {
    },
  • "businessHours":
    {
    },
  • "contentLocale": "string",
  • "coordinate":
    {
    },
  • "description": "string",
  • "identifier": "string",
  • "images":
    [
    ],
  • "locationGroupId": "string",
  • "locations":
    [
    ],
  • "name": "string",
  • "parking":
    {
    },
  • "paymentOptions":
    [
    ],
  • "priceInfo": "string",
  • "products":
    [
    ],
  • "shortDescription": "string",
  • "situations":
    [
    ],
  • "stop":
    {
    },
  • "termsOfServiceUrl": "string",
  • "tspId": "string",
  • "vehicle":
    {
    }
}

Product

Get ride products

Returns all ride products (offers) matching the provided parameters.

Authorizations:
MSP
query Parameters
oLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Origin coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

dLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Destination coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

time
string <date-time>

Reference time used to indicate desired arrival or departure.

timeContext
string
Enum: "ARR" "DEP"

Indicates, whether the time parameter is meant to be an arrival or departure time.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

Ride products.

400

The provided input parameters are not valid.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

get /products/ride
http://fluidtime.services/api/msp/products/ride

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "productList":
    [
    ]
}

Get vehicle products

Returns all vehicle products (offers) matching the provided parameters.

Authorizations:
MSP
query Parameters
tspId
required
string ^[a-zA-Z0-9_-]{1,16}$

Non enumerable TSP id restricting the result set.

pickupTime
string <date-time>

Time to pickup a vehicle. If not set, NOW should be taken.

Time has to be within a preconfigured tolerance before NOW or after NOW. The default configuration of this tolerance is PT1H.

The pickup time has to be before the return time. If the pickup time is before the return time an error is raised.

returnTime
string <date-time>

Time to return a vehicle. Depending on the TSP, this has to be set or not.

The return time has to be after the pickup time. If the return time is before the pickup time an error is raised.

pickupLocationId
required
string

Pickup location identifier. Can be retrieved via location calls.

returnLocationId
string

Return location identifier. Can be retrieved via location calls.

Depending on the TSP, this has to be set or not. If not set, the same value as in pickupLocationId should be taken.

acrissCodes
Array of strings

Comma separated list of acriss codes to filter.

corporateNumber
string

Corporation number.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

Vehicle products.

400

The provided input parameters are not valid.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

422

The request was well-formed but was unable to be followed due to semantic errors.

500

General error.

503

Service is temporarily unavailable.

get /products/vehicle
http://fluidtime.services/api/msp/products/vehicle

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "productList":
    [
    ]
}

Get ticket products

Returns all bookable ticket products available from the specified TSP.

Authorizations:
MSP
query Parameters
tspId
required
string ^[a-zA-Z0-9_-]{1,16}$

Non enumerable TSP id restricting the result set.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

Ticket products.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

500

General error.

503

Service is temporarily unavailable.

get /products/ticket
http://fluidtime.services/api/msp/products/ticket

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "productList":
    [
    ]
}

Reporting

Get a report for bookings

Returns a report for bookings within the specified interval.

Authorizations:
MSP
query Parameters
aggregationInterval
string
Enum: "MINUTE" "HOUR" "DAY" "WEEK" "MONTH" "YEAR"

The preferred time unit a time series should use for aggregation. If not provided, a meaningful default is set.

startDate
string <date-time>

Defines the start of the interval, the request considers. If not set, a meaningful default applies.

endDate
string <date-time>

Defines the end of the interval, the request considers. If not set, all entries to now will be considered.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

header Parameters
Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

422

The request was well-formed but was unable to be followed due to semantic errors.

500

General error.

get /report/bookings/timeseries
http://fluidtime.services/api/msp/report/bookings/timeseries

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "timeSeries":
    [
    ],
  • "aggregationInterval": "MINUTE"
}

Route

Get a route with multiple trip suggestions

Returns suggestions for possible trips to accomplish the requested route request. Each trip represents an alternative to choose from. A trip may be divided into legs by using defined waypoints between legs.

Clients must either set a location id or a coordinate parameter for origin and destination. It is not allowed to set both parameters for origin or destination.

The main properties of a trip are origin and destination. leg in destination describes the way from the last waypoint to the destination. If no waypoints are set, this leg describes the way from origin to destination.

Each waypoint contains a leg that describes the way from the previous waypoint (if available, otherwise from origin) to the waypoint itself.

All trips contain a simplified encoded polyline. The legs' polylines are more detailed.

Authorizations:
MSP
query Parameters
oLatLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Origin coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

dLatLng
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Destination coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

oLocationId
string non-empty

Origin location id which uniquely identifies a location.

dLocationId
string non-empty

Destination location id which uniquely identifies a location.

time
string <date-time>

Reference time used to indicate desired arrival or departure.

timeContext
string
Enum: "ARR" "DEP"

Indicates, whether the time parameter is meant to be an arrival or departure time.

transportationTypes
Array of strings (Transportation)
Items Enum: "WALK" "BIKE" "MOTORCYCLE" "CAR" "BUS" "COACH" "TROLLEY_BUS" "CABLE_CAR" "FUNICULAR" "ROPEWAY" "ELEVATOR" "ESCALATOR" "MOVING_WALKWAY" "TRAIN" "TRAM" "SUBWAY" "MONORAIL" "COG_RAIL" "BOAT" "FERRY" "PLANE" "SCOOTER"

Transportation types to include. If no routes can be found with the provided parameter, routes with alternative transportation types may be included.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

sort
Array of strings
Default: "DURATION_ASC"
Items Enum: "ARRIVAL_TIME_ASC" "ARRIVAL_TIME_DESC" "RELEVANCE_ASC" "RELEVANCE_DESC" "DEPARTURE_TIME_ASC" "DEPARTURE_TIME_DESC" "DURATION_ASC" "DURATION_DESC" "WALKING_TIME_ASC" "WALKING_TIME_DESC" "CHANGE_COUNT_ASC" "CHANGE_COUNT_DESC"

Determines the sort order of the result trips.

paymentType
string
Enum: "INVOICE" "PAY_ON_SITE"

Filter the result to contain only products payable with the specified payment type. Depending on the TSP, this may not be supported.

viaLocationIds
Array of strings

One or more (comma-separated) location ids that are used as via locations, i.e. locations to include along the route between the origin and destination. This parameter is not supported by all routers. Therefore not all returned trips may reflect this parameter.

includeNavigationInstructions
boolean
Default: false

Indicates whether to include navigation instructions in the route calculations and in the output or not.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

409

The provided data is conflicting or would result in a conflict if applied.

422

The request was well-formed but was unable to be followed due to semantic errors.

500

General error.

503

Service is temporarily unavailable.

get /route
http://fluidtime.services/api/msp/route

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "trips":
    [
    ]
}

Get a footpath route with a single trip

Returns a suggestion for a possible walking trip to accomplish the requested route request. This will return either 0 or 1 trip.

Authorizations:
MSP
query Parameters
oLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Origin coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

dLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Destination coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

includeNavigationInstructions
boolean
Default: false

Indicates whether to include navigation instructions in the route calculations and in the output or not.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

User-Reference
string

Optional, arbitrary reference to relate certain API calls to users. This may be used for reportings and the grouping of bookings (e.g. to query bookings by a user).

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /footpath
http://fluidtime.services/api/msp/footpath

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "trip":
    {
    }
}

Situation

Get situations

Get situations based on different criteria.

Authorizations:
MSP
query Parameters
tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

situationTypes
Array of strings (SituationType)
Items Enum: "AIR_QUALITY" "WEATHER" "TRAFFIC" "MESSAGE" "TOLLING"

Only include given situation types.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /situations
http://fluidtime.services/api/msp/situations

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "situations":
    [
    ]
}

Get situations within a specified bounding box

Returns situations within a bounding box specified by two coordinates. Returned situations are sorted by the distance to the calculated center of the request's bounding box. Situations without coordinates will not be returned.

Authorizations:
MSP
query Parameters
neLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

North-east boundary coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

swLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

South-west boundary coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

zoomLevel
integer [ 0 .. 20 ]

Current zoom level of the web map used for clustering and deciding whether records are included in the result. If the zoom level parameter is not specified, no clustering or filtering will occur. Depending on the web map, zoom level may be in the range from 0 to 20. Please refer to http://wiki.openstreetmap.org/wiki/Zoom_levels and https://developers.google.com/maps/documentation/javascript/maxzoom

situationTypes
Array of strings (SituationType)
Items Enum: "AIR_QUALITY" "WEATHER" "TRAFFIC" "MESSAGE" "TOLLING"

Only include given situation types.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /situationsByBoundingbox
http://fluidtime.services/api/msp/situationsByBoundingbox

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "situations":
    [
    ]
}

Get situations within a specified rectangle on a geographic projection

Returns situations within a rectangle specified by four coordinates designating its corners. The coordinates have to be sorted by longitude from west to east. The order of 2 coordinates with the same longitude can be arbitrary. This definition of the coordinates' sequence is necessary to detect a rectangle which crosses the antimeridian. Returned locations are sorted by the distance to the calculated center of the request's rectangle. Situations without coordinates will not be returned.

Authorizations:
MSP
query Parameters
latLng0
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Most western corner coordinate of the rectangle.

latLng1
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Second most western corner coordinate of the rectangle.

latLng2
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Second most eastern corner coordinate of the rectangle.

latLng3
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Most eastern corner coordinate of the rectangle.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

zoomLevel
integer [ 0 .. 20 ]

Current zoom level of the web map used for clustering and deciding whether records are included in the result. If the zoom level parameter is not specified, no clustering or filtering will occur. Depending on the web map, zoom level may be in the range from 0 to 20. Please refer to http://wiki.openstreetmap.org/wiki/Zoom_levels and https://developers.google.com/maps/documentation/javascript/maxzoom

situationTypes
Array of strings (SituationType)
Items Enum: "AIR_QUALITY" "WEATHER" "TRAFFIC" "MESSAGE" "TOLLING"

Only include given situation types.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /situationsByRectangle
http://fluidtime.services/api/msp/situationsByRectangle

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "situations":
    [
    ]
}

Get situations near a reference coordinate

Returns a specified number of situations near a given reference coordinate. Returned situations are sorted by the distance to the given reference coordinate. Situations without coordinates will not be returned.

Authorizations:
MSP
query Parameters
cLatLng
required
string ^[-+]?([1-8]?\d(\.\d{0,7})?|90(\.0{0,7})?),[-+]?(180(\.0{0,7})?|((1[0-7]\d)|([1-9]?\d))(\.\d{0,7})?)$

Center coordinate represented by a "lat,lon" in the format "[-90,90],[-180,180]" allowing a numeric format with a maximum precision of 7 decimal digits.

limit
integer <int32> [ 1 .. 1000 ]
Default: 10

Maximum number of returned situations.

tsps
Array of strings

A comma separated list of TSP ids restricting the result set. If this parameter is omitted, no restriction takes effect and therefore records for all eligible TSPs are returned. If this parameter is set, but is an empty list, no records will be returned. Unknown TSP ids will be ignored and do not result in an error.

situationTypes
Array of strings (SituationType)
Items Enum: "AIR_QUALITY" "WEATHER" "TRAFFIC" "MESSAGE" "TOLLING"

Only include given situation types.

header Parameters
Accept-Language
string

The desired language for response content. RFC 2616

Request-UUID
string

Request UUID.

Responses

200

OK.

400

The provided input parameters are not valid.

404

The requested resource is not available.

500

General error.

503

Service is temporarily unavailable.

get /situationsNearby
http://fluidtime.services/api/msp/situationsNearby

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "situations":
    [
    ]
}