Zum Inhalt springen

OJPLocationInformationRequest

Location Information Service

Der Location Service liefert verschiedene Location als Antwort auf eine Anfrage. Wesentliche Inputdaten sind:

  • textueller Input
  • Erlaubte Objekttypen
  • Geographische Restriktionen/Gewichtung
  • Weitere Einschränkungen

Die Ausgabe ist eine Liste von Objekten mit Namen, geographischer Position, Attributen und einer Wahrscheinlichkeit.

Wird der LocationInformationRequest ohne LocationName, aber mit GeoPosition, Circle oder Rectangle verwendet, so ist nur der type=“stop“ unterstützt. Zusätzlich GeoPosition mit type=“address“ liefert genau eine Adresse mit HausnummerRequest.

API-Explorer

Sie können eigene Requests ausprobieren – direkter Link zum API-Explorer.

Request

Element Kardinalität Beschreibung Beispiel
RequestTimestamp 1:1  Timestamp der Anfrage. Am liebsten als Zulu-Time
MessageIdentifier 0:1 Eindeutige id der Meldung. Wir würden es begrüssen, wenn diese streng monoton steigend sind.
ojp:InitialInput/ojp:LocationName 0:1 Der Name des Objekts. Wenn keiner angegeben wird, dann wird anhand der anderen Kriterien gesucht.

Wo verschiedene Bezeichnungen üblich sind, kann nach allen gesucht werden. Es funktioniert z.B. sowohl die Suche nach „Basel“ als auch „Bâle CFF“. Bei mehrsprachig angeschriebenen Haltestellen funktioniert es auch, wenn man nur in eine Sprache sucht. Z.B. „Biel/Bienne“ wird sowohl mit dem Request „Biel“ als auch mit „Bienne“ gefunden.

ojp:InitialInput/ojp:GeoPosition 0:1 Die gesuchte Position mit Geokoordinaten (WGS84)

ojp:InitialInput/GeoRestriction/Circle 0:1  Eine Restriktion der Suche auf einen bestimmten Umkreis. Z.B. können so mit korrekter Wahl von type alle Haltestellen in einem Umkreis angegeben werden. Koordinaten als WGS84.

ojp:InitialInput/GeoRestriction/Rectangle 0:1  Eine Restriktion der Suche auf ein bestimmtes Rechteck. Koordinaten als WGS84.

ojp:/ojp:PlaceRef 0:1 Eine Referenz auf einen Platz. siehe separate Tabelle
ojp:Restrictions 0:1 Die zu verwendenden Einschränkungen siehe separate Tabelle

Restrictions

Element Kardinalität Beschreibung Beispiel
ojp:Type 0:*  Type, was gesucht wird an zurückzuliefernden Objekten.

Es gibt die folgenden Typen:

  • stop
  • address
  • poi
  • coord
  • topographicPlace

Die Hauptverwendung sind stop und coord. poi wird mit der Zeit wichtiger werden (namentlich u.U. für Parkhäuser und Sharer).

Neu können Sharing-Fahrzeuge (E-Scooter, Fahrräder, Autos) und Ladestationen als POI abgerufen werden (siehe unter ojp:PointOfInterestFilter unten).

Für address muss zuerst mit generellem Input der genaue LocationName ermittelt werden. Dann muss genau mit diesem Namen und dem Type „address“ gesucht werden. Erst dann kommt der Adresscode zurück. Dies ist aber ein Sonderfall, der normalerweise nicht verwendet werden sollte. Weder Adresscode noch TopographicPlaceRef haben eine sinnvolle Bedeutung ausserhalb der Suchen im OJP.

 

ojp:Usage 0:* Gibt an, wofür der Place verwendet wird.

Es gibt folgende Werte:

  • origin
  • via
  • destination

Das Feature wird nicht unterstützt.

n/a
ojp:PtModes  0:1 Enthält ein boolsches Exclude-element. Wenn true, dann werden die Modes ausgeschlossen, sonst eingeschlossen.  Die Handhabung wird in einem separaten Abschnitt beschrieben.

Siehe auch Abschnitt zu PtMode

 

ojp:OperatorFilter 0:1 Ein Filter nach dem Betreiber.

Das Feature wird nicht unterstützt.

n/a
ojp:TopographicPlaceRef 0:1 Wird benutzt, um nach Orten zu filtern. Wenn mindestens eine Referenz gesetzt ist, werden nur Objekte innerhalb der betreffenden Orte gesucht.

ojp:PointOfInterestFilter 0:1 Neu (seit August 2022) können hiermit Sharing-Fahrzeuge (E-Scooter, Fahrräder, Autos) und Ladestationen in einem Umkreis oder Rechteck abgerufen werden.
Aufbau wie im Beispiel rechts ersichtlich:

  • Bei ojp:Tag immer amenity
  • Bei ojp:Value wahlweise escooter_rental, bicycle_rental, car_sharing oder charging_station.

Achtung: Die Abfrage sollte mit einer GeoRestriction (Circle oder Rectangle) kombiniert werden, und nicht mit LocationName, GeoPosition oder PlaceRef.

 

ojp:Language 0:1 Gewünschte Sprache für Rückgabewerte.

Nicht implementiert in der aktuellen Version 1.0, geplant für eine spätere Version

n/a
ojp: NumberOfResults 0:1 Die Anzahl der Ergebnisse.

Wichtig: Zeichenketten wie „St. Gallen Haggen“ und „St. Gallen, Haggen“ sind für die Suche gleichwertig.

