Indice della materia

Ricerca nella pagina

OJPLocationInformationRequest 2.0

#AutoTranslate

Descrizione breve

Il Location Information Service (LIR) secondo l’OJP 2.0 fornisce diverse ubicazioni in risposta a una richiesta. I dati di input essenziali (Request) sono:

  • input testuale
  • Tipi di oggetti consentiti
  • Restrizioni geografiche/ponderazione
  • Ulteriori restrizioni

L’output (response) è un elenco di oggetti con nomi, posizione geografica, attributi e probabilità.

Se la LocationInformationRequest viene utilizzata senza nome, ma con GeoPosition, Circle o Rectangle, sono supportati i tipi=»address», «stop» e «poi». Inoltre, una GeoPosition con filtro type=»address» fornisce esattamente un indirizzo con numero civico.

Descrizione tecnica

API-Explorer e altri riferimenti

Puoi provare le tue richieste – Open API Explorer.
Dettagli relativi ai singoli parametri per il Richiesta e la Risposta sono disponibili anche online sul sito ufficiale Pagina GitHub dalla VDV.

Richiesta

Esempio di una LocationInformation Request secondo l’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>

Descrizione degli elementi del OJPLocationInformationRequests:

Elemento Cardinalità Descrizione Esempio
siri:RequestTimestamp 1:1 Timestamp della richiesta, come Zulu-Time. 
<siri:RequestTimestamp>2024-11-26T16:03:09Z</siri:RequestTimestamp>
siri:MessageIdentifier 0:1 ID univoco del messaggio, per identificare la risposta. 
<siri:MessageIdentifier>LIR-1a</siri:MessageIdentifier>
InitialInput/Name 0:1 Nome dell’oggetto. Se non viene indicato nessuno, si procede alla ricerca in base agli altri criteri.

Dove si usano più denominazioni, è possibile cercarle tutte. È possibile effettuare la ricerca sia per «Basilea» che per «Basilea FFS». Ad esempio, inserire «Biel» o «Bienne» in entrambi i campi.

 
<InitialInput>
    <Name>Bern</Name>
</InitialInput>
InitialInput/GeoPosition 0:1 La posizione cercata con le geocoordinate (WGS84) 
<InitialInput>
    <GeoPosition>
        <siri:Longitude>8.5545</siri:Longitude>
        <siri:Latitude>47.365</siri:Latitude>
    </GeoPosition>
</InitialInput>
InitialInput/GeoRestriction/Circle 0:1 Una restrizione della ricerca a un determinato raggio. Ad esempio, selezionando il tipo corretto, è possibile indicare tutte le fermate in un raggio. Coordinate come 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 Una restrizione della ricerca a un determinato rettangolo. Coordinate come 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 Un riferimento a un posto v. tabella a parte
Restrictions 0:1 Limitazioni da applicare v. tabella a parte

PlaceRif

Per una Request con una PlaceRif l’elemento necessario <Name> viene ignorato, viene analizzato solo il numero di riferimento.

Elemento Cardinalità Descrizione Esempio
siri:StopPointRef 0:1 Riferimento a uno ScheduledStopPoint.
Vengono ancora utilizzati solo SLOID; per StopPoint esteri nelle request e nella response possono ancora essere utilizzati numeri BPUIC.		 
<PlaceRef>
    <siri:StopPointRef>ch:1:sloid:30813</siri:StopPointRef>
    <Name>
        <Text>Zürich Kreuzplatz</Text>
    </Name>
</PlaceRef>
StopPlaceRef 0:1 Riferimento a una fermata. Vengono ancora utilizzati solo gli SLOID; per StopPlace esteri si possono ancora utilizzare i numeri BPUIC nella request e nella response. 
<PlaceRef>
    <StopPlaceRef>ch:1:sloid:30813</StopPlaceRef>
    <Name>
        <Text>Zürich Kreuzplatz</Text>
    </Name>
</PlaceRef>
GeoPosition 0:1 Geoposizione come longitudine/latitudine 
<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)

Elemento Cardinalità Descrizione Esempio
Type 0:* Digita gli oggetti da riconsegnare che cosa si sta cercando.

Esistono i seguenti tipi (PlaceTypeEnumeration):

  • stop
  • indirizzo
  • poi
  • sede
  • topographicPlace

Gli utilizzi principali sono stop e location. Con il tempo, i POI acquisiranno importanza (eventualmente specialmente per autosili e sharer).

I veicoli in condivisione (monopattino elettrico, biciclette, auto) e le stazioni di ricarica possono ora essere richiamati come POI (v. il filtro PointOfInterest qui di seguito).

