OJPLocationInformationRequest 2.0

#AutoTranslate

Brief Description

The Location Information Service (LIR) in accordance with OJP 2.0 returns various locations in response to a request. The main input data (request) are:

  • textual input
  • Permitted object types
  • Geographical restrictions/weighting
  • Other restrictions

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

If the LocationInformationRequest is used without a name, but with GeoPosition, Circle or Rectangle, the types=’address,’ ‘stop’ & ‘poi’ are supported. In addition, GeoPosition with filter type=’address returns exactly one address with a house number.

Technical Description

API Explorer and other references

You can try out your own requests – Open API Explorer.
Details of the individual parameters for the Request and the Response are also online on the official GitHub page by VDV.

Request

Example of a LocationInformationRequest in accordance with OJP 2.0:

<?xml version="1.0" encoding="UTF-8"?>
<OJP xmlns="http://www.vdv.de/ojp" xmlns:siri="http://www.siri.org.uk/siri" version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vdv.de/ojp ../../../../Downloads/OJP-changes_for_v1.1%20(1)/OJP-changes_for_v1.1/OJP.xsd">
    <OJPRequest>
        <siri:ServiceRequest>
            <siri:RequestTimestamp>2024-11-26T16:03:09Z</siri:RequestTimestamp>
            <siri:RequestorRef>SKIplusDemo</siri:RequestorRef>
            <OJPLocationInformationRequest>
                <siri:RequestTimestamp>2024-11-26T16:03:09Z</siri:RequestTimestamp>
                <siri:MessageIdentifier>LIR-1a</siri:MessageIdentifier>
                <InitialInput>
                    <Name>Bern</Name>
                </InitialInput>
                <Restrictions>
                    <Type>stop</Type>
                    <NumberOfResults>5</NumberOfResults>
                </Restrictions>
            </OJPLocationInformationRequest>
        </siri:ServiceRequest>
    </OJPRequest>
</OJP>

Description of the elements of the OJPLocationInformationRequests:

Item Cardinality Description Example
siri:RequestTimestamp 1:1 The timestamp of the request, in UTC.
<siri:RequestTimestamp>2024-11-26T16:03:09Z</siri:RequestTimestamp>
siri:MessageIdentifier 0:1 Unique ID of the message, to identify the response.
<siri:MessageIdentifier>LIR-1a</siri:MessageIdentifier>
InitialInput/Name 0:1 The name of the object. If none is specified, other criteria will be used to search.

Where different terms are common, you can search for all of them. For example, it works to search for ‘Basel’ or ‘Bâle CFF’. For example, ‘Biel’ can be found with a request for ‘Biel’ or ‘Bienne’.


<InitialInput>
<Name>Bern</Name>
</InitialInput>

InitialInput/GeoPosition 0:1 The requested position with geo-coordinates (WGS84)
<InitialInput>
<GeoPosition>
<siri:Longitude>8.5545</siri:Longitude>
<siri:Latitude>47.365</siri:Latitude>
</GeoPosition>
</InitialInput>
InitialInput/GeoRestriction/Circle 0:1 Restrict the search to a certain radius. For example, if type is correctly selected, all the stops within a radius can be shown. Coordinates in WGS84.
<GeoRestriction>
<Circle>
<Center>
<siri:Longitude>8.5545</siri:Longitude>
<siri:Latitude>47.365</siri:Latitude>
</Center>
<Radius>500</Radius>
</Circle>
</GeoRestriction>
InitialInput/GeoRestriction/Rectangle 0:1 Restrict the search to a specific rectangle. Coordinates in WGS84.
<InitialInput>
<GeoRestriction>
<Rectangle>
<UpperLeft>
<siri:Longitude>8.54</siri:Longitude>
<siri:Latitude>47.37</siri:Latitude>
</UpperLeft>
<LowerRight>
<siri:Longitude>8.57</siri:Longitude>
<siri:Latitude>47.36</siri:Latitude>
</LowerRight>
</Rectangle>
</GeoRestriction>
</ojp:InitialInput>
PlaceRef 0:1 A reference to a place see separate table
Restrictions 0:1 The restrictions to be used see separate table

PlaceRef

In the case of a request with a PlaceRef the necessary element <Name> is ignored; only the reference number is evaluated in each case.