Wird eine Resultategruppe mit gleicher Wahrscheinlichkeit (>0.5) angeschnitten, so liefert der Server alle Resultate zurück. D.h. die effektive Anzahl der Resultate kann abweichen vom gewünschten Resultat. Der Grund liegt darin, dass bei NumberOfResults=1 und Eingabe „St. Gallen, Haggen“ effektiv 2 Haltestellen zurückgeliefert werden müssen: „St. Gallen, Haggen“ und „St. Gallen Haggen“.

IncludePtModes 0:1 Teilt dem Service mit, dass er die verfügbaren Modi zurückgeben soll für jeden Stop. Default ist false.

PlaceRef

Element Kardinalität Beschreibung Beispiel
ojp: StopPointRef 0:1 Verweis auf einen ScheduledStopPoint.

Es wird davon abgeraten, diese zu verwenden, da es unklar ist, welche id notwendig ist.

ojp:StopPlaceRef 0:1 Verweis auf eine Haltestelle. Basiert auf der DiDok-Nummer. Die Verwendung von StopPlaces führt zu sehr schnellen Suchresultaten.

ojp:GeoPosition 0:1 Geoposition als Longitude/Latitude

ojp:PlaceRef/ojp:LocationName 0:1 Wird ignoriert n/a

PTMode

Die PTMode sind die Modi des Verkehrs.

Auf der PTMode-Ebene gibt es die folgenden Werte (es gibt mehr, aber die kommen nicht vor bei uns, auch von den unten genannten, werden im Moment nicht alle verwendet):

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

Die SubModes sind:

AirSubmode

  • Aktuell nicht verwendet

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 (ja, tatsächlich mit b. Wird irgendwann mal geändert)

WaterSubmode

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

 

Response

Die Antwort ist in einem ojp:OJPLocationInformationDelivery-Element

Element Kardinalität Beschreibung Beispiel
siri:ResponseTimestamp 1:1 Der timestamp der Antwort
siri:RequesteMessageRef 0:1 Hier wird die Message referenziert, die angefragt wurde
siri:Status 1:1 Der Status der Antwort. true heisst, die Anfrage wurde bearbeitet.
ojp:CalcTime 1:1 Die Berechnungszeit in Millisekunden
ojp:Location 1:1 Enthält die einzelnen ojp:Location-Antworten
ojp:Location/ojp:Location 1:1 Die einzelnen Antworten. Es ist relativ unschön, dass hier zwei hierarchisch unterschiedliche Elemente gleich benannt sind, aber das ist jetzt einfach so.
 ojp:Complete 1:1 Gibt an, ob die aktuelle Location vollständig ist oder noch verfeinert werden muss. Beim Refinement muss sie nochmals in einem LocationInformationRequest präziser eingegeben werden.
ojp:Probability 1:1 Die Wahrscheinlichkeit, dass die entsprechende Location der gesuchten entspricht.

Das Resultat ist nach Wahrscheinlichkeit absteigend sortiert (relevantestes zuerst).

Die Auswahl der besten Kandidaten für die Trefferliste wird nach Übereinstimmung des Eingabetextes mit dem gesamten Datenbestand ermittelt. Die Probability wird anhand der Anzahl der übereinstimmenden Trigramme, in die sich die Begriffe zerlegen lassen, und dem Rest, der nicht übereinstimmt, ermittelt. Bei vollständiger Übereinstimmung, also ohne Rest, liegt ein Volltreffer vor und der Kandidat erhält die maximale Probability 1. Liegt noch ein Rest vor, so führt dieser zu Punktabzug. Die so gefunden Treffer lassen sich anschließend über verschiedene Bewertungskriterien und Qualität und Sortierreihenfolge beeinflussen. Treffer können anhand der Region (Gemeindekennziffer), Typ (Haltestelle, Adresse, Ort, POI,…), bedienendem Verkehrsmittel oder einem Relevanzwert verändert werden.

 

ojp:Mode 0:* Die relevanten Modi für die Location

ojp:Location

Eine Location kann Folgendes sein:

  • StopPoint: Eine Haltestelle oder ein Gleis
  • StopPlace: Eine Haltestelle im physischen Sinne
  • TopographicPlace: Ein Ort
  • PointOfInterest: Ein POI. Achtung: Im Moment sind keine verfügbar.
  • Address: Eine Adresse
Element Kardinalität Beschreibung Beispiel
ojp:StopPlace 0:1 Eine Haltestelle im physischen Sinne
ojp:StopPoint 0:1 Eine Haltestelle oder ein Gleis

Im Moment sollten keine kommen.

Das Feature wird im Moment nicht unterstützt.

ojp:TopographicPlace 0:1 Ein Ort

ojp:PointOfInterest 0:1 Ein POI. Achtung: Im Moment sind keine verfügbar.

Das Feature wird im Moment nicht unterstützt.

ojp:Address 0:1 Eine Adresse

 

ojp:LocationName 0:1 Der Name des Ortes

 

ojp:GeoPosition 0:1 Die Koordinaten

Das Beispiel zeigt, was zurückkommt, wenn keine Koordinaten vorhanden sind. Die Präzision ist dann auf den halben Weltumfang eingestellt. Wir versuchen natürlich, solche Fälle zu vermeiden.

 

ojp:Location/ojp:StopPoint

Das Feature wird im Moment nicht unterstützt.

ojp:Location/ojp:StopPlace

Element Kardinalität Beschreibung Beispiel
ojp:StopPlaceRef  1:1 Die Referenz auf die Haltestelle. Aktuell: DiDok-Nummer
ojp:StopPlaceName 1:1 Der Name der Haltestelle
 
ojp:TopographicPlaceRef 1:1 Die Referenz auf den Ort.

ojp:Location/ojp:TopographicPlace

Element Kardinalität Beschreibung Beispiel
ojp:TopographicPlaceRef  1:1 Die Referenz auf den Ort.
ojp:TopographicPlaceName 1:1 Der Name des Ortes