Lo scopo di questo bot Telegram è consentire la ricerca delle tratte coperte da aziende appartenenti a COTRAP. Nello specifico, con questo bot è possibile eseguire le stesse operazioni di ricerca del sito di COTRAP per la ricerca delle tratte, ma in modo più veloce e pratico utilizzando la semplice interfaccia di bot Telegram.
ℹ️ Questo è un prodotto NON UFFICIALE, ovvero non è commissionato né mantenuto da COTRAP.
Per la realizzazione di questo bot ho usato il framework StatefulBot.
Per installare il bot ed eseguirlo correttamente bisogna rispettare essenzialmente i requisiti indicati nel repo StatefulBot.
Una volta clonato i repository con il comando git clone https://github.com/giuseppetrivi/OBCBot.git, bisogna importare il database MySQL contenente le tabelle per la gestione delle procedure di ricerca. Il file per l'importazione è config/obcbot.sql.
Poi bisogna modificare il file config/config.json in base alle proprie impostazioni e infine bisogna modificare l'attributo $config_filename nella classe config/ConfigurationHandler.
Le tabelle dela database obc_users e obc_searches servono rispettivamente per memotizzare informazioni sull'utente e sulla ricerca in corso. Oltre a queste, ho utilizzato delle tabelle nel database anche per memorizzare tutte le informazioni statiche (relative alle località, alle aziende e ai poli), per evitare di dover eseguire una richiesta HTTP alle API ogni volta. In questo modo ho velocizzato la ricerca. Nello specifico la chiamata alle API viene fatta solamente nel momento in cui, impostati tutti i parametri, la ricerca viene avviata, ed infatti è l'operazione che impiega più tempo per restituire i risultati e la risposta.
In questo progetto ho seguito il coding style descritto nel framework ed ho usato l'inglese per la scrittura di tutte le parti di codice (commenti, variabili, classi, metodi, ecc...), mentre ho usato l'italiano nel database, per avere una corrispondenza 1:1 con i campi restituiti dalle chiamate agli endpoint delle API COTRAP, e qui, nel file README.
La cartella utilities/ non è presente nel progetto originale di StatefulBot. Al suo interno ho inserito la classe DateTimeIT, una estensione della classe di default DateTime fornita da PHP per la manipolazione delle date, con degli specifici metodi per la formattazione e per la traduzione dei giorni e dei mesi in italiano.
Questo bot permette di fare due cose:
- Cercare una tratta urbana, specificando quindi la località tra quelle possibili, la fermata di partenza e quella di arrivo e, infine, la data e l'ora.
- Cercare una tratta extraurbana, specificando quindi la località di partenza, la località di arrivo tra quelle possibili (data la località di partenza), la fermata della località di partenza e quella della località di arrivo e, infine, la data e l'ora.
Entrambe le ricerche restituiranno, se possibile, gli orari di partenza e di arrivo e il relativo costo del biglietto.
🚧 [work in progress]: sarà presente anche una funzionalità che permette di avviare rapidamente le ricerche effettuate più di frequente.
Parto dalla premessa che queste API non sono pubbliche, bensì le ho individuate ispezionando il flusso di richieste fatte dal sito di COTRAP per la ricerca delle tratte durante una ricerca, appunto (per verificare apri il sito, apri "Ispeziona" e posizionati nel tab "Network", dopodiché inizia a selezionare i parametri di ricerca e nel flusso appariranno delle chiamate che restituiscono dati relativi alla ricerca).
Inoltre ci sono anche altri endpoint, che però non ho documentato qui perché non li ho utilizzati all'interno di questo progetto.
Di seguito descriverò gli endpoint principale e i parametri essenziali.
https://biglietteria.cotrap.it/api/ricerca
Questo è il link per accedere a tutti gli endpoint della ricerca delle tratte COTRAP.
(urbane) ➝ https://biglietteria.cotrap.it/api/ricerca/localitaurbane
(extraurbane) ➝ https://biglietteria.cotrap.it/api/ricerca/localitaextraurbane
Questi endpoint danno una lista delle località presenti nel database della COTRAP, con tutte le loro informazioni utili. Per ogni località sono indicati, ad esempio:
- il nome (
denominazione) - le località di arrivo (
localitaArrivo), ovvero una lista di località raggiungibili da una data località - le aziende (
aziende), ovvero la lista di aziende che operano in una data località
Le località urbane sono quelle in cui ci sono tratte interne allo stesso paese, quindi non hanno località di arrivo e, in generale, sono più povere di informazioni.
https://biglietteria.cotrap.it/api/ricerca/aziende
Questo endpoint restituisce informazioni semplici (id, denominazione e descrizione) relative alle aziende di trasporto.
https://biglietteria.cotrap.it/api/ricerca/polilocalita/{idComune}
I poli corrispondono alle fermate presenti in un determinato comune. Questo endpoint restituisce informazioni relative alle fermate, compresa l'azienda di trasporto che ne usufruisce.
Questo è l'endpoint per ottenere le informazioni relative agli orari per una specifica tratte scelta. Tutti i parametri della tratta (località di partenza e di arrivo, fermata di partenza e di arrivo, data e ora di ricerca) vanno indicati nella query del link.
I parametri che bisogna indicare per questa richiesta, quindi, sono i seguenti:
- idLocalitaPartenza
- idLocalitaArrivo
- idPoloPartenza
- idPoloArrivo
- dataPartenza (in formato gg/mm/aaaa)
- oraPartenza (in formato hh:mm)
- numeroCambi, praticamente sempre = 0
- pagina, praticamente sempre = 1
La ricerca per una tratta urbana richiede le stesse informazioni della precedente eccetto per la località di arrivo, che in tal caso è omessa perché il trasporto è interno alla località indicata dal parametro idLocalita.
I parametri che bisogna indicare per questa richiesta, quindi, sono i seguenti:
- idLocalita
- idPoloPartenza
- idPoloArrivo
- dataPartenza (in formato gg/mm/aaaa)
- oraPartenza (in formato hh:mm)
- pagina, praticamente sempre = 1