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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<?xml version="1.0" encoding="UTF-8"?> <OJP xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.siri.org.uk/siri" version="1.0" xmlns:ojp="http://www.vdv.de/ojp" xsi:schemaLocation="http://www.siri.org.uk/siri ../ojp-xsd-v1.0/OJP.xsd"> <OJPRequest> <ServiceRequest> <RequestTimestamp>2020-01-09T08:00:00Z</RequestTimestamp> <RequestorRef>IRMA</RequestorRef> <ojp:OJPLocationInformationRequest> <RequestTimestamp>2020-01-09T08:00:00Z</RequestTimestamp> <MessageIdentifier>4711</MessageIdentifier> <ojp:InitialInput> <ojp:LocationName>Bern</ojp:LocationName> </ojp:InitialInput> <ojp:Restrictions> <ojp:Type>stop</ojp:Type> <ojp:IncludePtModes>true</ojp:IncludePtModes> </ojp:Restrictions> </ojp:OJPLocationInformationRequest> </ServiceRequest> </OJPRequest> </OJP> |
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:
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:
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:
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
<?xml version="1.0" encoding="UTF-8"?> <siri:OJP xmlns:siri="http://www.siri.org.uk/siri" xmlns:ojp="http://www.vdv.de/ojp" version="1.0"> <siri:OJPResponse> <siri:ServiceDelivery> <siri:ResponseTimestamp>2020-03-09T09:12:49Z</siri:ResponseTimestamp> <siri:ProducerRef>OJPCH_test</siri:ProducerRef> <siri:Status>true</siri:Status> <ojp:OJPLocationInformationDelivery> <siri:ResponseTimestamp>2020-03-09T09:12:49Z</siri:ResponseTimestamp> <siri:RequestMessageRef>4711</siri:RequestMessageRef> <siri:Status>true</siri:Status> <ojp:CalcTime>53</ojp:CalcTime> <ojp:Location> <ojp:Location> <ojp:StopPlace> <ojp:StopPlaceRef>8571260</ojp:StopPlaceRef> <ojp:StopPlaceName> <ojp:Text>Aarberg, Bernfeld</ojp:Text> </ojp:StopPlaceName> <ojp:TopographicPlaceRef>23006301:1</ojp:TopographicPlaceRef> </ojp:StopPlace> <ojp:LocationName> <ojp:Text xml:lang="de">Aarberg, Bernfeld (Aarberg)</ojp:Text> </ojp:LocationName> <ojp:GeoPosition> <siri:Longitude>7.28473</siri:Longitude> <siri:Latitude>47.04372</siri:Latitude> </ojp:GeoPosition> </ojp:Location> <ojp:Complete>true</ojp:Complete> <ojp:Probability>0.922999978</ojp:Probability> <ojp:Mode> <ojp:PtMode>bus</ojp:PtMode> <siri:BusSubmode>localBusService</siri:BusSubmode> </ojp:Mode> </ojp:Location> <!---- und so weiter und so weiter --> <ojp:Location> <ojp:Location> <ojp:StopPlace> <ojp:StopPlaceRef>8578094</ojp:StopPlaceRef> <ojp:StopPlaceName> <ojp:Text>Biberist, Bernstrasse</ojp:Text> </ojp:StopPlaceName> <ojp:TopographicPlaceRef>23019513:1</ojp:TopographicPlaceRef> </ojp:StopPlace> <ojp:LocationName> <ojp:Text xml:lang="de">Biberist, Bernstrasse (Biberist)</ojp:Text> </ojp:LocationName> <ojp:GeoPosition> <siri:Longitude>7.55428</siri:Longitude> <siri:Latitude>47.18031</siri:Latitude> </ojp:GeoPosition> </ojp:Location> <ojp:Complete>true</ojp:Complete> <ojp:Probability>0.920000017</ojp:Probability> <ojp:Mode> <ojp:PtMode>bus</ojp:PtMode> <siri:BusSubmode>localBusService</siri:BusSubmode> </ojp:Mode> </ojp:Location> </ojp:OJPLocationInformationDelivery> </siri:ServiceDelivery> </siri:OJPResponse> </siri:OJP> |
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
<table
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. |
|