Item Cardinality Description Example
siri:StopPointRef 0:1 Reference to a ScheduledStopPoint.
Only the SLOID will be used; for foreign StopPoints, the BPUIC number can still be used in the request and in the response.
<PlaceRef>
<siri:StopPointRef>ch:1:sloid:30813</siri:StopPointRef>
<Name>
<Text>Zürich Kreuzplatz</Text>
</Name>
</PlaceRef>
StopPlaceRef 0:1 Reference to a stop. Only the SLOID will be used; for foreign StopPlaces, the BPUIC number can still be used in the request and in the response.
<PlaceRef>
<StopPlaceRef>ch:1:sloid:30813</StopPlaceRef>
<Name>
<Text>Zürich Kreuzplatz</Text>
</Name>
</PlaceRef>
GeoPosition 0:1 Geoposition in Longitude/Latitude
<PlaceRef>
<GeoPosition>
<siri:Longitude>8.5545</siri:Longitude>
<siri:Latitude>47.365</siri:Latitude>
</GeoPosition>
<Name>
<Text>Zürich Kreuzplatz</Text>
</Name>
</PlaceRef>

Restrictions (PlaceParamStructure)

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

There are the following types (PlaceTypeEnumeration):

  • stop
  • address
  • poi
  • location
  • topographicPlace

The main uses are stop and location. POI will become more important over time (particularly for car parks and sharers).

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

For address, the exact name must first be determined using general input. Then the exact name and type ‘address’ must be searched. Only then does the address code return. However, this is a special case and should not normally be used. Neither the address code nor TopographicPlaceRef have any meaning outside of the OJP search.


<Type>stop</Type>

Modes 0:1 Contains a Boolean exclude element. If true, the modes are excluded; otherwise they are included.
Further details: opentransportdata.swiss/…/ojptriprequest
<Modes>
    <Exclude>false</Exclude>
    <PtMode>bus</PtMode>
</Modes>
OperatorFilter 0:1 A filter by operator. In the future with the SBOID. n/a
TopographicPlaceRef 0:1 Used to filter by locations. If at least one reference is set, only objects within the respective locations are searched.
<TopographicPlaceRef>23011901:2</TopographicPlaceRef>
PointOfInterestFilter 0:1 You can use this filter to find relevant locations. 12/2024 Routing with different modes is not currently supported. The following modes will be available in future: Sharing vehicles (e-scooters, bicycles, cars) and charging stations can be retrieved within a radius or rectangle.
Structure as shown in the example on the right:
  • For ‘Tag,’ always ‘amenity’
  • For ‘Value,’ choose ‘escooter_rental,’ ‘bicycle_rental,’ ‘car_sharing’ or ‘charging_station’.

Please note: The query must be combined with a GeoRestriction (Circle or Rectangle) and not with Name, GeoPosition or PlaceRef.

<PointOfInterestFilter>
<PointOfInterestCategory>
<OsmTag>
<Tag>amenity</Tag>
<Value>car_sharing</Value>
</OsmTag>
</PointOfInterestCategory>
</PointOfInterestFilter>
NumberOfResults 0:1 The number of results.

Important: Strings such as ‘St. Gallen Haggen’ and ‘St. Gallen, Haggen’ are equivalent for the search.

If a result group is trimmed with an equal probability (>0.5), the server returns all results. I.e. the actual number of results may differ from the desired result. The reason for this is that if NumberOfResults=1 and ‘St. Gallen, Haggen’ are entered, 2 stops must be returned: ‘St. Gallen, Haggen’ and ‘St. Gallen Haggen’.

<NumberOfResults>10</NumberOfResults>
NumberOfResultsAfter & NumberOfResultsBefore 0:1 The number of results after or before the specified time, regardless of whether the time is at <Origin> or <Destination>.
<NumberOfResults>10</NumberOfResults>
IncludePtModes 0:1 Tells the service to return the available modes for each stop. The default is false.
<IncludePtModes>true</IncludePtModes>

Response

Example of a response:

<?xml version="1.0" encoding="UTF-8"?>
<OJP version="2.0" xmlns:siri="http://www.siri.org.uk/siri" xmlns="http://www.vdv.de/ojp">
    <OJPResponse>
        <siri:ServiceDelivery>
            <siri:ResponseTimestamp>2024-11-26T17:03:09.1541119+01:00</siri:ResponseTimestamp>
            <siri:ProducerRef>MENTZ</siri:ProducerRef>
            <OJPLocationInformationDelivery>
                <siri:ResponseTimestamp>2024-11-26T17:03:09.1542196+01:00</siri:ResponseTimestamp>
                <siri:RequestMessageRef>d5e1d0e3-ba3c-4f3e-b068-105f4d001777</siri:RequestMessageRef>
                <siri:DefaultLanguage>de</siri:DefaultLanguage>
                <CalcTime>2</CalcTime>
                <PlaceResult>
                    <Place>
                        <StopPlace>
                            <StopPlaceRef>ch:1:sloid:7000</StopPlaceRef>
                            <StopPlaceName>
                                <Text xml:lang="de">Bern</Text>
                            </StopPlaceName>
                            <PrivateCode>
                                <System>EFA</System>
                                <Value>111055</Value>
                            </PrivateCode>
                            <TopographicPlaceRef>23006351:1</TopographicPlaceRef>
                        </StopPlace>
                        <Name>
                            <Text xml:lang="de">Bern (Bern)</Text>
                        </Name>
                        <GeoPosition>
                            <siri:Longitude>7.43913</siri:Longitude>
                            <siri:Latitude>46.94883</siri:Latitude>
                        </GeoPosition>
                        <Mode>
                           <PtMode>rail</PtMode>
                        </Mode>
                    </Place>
                    <Complete>true</Complete>
                    <Probability>1</Probability>
                </PlaceResult>
<!-- und so weiter und so fort -->
                <PlaceResult>
                    <Place>
                        <StopPlace>
                            <StopPlaceRef>ch:1:sloid:7062</StopPlaceRef>
                            <StopPlaceName>
                                <Text xml:lang="de">Muri b. Bern</Text>
                            </StopPlaceName>
                            <PrivateCode>
                                <System>EFA</System>
                                <Value>111070</Value>
                            </PrivateCode>
                            <TopographicPlaceRef>23006356:3</TopographicPlaceRef>
                        </StopPlace>
                        <Name>
                            <Text xml:lang="de">Muri b. Bern (Muri b. Bern)</Text>
                        </Name>
                        <GeoPosition>
                            <siri:Longitude>7.48641</siri:Longitude>
                            <siri:Latitude>46.93141</siri:Latitude>
                        </GeoPosition>
                        <Mode>
                            <PtMode>tram</PtMode>
                            <siri:TramSubmode>cityTram</siri:TramSubmode>
                        </Mode>
                        <Mode>
                            <PtMode>bus</PtMode>
                            <siri:BusSubmode>localBus</siri:BusSubmode>
                        </Mode>
                    </Place>
                    <Complete>true</Complete>
                    <Probability>0.851</Probability>
                </PlaceResult>
            </OJPLocationInformationDelivery>
        </siri:ServiceDelivery>
    </OJPResponse>
</OJP>
+

The answer is in a OJPLocationInformationDelivery element packed:

Item Cardinality Description Example
siri:ResponseTimestamp 1:1 The timestamp of the answer
<siri:ResponseTimestamp>2024-11-26T17:03:09.1542196+01:00</siri:ResponseTimestamp>

siri:ProducerRef 0:1 Name of OJP system operator
<siri:ResponseTimestamp>MENTZ</siri:ResponseTimestamp>

siri:RequesteMessageRef 0:1 Arbitrary unambiguous reference to the request that led to this report
<siri:RequestMessageRef>d5e1d0e3-ba3c-4f3e-b068-105f4d001777</siri:RequestMessageRef>

siri:DefaultLanguage 0:1 Default language for text elements.
<siri:DefaultLanguage>de</siri:DefaultLanguage>

CalcTime 0:1 The calculation time in milliseconds
<CalcTime>2</CalcTime>

Place 1:1 Contains the individual place responses
PlaceResult/Place 1:1 Contains the individual Place responses. Here is an example of a response with a StopPlace. This may look slightly different depending on the request. More on other parameters below.

One Place element is returned for each PlaceResult. The number of PlaceResults is related to the request parameters ‘NumberOfResults,’ ‘NumberOfResultsAfter’ and ‘NumberOfResultsBefore’. If a request was made without these parameters, the router can determine the number itself.

<PlaceResult>
<Place>
<StopPlace>
<StopPlaceRef>ch:1:sloid:7000</StopPlaceRef>
<StopPlaceName>
<Text xml:lang="de">Bern</Text>
</StopPlaceName>
...
<TopographicPlaceRef>23006351:1</TopographicPlaceRef>
</StopPlace>
<Name>
<Text xml:lang="de">Bern (Bern)</Text>
</Name>
<GeoPosition>
<siri:Longitude>7.43913</siri:Longitude>
<siri:Latitude>46.94883</siri:Latitude>
</GeoPosition>
<Mode>
<PtMode>rail</PtMode>
</Mode>
</Place>
...
</PlaceResult>
 Complete 1:1 Indicates whether the current place is complete or can be refined further. If refinement is required, enter the ‘Ref’ again in a LocationInformationRequest for a full and detailed response.
