Skip to content

Location Information Service

Location Information Service

The Location Service returns multiple locations in response to a request. The main input data are as follows:

  • Text input
  • Permitted object types
  • Geographical restrictions/weighting
  • Additional restrictions

The output is a list of objects with names, geographical position, attributes and a probability rating.

If the LocationInformationRequest is used without the LocationName, but with GeoPosition, Circle or Rectangle, only type=”stop” is supported. In addition, GeoPosition with type=”address” returns exactly one address with HausnummerRequest.

Element Cardinality Description Example
RequestTimestamp 1:1  Timestamp of the request. Preferably in UTC
MessageIdentifier 0:1 Unique message ID. We would like this ID to be issued in a strictly monotonically increasing order.
ojp:InitialInput/ojp:LocationName 0:1 The name of the object. If none is provided, other criteria will be used in the search.

Where different designations are common, it is possible to search for any of them. For example, it is possible to search for “Basel” as well as “Bâle CFF”. For stops that have names in multiple languages, it also works if searching in only one language. For example, “Biel/Bienne” can be found with a request for “Biel” or “Bienne”.

ojp:InitialInput/ojp:GeoPosition 0:1 The requested position with GPS coordinates (WGS84)

ojp:InitialInput/GeoRestriction/Circle 0:1  Restrict the search to a particular radius. For example, if type is correctly selected, all the stops within a certain radius can be shown. Coordinates in WGS84.

ojp:InitialInput/GeoRestriction/Rectangle 0:1  Restrict the search to a particular rectangle. Coordinates in WGS84.

ojp:/ojp:PlaceRef 0:1 A reference to a place. See separate table
ojp:Restrictions 0:1 The restrictions that are to be applied See separate table

Restrictions for LocationInformationRequest

Element Cardinality Description Example
ojp:Type 0:*  The type of objects to be returned.

The following types exist:

  • stop
  • address
  • poi
  • coord
  • topographicPlace
ojp:Usage 0:* Indicates what the place (location) will be used for.

The following values exist:

  • origin
  • via
  • destination

TODO: This feature is currently not supported.

n/a
ojp:PtModes  0:1 Contains a Boolean exclude element. If true, the modes are excluded, otherwise they are included.  How this is done is described in a separate section.

See also section on PtMode

TODO: planned

 

ojp:OperatorFilter 0:1 A filter by operator.

Not planned

n/a
ojp:TopographicPlaceRef 0:1 A filter by reference to a location.

TODO: planned

TODO
ojp:PointOfInterestFilter 0:1 A filter by POI

Not planned

n/a
ojp:Language 0:1 TODO: planned n/a
ojp: NumberOfResults 0:1 The quantity of results.

Important: If a result group is cut with equal probability (>0.5), the server returns all results. This means that the actual number of results can deviate from the desired result. The reason for this is that with NumberOfResults=1 and input “St. Gallen, Haggen”, two stops must actually be returned: “St. Gallen, Haggen” and “St. Gallen Haggen”.

IncludePtModes 0:1 Requests the service to return the available modes for each stop. The default value is false.

PlaceRef

Element Cardinality Description Example
ojp: StopPointRef 0:1 Reference to a ScheduledStopPoint.

We do not recommend using this element because there is uncertainty about which ID is required.

ojp:StopPlaceRef 0:1 Reference to a stop. Based on the DiDok number. Using StopPlaces yields very quick search results.

ojp:GeoPosition 0:1 Geoposition in longitude/latitude

ojp:PlaceRef/ojp:LocationName 0:1 Ignored n/a

PTMode

The PTModes are the modes of transport.

The following values exist at PTMode level (there are more but we do not use them; and of the ones listed below we currently do not use all):

  • unknown
  • rail
  • coach
  • suburbanRail
  • urbanRail
  • metro
  • underground
  • bus
  • trolleyBus
  • tram
  • water
  • air
  • telecabin
  • funicular
  • taxi
  • selfDrive
  • all

The SubModes are:

AirSubmode

  • Not currently used

BusSubmode

  • regionalBus
  • expressBus
  • localBus
  • postBus
  • sightseeingbus
  • shuttleBus
  • railReplacementBus
  • demandAndResponseBus

CoachSubmode

  • internationalCoachService
  • nationalCoachService
  • regionalCoachService
  • touristCoachService

FunicularSubmode

  • funicular

MetroSubmode

  • urbanRailway
  • metro

TramSubmode

  • cityTram
  • regionalTram
  • localTramService
  • sightseeingTram

TelecabinSubmode

  • chairLift
  • dragLift
  • smallTelecabin
  • lift
  • telecabin
  • cableCar

RailSubmode

  • hightSpeedRailService
  • longDistanceTrain
  • interRegionalRailService
  • carTransportRailService
  • sleeperRailService
  • regionalRail
  • touristRailway
  • railShuttle
  • suburbanRailway
  • replacementRailService
  • local
  • interbational (yes, with a b; will be changed at some point)

WaterSubmode

  • internationalCarFerryService
  • nationalCarFerryService
  • regionalCarFerryService
  • localCarFerryService
  • internationalPassengerFerry
  • regionalPassengerFerry
  • localPassengerFerry
  • postBoat
  • trainFerry

 

Response

The response is packed into an ojp:OJPLocationInformationDelivery element

Element Cardinality Description Example
siri:ResponseTimestamp 1:1 The timestamp of the response
siri:RequesteMessageRef 0:1 Reference to the request message
siri:Status 1:1 The status of the response; true means that the request has been processed.
ojp:CalcTime 1:1 The calculation time in milliseconds
ojp:Location 1:1 Contains the individual ojp:Location responses
ojp:Location/ojp:Location 1:1 The individual responses. It is somewhat irritating that two hierarchically different elements have the same name but it’s just how it is for now.
 ojp:Complete 1:1 Indicates whether the current location is complete or requires further refinement. If refinement is required, resubmit in a LocationInformationRequest with greater precision.
ojp:Probability 1:1 The probability that the respective location corresponds to the one that is being requested.

The results are sorted in descending order by probability (most relevant first).

 

ojp:Mode 0:* The relevant modes for the location

ojp:Location

A location can be one of the following:

  • StopPoint: A stop or a platform
  • StopPlace: A stop in the physical sense
  • TopographicPlace: A location
  • PointOfInterest: A POI. Please note: None of these are currently available.
  • Address: An address
Element Cardinality Description Example
ojp:StopPlace 0:1 A stop in the physical sense
ojp:StopPoint 0:1 A stop or a platform

None of these should currently be returned.

This feature is currently not supported.

ojp:TopographicPlace 0:1 A location

ojp:PointOfInterest 0:1 A POI. Please note: None of these are currently available.

TODO: PointOfInterest is not currently supported.

ojp:Address 0:1 An address

 

ojp:LocationName 0:1 The name of the location

 

ojp:GeoPosition 0:1 The coordinates

 

The example shows what comes back if no coordinates are available. The precision is then set to half the world circumference. Of course we try to avoid such cases.

 

ojp:Location/ojp:StopPoint

This feature is currently not supported.

ojp:Location/ojp:StopPlace

Element Cardinality Description Example
ojp:StopPlaceRef  1:1 The reference to the stop. Currently: DiDok number.
ojp:StopPlaceName 1:1 The name of the stop
 
ojp:TopographicPlaceRef 1:1 The reference to the location.

ojp:Location/ojp:TopographicPlace

Element Cardinality Description Example
ojp:TopographicPlaceRef  1:1 The reference to the location.
ojp:TopographicPlaceName 1:1 The name of the location.