#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> |
InitialInput/GeoPosition |
0:1 | The requested position with geo-coordinates (WGS84) |
<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> |
InitialInput/GeoRestriction/Rectangle |
0:1 | Restrict the search to a specific rectangle. Coordinates in WGS84. |
<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> |
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> |
GeoPosition |
0:1 | Geoposition in Longitude/Latitude |
<PlaceRef> |
Restrictions (PlaceParamStructure)
| Item | Cardinality | Description | Example |
|---|---|---|---|
Type |
0:* | The type of objects to be returned.
There are the following types (PlaceTypeEnumeration):
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>
|
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:
Please note: The query must be combined with a GeoRestriction (Circle or Rectangle) and not with Name, GeoPosition or PlaceRef. |
<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> |
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> |
Location (Place structure)
| Item | Cardinality | Description | Example |
|---|---|---|---|
StopPlace |
1:1 | A stop in the physical sense |
<StopPlace> |
TopographicPlace |
1:1 |
A place with a name and an ID. |
<TopographicPlace> |
PointOfInterest |
1:1 | A POI. Please note that there are currently none available.
This feature is currently not supported. |
<Place> |
Address |
1:1 | An address |
<Address> |
Name |
1:1 | The name of the place |
<Name> |
GeoPosition |
1:1 | The example shows what comes back. Can also be supplied with other elements e.g. StopPlace. |
<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> |
TopographicPlaceRef |
1:1 | The reference to the location. |
<TopographicPlaceRef>23006351:1</TopographicPlaceRef> |
TopographicPlaceName |
1:1 | The name of the place |
<TopographicPlaceName> |
PointOfInterest |
1:1 | The reference to the location. |
<PointOfInterest> |
