Documentación api itranvias

6 files changed, 473 insertions, 10 deletions

diff --git a/docs/urban/coruna.md b/docs/urban/coruna.md
deleted file mode 100644
index f7dbdad..0000000
--- a/docs/urban/coruna.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Urbano de A Coruña
-
-El transporte urbano de A Coruña consiste en un servicio de autobuses urbanos prestado por [Tranvias Coruña](https://tranviascoruna.com), en régimen de concesión por parte del Concello de A Coruña.
-
-## Datos estáticos
-
-Los datos de las líneas de autobuses urbanos de A Coruña se pueden obtener en formato GTFS desde el [NAP](../other/nap.md) del Ministerio de Transportes y Movilidad Sostenible. La URL del dataset es <https://nap.transportes.gob.es/Files/Detail/1376>.
-
-Además, el Concello dispone de un servidor FTP con el historial de feeds GTFS para el ayuntamiento, al que se puede acceder a través de `ftp://tranviasro:TR4nV14S.ro@ftp.coruna.es/`.
diff --git a/docs/urban/coruna/general.md b/docs/urban/coruna/general.md
new file mode 100644
index 0000000..65208c4
--- /dev/null
+++ b/docs/urban/coruna/general.md
@@ -0,0 +1,153 @@
+# General
+
+Esta sección describe cómo obtener los datos estáticos sobre el sistema de buses de Coruña. Esto incluye una lista de paradas, una lista de líneas y otros datos como las tarifas.
+
+## Rutas
+
+Todos los datos arriba mencionados se pueden obtener a partir de la ruta:
+
+```
+https://itranvias.com/queryitr_v3.php?dato=20160101T000000_gl_0_20160101T000000&func=7
+```
+
+Donde la función 7 devuelve novedades sobre la página y, al establecer como parámetro esa fecha, se puede obtener la lista de toda la información.
+
+Es importante mencionar que cambiando \_gl\_ se puede cambiar el idioma de la información sobre las tarifas y de algunas paradas. La información está disponible en los idiomas:
+
+- Gallego: _gl_
+- Español: _es_
+- Inglés: _en_
+
+## Salida
+
+La petición arriba descrita es de gran tamaño, por eso para facilitar su descripción, en este documento se fragmenta.
+
+### Cabeza
+
+Esta parte _"exterior"_ de la repuesta incluye información sobre el estado de la petición, la fecha de la misma, la fecha de los datos devueltos y su tamaño.
+
+Los puntos suspensivos, en este caso, simbolizan el lugar donde se encontrará la información descrita en los próximos apartados
+
+```json
+{
+    "resultado": "OK",
+    "fecha_peticion": "20230921235412",
+    "peticion":"itranvias?fecha=20160101t000000&plataforma=www&lenguaje=gl&idnovedad=0&fechanovedad=20160101t000000",
+    "tama\u00f1o": 72829,
+    "iTranvias": {
+        "actualizacion": {
+            "fecha": "20230832T140825",
+            ...
+        }
+    }
+    "Origen": "Web_Beta"
+}
+```
+
+### Cuerpo
+
+El resto de la respuesta incluye toda la información que nos interesa. Se procede a definir la estructura de la misma separándola por tipos de datos, para facilitar su _"digestión"_
+
+Todas las definiciones que siguen a esta se consideran entradas del diccionario `actualización`
+
+#### Líneas
+
+Bajo la clave _lineas_ se describe la información relativa a las líneas en una lista con un diccionario para cada línea en el que se incluye la siguiente información:
+
+- ID: `id`
+- Nombre de la línea: `lin_comer`
+- Nombre del origen: `nombre_orig`
+- Nombre del destino: `nombre_dest`
+- Color de la línea en hexadeximal (#RRGGBB): `color`
+- Lista de rutas (para cada entrada un diccionario con):
+    - ID de la ruta: `ruta`
+    - Origen de la ruta (normalmente vacío): `nombre_orig`
+    - Destino de la ruta (normalmente vacío): `nombre_dest`
+    - Lista de identificadores de las paradas por las que pasa el recorrido
+
+!!! note "Nota"
+    Aunque algunas líneas contienen 3 rutas diferentes, aún no he tenido problemas utilizando la primera entrada como sentido de IDA, la segunda como VUELTA e ignorando las sucesivas
+
+A continuación se muestra un ejemplo de respuesta de este bloque:
+
+```json
+"lineas": [
+    {
+        "id": 100,
+        "lin_comer": "1",
+        "nombre_orig": "Abente y Lago",
+        "nombre_dest": "Castrill\u00f3n",
+        "color": "982135",
+        "rutas": [
+            {
+                "ruta": 10000,
+                "nombre_orig": "",
+                "nombre_dest": "",
+                "paradas": [
+                    523,
+                    180,
+                    1,
+                    2,
+                    3,
+                    4,
+                    5,
+                    ...
+                ]
+            },
+            ...
+        ]
+    }
+    ...
+]
+```
+
+#### Paradas
+
+Bajo la clave _paradas_ se describe la información relativa a las paradas en una lista con un diccionario para cada parada en la que se incluye la siguiente información:
+
+- ID: `id`
+- Nombre: `nombre`
+- Coordenadas:
+    - Eje X en `posx`
+    - Eje Y en `posy`
+- Lista de identificadores de las líneas que pasan por la parada
+
+A continuación se muestra un ejemplo de respuesta de este bloque:
+
+```json
+"paradas": [
+    {
+        "id": 1,
+        "nombre": "Porta Real",
+        "posx": -8.39585,
+        "posy": 43.370115,
+        "enlaces": [
+            100,
+            1900,
+            200,
+            800,
+            ...
+    }
+    ...
+]
+```
+
+#### Enlaces
+
+En proceso
+
+#### Precios
+
+Bajo la clave _tarifas_ se describe la información relativa a los precios de los billetes en una lista con un diccionario para cada tarifa en la que se incluye el nombre de la tarifa y el precio en euros.
+
+Ejemplo:
+
+```json
+"tarifas": [
+    {
+        "tarifa": "Tarifa ordinaria",
+        "precio": 1.3
+    ]
+    ...
+]
+```
diff --git a/docs/urban/coruna/index.md b/docs/urban/coruna/index.md
new file mode 100644
index 0000000..29e7aeb
--- /dev/null
+++ b/docs/urban/coruna/index.md
@@ -0,0 +1,32 @@
+# Urbano de A Coruña
+
+El transporte urbano de A Coruña consiste en un servicio de autobuses urbanos prestado por [Tranvias Coruña](https://tranviascoruna.com), en régimen de concesión por parte del Concello de A Coruña.
+
+## Datos estáticos
+
+Los datos de las líneas de autobuses urbanos de A Coruña se pueden obtener en formato GTFS desde el [NAP](../other/nap.md) del Ministerio de Transportes y Movilidad Sostenible. La URL del dataset es <https://nap.transportes.gob.es/Files/Detail/1376>.
+
+Además, el Concello dispone de un servidor FTP con el historial de feeds GTFS para el ayuntamiento, al que se puede acceder a través de `ftp://tranviasro:TR4nV14S.ro@ftp.coruna.es/`.
+
+El feed GTFS solo incluye los archivos obligatorios `agency.txt`, `routes.txt`, `trips.txt`, `stops.txt`, `stop_times.txt`, `calendar.txt` y `calendar_dates.txt` y, también, `shapes.txt`.
+
+## Datos en tiempo real
+
+Esta página documenta la API que utiliza la página [iTranvías](https://itranvias.com) de la [Compañía de Tranvías de **La** Coruña](https://tranviascoruna.com), que a la que he hecho *ingeniería inversa* durante el desarrollo de mi página alternativa [bus.delthia.com](https://bus.delthia.com).
+
+!!! warning "Aviso"
+    Es posible que no haya descubierto toda la funcionalidad, o que haya maneras diferentes de utilizar los parámetros para obtener otros resultados o información adicional. Esta es mi mejor apuesta sobre el funcionamiento de la API según lo observado a través de la página de *iTranvias* y una pequeña investigación
+
+### Contenidos
+
+- [Información general](general/): Datos generales sobre el sistema de transporte
+    - [Líneas](general#lineas): Líneas y sus recorridos
+    - [Paradas](general#paradas): Paradas y las rutas que pasan por las mismas
+    - [Enlaces](general#enlaces): Enlaces permitidos y su coste
+    - [Precios](general#precios): Tarifas disponibles
+- [Paradas](paradas/): Próximos buses para una parada
+- [Líneas](lineas/): Información sobre una línea
+    - Posición de los buses sobre el recorrido
+    - Posición geográfica de los buses
+    - Horas de salida
+    - Trazado de una línea
diff --git a/docs/urban/coruna/lineas.md b/docs/urban/coruna/lineas.md
new file mode 100644
index 0000000..442f497
--- /dev/null
+++ b/docs/urban/coruna/lineas.md
@@ -0,0 +1,237 @@
+# Líneas
+
+Esta sección describe cómo obtener información sobre los buses de una línea y, por tanto, son datos en tiempo real. La primera ruta que se trata devuelve una lista de todas las líneas con la información descrita en el apartado [general](general/) y, por tanto, no se describe más lejos del ejemplo de respuesta.
+
+## Información sobre una línea
+
+### Ruta
+Para obtener los datos se puede utilizar la ruta
+
+```
+https://itranvias.com/queryitr_v3.php?&func=1&dato=500
+```
+
+Donde el parámetro `dato` es el identificador de la línea que se quiere consultar.
+
+### Respuesta
+
+```json
+{
+    "resultado": "OK",
+    "fecha_peticion": "20230922222756",
+    "peticion": "jlineas?",
+    "tama\u00f1o": 4644,
+    "lineas": [
+        {
+            "id": "100",
+            "nom_comer": "1",
+            "color_linea": "982135",
+            "orig_linea": "Abente y Lago",
+            "dest_linea": "Castrill\u00f3n"
+            "dest_ida": "Pza. Pablo Iglesias",
+            "dest_vuelta": "Abente y Lago"
+        }
+        ...
+    ],
+    "Origen": "Web_Beta"
+}
+```
+
+## Buses para una línea
+
+Se puede obtener información sobre la posición de los buses con respecto al recorrido de una línea, así como su estado.
+
+### Ruta
+
+```
+https://itranvias.com/queryitr_v3.php?func=2&dato=500
+```
+
+Donde el parámetro `dato` es el identificador de la línea que se quiere consultar.
+
+### Respuesta
+
+```json
+{
+    "resultado": "OK",
+    "fecha_peticion": "20230922224449",
+    "peticion": "jparadas?linea=500&version=2",
+    "tama\u00f1o": 315,
+    "mls": 0,
+    "paradas": [
+        {
+          "sentido": 0,
+          "paradas": [
+            {
+                "parada": 184,
+                "buses": [
+                    {
+                        "bus": 357,
+                        "estado": 1
+                        "distancia": 0.288
+                    },
+                    ...
+                ]
+            },
+            ...
+          ]
+        },
+        ...
+    ],
+    "Origen": "Web_Beta"
+}
+```
+
+Donde la información principal se encuentra bajo la clave `paradas`, donde existe una un diccionario para cada sentido.
+Cada diccionario contiene una lista de paradas, con un diccionario para cada parada que contiene el identificador de la parada (`parada`) y una lista de buses para esa parada.
+Cada bus es un diccionario en esa lista con las entradas:
+
+- `bus`: Identificador del bus
+- `estado`: Estado del bus,
+    - 0: En la parada
+    - 1: En movimiento
+- `distancia`: Posición del bus en su sentido del recorrido como un tanto por uno de la distancia total de ese recorrido.
+
+!!! warning "¡Cuidado!"
+    La posición del bus se representa como una fracción del sentido, pero esta no representa la distancia real entre paradas, si no que el 0 representa la primera parada y el 1 la última y las posiciones del resto de paradas están espaciadas a partes iguales.
+
+## Posición geográfica de los buses de una línea
+
+También es posible obtener las coordenadas de los buses de una línea para mostrar esta información sobre un mapa, esto se puede hacer con la ruta:
+
+```
+https://itranvias.com/queryitr_v3.php?&func=99&mostrar=B&dato=600
+```
+
+```json
+{
+    "resultado":"OK",
+    "fecha_peticion":"20230922231324",
+    "peticion":"jmapas?linea=600&mostrar=b",
+    "tama\u00f1o":199,
+    "mapas": [
+        {
+            "buses": [
+                {
+                    "sentido": 0,
+                    "buses": [
+                        {
+                            "bus": 342,
+                            "posx": -8.413613,
+                            "posy": 43.362973
+                        },
+                        ...
+                    ]
+                },
+                ...
+            ],
+            ...
+        },
+        ...
+    ],
+    "Origen": "Web_Beta"
+}
+```
+
+
+## Posición de las paradas de una línea
+
+```
+https://itranvias.com/queryitr_v3.php?&func=99&mostrar=P&dato=600
+```
+
+### Respuesta
+
+```json
+{
+    "resultado":"OK",
+    "fecha_peticion":"20230922231358",
+    "peticion":"jmapas?linea=600&mostrar=p",
+    "tama\u00f1o":9540,
+    "mapas": [
+        {
+            "paradas": [
+                {
+                    "sentido":"0",
+                    "paradas":[
+                        {
+                            "id": "570",
+                            "parada": "Rda. de Monte Alto, 52",
+                            "posx": -8.40657,
+                            "posy": 43.380598
+                        },
+                        ...
+                    ]
+                },
+                ...
+            ]
+        },
+    ],
+    "Origen": "Web_Beta"
+}
+```
+
+## Trazado del recorrido de una línea
+
+```
+https://itranvias.com/queryitr_v3.php?&func=99&mostrar=R&dato=600
+```
+
+### Respuesta
+
+```json
+{
+    "resultado":"OK",
+    "fecha_peticion":"20230922231404",
+    "peticion":"jmapas?linea=600&mostrar=r",
+    "tama\u00f1o":26731,
+    "mapas": [
+        {
+            "recorridos": [
+                {
+                    "sentido":"0",
+                    "recorrido": "-8.406574518012148,43.3805987842061,0 -8.406662548136888,43.38047546094802,..."
+                },
+                ...
+            ]
+        }
+    ],
+    "Origen": "Web_Beta"
+}
+```
+
+## Salidas para una línea
+
+```
+https://itranvias.com/queryitr_v3.php?&func=8&dato=500&fecha=20230922
+```
+
+```json
+{
+    "resultado":"OK",
+    "fecha_peticion":"20230922232647",
+    "peticion":"servicios",
+    "tama\u00f1o":668,
+    "servicios": [
+        {
+            "fecha":"20230922",
+            "tipo":"Especial",
+            "ida": [
+                635,
+                700,
+                725,
+                543,
+                ...
+            ],
+            "vuelta": [
+                700,
+                725,
+                743,
+                757,
+                ...
+            ]
+        }
+    ],
+    "Origen": "Web_Beta"
+}
+```
diff --git a/docs/urban/coruna/paradas.md b/docs/urban/coruna/paradas.md
new file mode 100644
index 0000000..9824e28
--- /dev/null
+++ b/docs/urban/coruna/paradas.md
@@ -0,0 +1,50 @@
+# Paradas
+
+Esta sección describe cómo obtener los próximos buses para una parada y, por tanto, son datos en tiempo real.
+
+Para obtener los datos se puede utilizar la ruta
+
+```
+https://itranvias.com/queryitr_v3.php?&func=0&dato=10
+```
+
+Donde el parámetro `dato` es el identificador de la parada para la que se quieren consultar los buses. La respuesta tendrá esta forma:
+
+```json
+{
+    "resultado": "OK",
+    "fecha_peticion": "20230922152056",
+    "peticion": "jbuses?parada=100&version=2",
+    "tama\u00f1o": 700,
+    "buses": {
+        "parada": 100,
+        "lineas": [
+            {
+                "linea": 500,
+                "buses": [
+                    {
+                        "bus": 385,
+                        "tiempo": "<1",
+                        "distancia": "186",
+                        "estado": 1,
+                        "ult_parada": 203
+                    },
+                    ...
+                ],
+                ...
+            },
+            ...
+        ]
+    }
+}
+```
+
+El contenido principal se encuentra bajo la clave `buses['paradas']` y, donde existe una entrada para cada línea **activa** (esto es importante, no incluirá aquellas líneas que pasan por la parada pero para las que ya no hay buses activos con ese destino) y, dentro de la clave `buses`, una entrada de diccionario para cada bus con la información:
+
+- Identificador del bus: `id`
+- Tiempo que tardará en llegar a la parada: `tiempo`. En minutos pero el valor será _<1_ cuando el bus esté a punto de llegar
+- Distancia del bus a la parada en metros: `distancia`
+- Estado del bus: `estado`, con los siguientes valores:
+    - 0: El bus está en la parada
+    - 1: El bus está en movimiento
+- Última parada del recorrido por la que pasó el bus: `ult_parada`
diff --git a/mkdocs.yml b/mkdocs.yml
index 4258a20..1617c98 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -37,7 +37,7 @@ nav:
       - Arriva: autonomic/operator/arriva.md
       - Monbus: autonomic/operator/monbus.md
   - Transporte urbano:
-    - A Coruña: urban/coruna.md
+    - A Coruña: urban/coruna/
     - Vigo: urban/vigo.md
   - Otros:
     - NAP: other/nap.md