Per l’address occorre prima determinare il nome esatto con un input generico. Poi occorre effettuare la ricerca con lo stesso nome e il tipo «address». Solo allora il codice di indirizzo ritorna. Si tratta però di un caso speciale che di norma non dovrebbe essere utilizzato. Né il codice di indirizzo né il TopographicPlaceRef sono rilevanti al di fuori della ricerca nell’OJP.

 
<Type>stop</Type>
Modes 0:1 Contiene un elemento di esclusione booleano. Se true, le modalità vengono escluse, altrimenti incluse.
Ulteriori dettagli: opentransportdata.swiss/…/ojptriprequest		 <Modes>
    <Exclude>false</Exclude>
    <PtMode>bus</PtMode>
</Modes>
OperatorFilter 0:1 Un filtro per operatore. In futuro con SBOID. n.d.
TopographicPlaceRef 0:1 Viene usato per filtrare per località. Se è impostato almeno un riferimento, vengono cercati solo oggetti all’interno dei luoghi interessati. 
<TopographicPlaceRef>23011901:2</TopographicPlaceRef>
PointOfInterestFilter 0:1 Utilizzando questo filtro è possibile trovare le località corrispondenti. 12/2024 Attualmente i routing con diverse modalità non sono ancora supportati. Successivamente saranno disponibili le seguenti modalità: Possibilità di accedere ai veicoli in condivisione (monopattini elettrici, biciclette, auto) e alle stazioni di ricarica in un raggio o in un rettangolo.
Struttura come illustrato nell’esempio a destra:
  • In «Tag» inserire sempre «amenity»
  • In «Value» scegliere tra «escooter_rental», «bicycle_rental», «car_sharing» oppure «stazione di ricarica».

Attenzione: la query deve essere combinata con una GeoRestriction (Circle o Rectangle) e non con Name, GeoPosition o PlaceRef.

 
<PointOfInterestFilter>
    <PointOfInterestCategory>
        <OsmTag>
            <Tag>amenity</Tag>
            <Value>car_sharing</Value>
        </OsmTag>
    </PointOfInterestCategory>
</PointOfInterestFilter>
NumberOfResults 0:1 Il numero di risultati.

Importante: stringhe di caratteri come «St. Gallen Haggen» e «St. Gallen, Haggen» sono equivalenti per la ricerca.

Se viene intercettato un gruppo di risultati con la stessa probabilità (>0,5), il server restituisce tutti i risultati. Ciò significa che il numero effettivo di risultati può discostarsi dal risultato desiderato. Questo perché per NumberOfResults=1 e inserendo «St. Gallen, Haggen» devono essere restituite due fermate: «St. Gallen, Haggen» e «St. Gallen Haggen».

 
<NumberOfResults>10</NumberOfResults>
NumberOfResultsAfter & NumberOfResultsBefore 0:1 Il numero di risultati dopo l’ora specificata o prima, indipendentemente dal fatto che l’ora sia <Origin> o <Destination>. 
<NumberOfResults>10</NumberOfResults>
IncludePtModes 0:1 Comunica al servizio che deve restituire le modalità disponibili per ogni fermata. L’impostazione di default è false. 
<IncludePtModes>true</IncludePtModes>

Risposta

Esempio di risposta:

<?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>
+

La risposta è in una OJPLocationInformationDeliveryElement imballato:

Elemento Cardinalità Descrizione Esempio
siri:ResponseTimestamp 1:1 Il timestamp della risposta 
<siri:ResponseTimestamp>2024-11-26T17:03:09.1542196+01:00</siri:ResponseTimestamp>
siri:ProducerRef 0:1 Nome dell’operatore del sistema OJP 
<siri:ResponseTimestamp>MENTZ</siri:ResponseTimestamp>
siri:RequesteMessageRef 0:1 Riferimento univoco arbitrario alla richiesta che ha portato a questa segnalazione 
<siri:RequestMessageRef>d5e1d0e3-ba3c-4f3e-b068-105f4d001777</siri:RequestMessageRef>
siri:DefaultLanguage 0:1 Lingua standard per gli elementi di testo. 
<siri:DefaultLanguage>de</siri:DefaultLanguage>
CalcTime 0:1 Il tempo di calcolo in millisecondi 
<CalcTime>2</CalcTime>
Place 1:1 Contiene le risposte individuali Place
PlaceResult/Place 1:1 Contiene le singole risposte Place. Ecco un esempio di risposta con StopPlace. A seconda della richiesta, l’aspetto è leggermente diverso. Maggiori informazioni su altri parametri qui sotto.