<Complete>true</Complete>
Probability 1:1 The probability that the respective location corresponds to the one you are looking for.

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

The selection of the best candidates for the list of hits is determined after the input text matches the entire database. 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, there is a perfect match and the candidate receives the maximum probability 1. If there is still a remainder, points are deducted. The hits found in this way can then be influenced by various evaluation criteria and by quality and sorting order. Hits can be changed based on the region (municipality code), type (stop, address, location, POI, …), serving means of transport or a relevance value.

<Probability>0.927999973</Probability>

 

Mode 0:* The relevant modes for the location
<Mode>
<PtMode>tram</PtMode>
<siri:TramSubmode>cityTram</siri:TramSubmode>
</Mode>
<Mode>
<PtMode>bus</PtMode>
<siri:BusSubmode>localBus</siri:BusSubmode>
</Mode>

Location (Place structure)

Item Cardinality Description Example
StopPlace 1:1 A stop in the physical sense
<StopPlace>
<StopPlaceRef>ch:1:sloid:7483</StopPlaceRef>
<StopPlaceName>
<Text xml:lang="de">Spiez</Text>
</StopPlaceName>
<TopographicPlaceRef>23006768:5</TopographicPlaceRef>
</StopPlace>
TopographicPlace 1:1

A place with a name and an ID.

<TopographicPlace>
<TopographicPlaceCode>suburbID:8136088:6:Bernhardsdorf:5439812:10881110:MRCV</TopographicPlaceCode>
<TopographicPlaceName>
<Text xml:lang="de">Bernhardsdorf</Text>
</TopographicPlaceName>
</TopographicPlace>
PointOfInterest 1:1 A POI. Please note that there are currently none available.

This feature is currently not supported.

<Place>
<PointOfInterest>
<PublicCode>72215</PublicCode>
<PointOfInterestCategory>
<OsmTag>
<Tag>service</Tag>
<Value>hairdresser</Value>
</OsmTag>
</PointOfInterestCategory>
<TopographicPlaceRef>23006351:-1</TopographicPlaceRef>
</PointOfInterest>
<Name>
<Text xml:lang="de">Hair (Bern)</Text>
</Name>
...
</Place>
Address 1:1 An address
<Address>
<Name>
<Text xml:lang="de">Zürich, Staffelstrasse 12</Text>
</Name>
<PostCode/> <!-- empty tag -->
<TopographicPlaceName>Zürich</TopographicPlaceName>
<TopographicPlaceRef>23026261:1500000003</TopographicPlaceRef>
<Street>Staffelstrasse</Street>
<HouseNumber>12</HouseNumber>
</Address>
Name 1:1 The name of the place
<Name>
<Text xml:lang="de">Zürich</Text>
</Name>
GeoPosition 1:1 The example shows what comes back. Can also be supplied with other elements e.g. StopPlace.
<GeoPosition>
<siri:Longitude>7.43165</siri:Longitude>
<siri:Latitude>46.94308</siri:Latitude>
</GeoPosition>

Place

Item Cardinality Description Example
StopPlaceRef 1:1 The reference to the stop, a SLOID.
<StopPlaceRef>ch:1:sloid:8052</StopPlaceRef
StopPlaceName 1:1 The name of the stop
<StopPlaceName>
<Text>Bern Tiefenau</Text>
</StopPlaceName>
TopographicPlaceRef 1:1 The reference to the location.
<TopographicPlaceRef>23006351:1</TopographicPlaceRef>
TopographicPlaceName 1:1 The name of the place
<TopographicPlaceName>
<Text xml:lang="de">Bernhardsdorf</Text>
</TopographicPlaceName>
PointOfInterest 1:1 The reference to the location.
<PointOfInterest>
<PublicCode>75825</PublicCode>
<PointOfInterestCategory>
<OsmTag>
<Tag>service</Tag>
<Value>hairdresser</Value>
</OsmTag>
</PointOfInterestCategory>
<TopographicPlaceRef>23006627:-1</TopographicPlaceRef>
</PointOfInterest>