Skip to content
LoginRegister
DEENFRIT
Home
Open-Data-Plattform Mobilität Schweiz
  2. Cookbook
  3. OJPLocationInformationRequest

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.

Achtung: Es können sowohl Didok-Nummern wie auch sloid übertragen werden in Request und Response. Siehe

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

Seit Anfang Jahr 2024 stellen wir auf steigscharfe Daten in OJP um. Wo steigscharf eingeliefert wird, wird auch so ausgeliefert. Steigscharfe Daten sind immer mit einer SLOID ausgeführt und nicht mehr einer Didok-Nummer. Es sind aber gemischte Antworte möglich und Änderungen pro Betreiber/Linien können jederzeit erfolgen.

Alt:

Neu:

 

Alt

Neu:

Dies erlaubt dann auch bessere Fahrwege.

Die Umwandlungen gehen wie folgt:

  • Umwandlungsmethodik (falls Ihr intern mit DiDok arbeitet) für sloid -> didok:
    • Falls sloid im String drin ist,
    • Herauspicken des richtigen Elements, umwandeln in Zahl, und 8‘500‘000 hinzuzählen  (Bsp ch:1:sloid:1026:1:2 -> 8501026)

    Dies ist natürlich ein Hack. In Wirklichkeit müsste eine Mappingtabelle verwendet werden. Wir gehen aber davon aus, dass die letzten Didok-Nummer verschwinden für die Scheiz, bevor dies zum Problem wird.

     

  • Didok -> sloid geht ähnlich. Allerdings kann es zu Problemen bei ausländischen Haltestellen führen:
    •  Grundsätzlich nur 85xxxxx umwandeln, ausser ausländischer Nahverkehr, den wir in unseren Systemen auch erfassen mussten (8500700 -> ch:1:sloid:700)
    • Nahverkehr Ausland: 11xxxxx, 12xxxxx, 13xxxxx, 14xxxxx => ch:1:sloid:<didok>  (Bsp  “Annemasse, Adrien Ligué”:   1401664 à ch:1:sloid:1401664)

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