Per ogni PlaceResult viene restituito un elemento Place. Il numero di PlaceResults è correlato ai parametri della richiesta «NumberOfResults», «NumberOfResultsAfter» e «NumberOfResultsBefore». Se la richiesta è stata effettuata senza questi parametri, il router può determinarne il numero.

 
<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 Indica se il posto attuale è completo o può ancora essere perfezionato. Durante il refinement, il «Ref» deve essere inserito di nuovo in una LocationInformationRequest per ricevere una risposta con tutti i dettagli. 
<Complete>true</Complete>
Probability 1:1 La probabilità che la location corrispondente corrisponda a quella che stai cercando.

Il risultato è ordinato in ordine decrescente con la probabilità (il più rilevante prima).

La selezione dei migliori candidati per l’elenco dei risultati viene determinata dopo che il testo dell’input coincide con l’intero dataset. La probabilità viene determinata in base al numero di trigrammi corrispondenti in cui i termini possono essere scomposti e il resto che non coincide. In caso di corrispondenza completa, ossia senza risultato, si ha un risultato definitivo e il candidato ottiene la probabilità massima 1. Se rimane un risultato residuo, viene detratto un punteggio. I risultati ottenuti possono essere successivamente influenzati da diversi criteri di valutazione, qualità e ordine di classificazione. Le corrispondenze possono essere modificate in base alla regione (codice comune), al tipo (fermata, indirizzo, luogo, POI ecc.), al mezzo di trasporto di servizio o a un valore di rilevanza.		 
<Probability>0.927999973</Probability>

 
Mode 0:* Le modalità rilevanti per la location 
<Mode>
    <PtMode>tram</PtMode>
    <siri:TramSubmode>cityTram</siri:TramSubmode>
</Mode>
<Mode>
    <PtMode>bus</PtMode>
    <siri:BusSubmode>localBus</siri:BusSubmode>
</Mode>

Location (PlaceStructure)

Elemento Cardinalità Descrizione Esempio
StopPlace 1:1 Una fermata nel senso fisico 
<StopPlace>
    <StopPlaceRef>ch:1:sloid:7483</StopPlaceRef>
    <StopPlaceName>
        <Text xml:lang="de">Spiez</Text>
    </StopPlaceName>
    <TopographicPlaceRef>23006768:5</TopographicPlaceRef>
</StopPlace>
TopographicPlace 1:1

Un luogo con un nome e un ID.

 
<TopographicPlace>
    <TopographicPlaceCode>suburbID:8136088:6:Bernhardsdorf:5439812:10881110:MRCV</TopographicPlaceCode>
    <TopographicPlaceName>
         <Text xml:lang="de">Bernhardsdorf</Text>
    </TopographicPlaceName>
</TopographicPlace>
PointOfInterest 1:1 Un POI. Attenzione: Al momento non sono disponibili.

Questa funzione non è al momento supportata.

 
<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 Un indirizzo 
<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 Il nome del luogo 
<Name>
    <Text xml:lang="de">Zürich</Text>
</Name>
GeoPosition 1:1 L’esempio mostra ciò che viene utile. Può essere fornito anche con altri elementi, ad es. StopPlace. 
<GeoPosition>
    <siri:Longitude>7.43165</siri:Longitude>
    <siri:Latitude>46.94308</siri:Latitude>
</GeoPosition>

Luogo

Elemento Cardinalità Descrizione Esempio
StopPlaceRef 1:1 Il riferimento alla fermata, uno SLOID. 
<StopPlaceRef>ch:1:sloid:8052</StopPlaceRef
StopPlaceName 1:1 Nome della fermata 
<StopPlaceName>
    <Text>Bern Tiefenau</Text>
</StopPlaceName>
TopographicPlaceRef 1:1 Il riferimento al luogo. 
<TopographicPlaceRef>23006351:1</TopographicPlaceRef>
TopographicPlaceName 1:1 Il nome del luogo 
<TopographicPlaceName>
    <Text xml:lang="de">Bernhardsdorf</Text>
</TopographicPlaceName>
PointOfInterest 1:1 Il riferimento al luogo. 
<PointOfInterest>
    <PublicCode>75825</PublicCode>
    <PointOfInterestCategory>
        <OsmTag>
            <Tag>service</Tag>
            <Value>hairdresser</Value>
        </OsmTag>
    </PointOfInterestCategory>
    <TopographicPlaceRef>23006627:-1</TopographicPlaceRef>
</PointOfInterest>