Skip to content
LoginRegister
DEENFRIT
Home
Open data platform mobility Switzerland
  2. Cookbook
  3. Location Information Service

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.

API Explorer

You can try your own requests – direct link to the API explorer.

Request

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

The main uses are stop and coord. poi will become more important over time (namely for car parks and sharers).

Sharing vehicles (e-scooters, bicycles, cars) and charging stations can now be retrieved as POIs (see under ojp:PointOfInterestFilter below).

For address, the exact location name must first be determined with general input. Then exactly this name and the type “address” must be searched for. Only then will the address code be returned. However, this is a special case that should not normally be used. Neither address code nor TopographicPlaceRef have any meaningful meaning outside the searches in OJP.

ojp:Usage 0:* Indicates what the place (location) will be used for.

The following values exist:

  • origin
  • via
  • destination

This feature is 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.

 
ojp:OperatorFilter 0:1 A filter by operator.

Not planned

 n/a
ojp:TopographicPlaceRef 0:1 A filter by reference to a location. If at least one reference is set, the service only returns objects situated within the specified locations.

ojp:PointOfInterestFilter 0:1 Now (since August 2022), sharing vehicles (e-scooters, bicycles, cars) and charging stations can be called up within a radius or rectangle.

Structure as shown in the example on the right:

  • ojp:Tag: always amenity
  • For ojp:Value: use one of escooter_rental, bicycle_rental, car_sharing or charging_station.

Note: The query should be combined with a GeoRestriction (Circle or Rectangle) and not with LocationName, GeoPosition or PlaceRef.

ojp:Language 0:1 Preferred language for return values.

Planned for a future release.

 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).

The selection of the best candidates for the hit list is determined after the input text matches the entire dataset. The probability is determined by the number of matching trigrams into which the terms can be broken down and the remainder that does not match. If there is a complete match, i.e. no remainder, the candidate has a perfect match and receives the maximum probability 1. If there is still a remainder, this leads to a deduction of points. The hits found in this way can then be influenced by various evaluation criteria and quality and sorting order. Hits can be modified by region (municipality code), type (stop, address, city, POI,…), serving means of transport or a relevance value.

 
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.