Este proyecto contiene el código referente a la API de consulta de datos públicos obtenidos en MapatónCDMX
Este es un proyecto maven compuesto por los siguientes módulos:
- public-commons: Este módulo contiene los enums y las constantes utilizadas en todo mapaton. Es un jar que puede ser accedido desde el nuestro repositorio.
- public-utils: Este módulo contiene la lógica pincipal necesaria para implementar la API pública. En este módulo se encuentran las entidades (tablas) que componen la estructura de datos de nuestro modelo. Es un jar que puede ser accedido desde el nuestro repositorio.
- public-api: Este módulo contiene el código de la API pública que se explica a continuación y es desplegado en Google App Engine.
- public-dashboard: Este módulo contiene el código hmtl del dashboartd público y es desplegado en Google App Engine.
Una vez que el usuario ha descargado el código desde este repositorio puede empezar a hacer modificaciones. Los proyectos pueden modificarse e instalarse individualmente. De forma que si sólo se desea modificar la API, no es necesario hacer cambios o distribuir los otros módulos. Dado que todo el proyecto es de tipo Maven, éste puede ser importado en Eclipse o IntelliJ. Se reocmienda mantener los módulos juntos dentro del proytecto padre.
##API pública
Para más información acerca del API es posible utilizar la herramienta API explorer del proyecto, la cual contiene una lista de los métodos utilizables, así como sus parámetros y retornos. El API explorer cuenta con un editor de JSON para realizar las peticiones y ayuda a saber qué parámetros se utilizan en cada método. Dentro de Mapaton Public API es posible ver los métodos expuestos:
- mapatonPublicAPI.getAllGtfsTrails
- mapatonPublicAPI.getAllTrails
- mapatonPublicAPI.getAllValidTrails
- mapatonPublicAPI.getTrailDetails
- mapatonPublicAPI.getTrailRawPoints
- mapatonPublicAPI.getTrailSnappedPoints
- mapatonPublicAPI.getTrailsByStationName
- mapatonPublicAPI.registerGtfsFullTask
- mapatonPublicAPI.registerGtfsTask
- mapatonPublicAPI.trailsNearPoint
mapatonPublicAPI.getAllTrails, mapatonPublicAPI.getAllValidTrails, mapatonPublicAPI.getAllGtfsTrails,
Métodos utilizados para obtener todos los recorridos guardados, los recorridos se encuentran paginados y es necesario indicar al servidor el tamaño y el número de la página.
-
Parámetros:
- cursor: Una cadena de texto que puede estar vacía que le indica al servidor el número de la página que se desea obtener. Para obtener la primer página se llama con una cadena vacía, para páginas posteriores, se utiliza una cadena que el servidor regresa después de cada petición llamada también cursor
- numberOfElements: Un entero que indica el número de elementos que uno desea que el servidor regrese
-
Retornos:
- cursor: Una cadena de texto utilizada para mandar al servidor y obtener el siguiente grupo de elementos paginados.
- trails: Un arreglo de recorridos del número de elementos solicitado por numberOfElements. Los recorridos tienen todos los datos de recorrido detallados en mapatonPublicAPI.getTrailDetails.
Método utilizado para obtener todos los detalles de un recorrido en particular
-
Parámetros:
- trailId: El identificador único del recorrido
-
Retornos:
- trailId: El identificador único del recorrido
- originPlatformId: El identificador único de la plataforma de origen
- originPlatformName: El nombre de la plataforma de origen
- originStationId: El identificador único de la estación de origen
- originStationName: El nombre de la estación de origen
- destinationPlatformId: El identificador único de la plataforma de destino
- destinationPlatformName: El nombre de la plataforma de destino
- destinationStationId: El identificador único de la estación de origen
- destinationStationName: El nombre de la estación de destino
- transportType: El tipo de transporte registrado por el usuario
- maxTariff: La tarifa máxima registrada por el usuario
- photoUrl: El URL de la foto del autobús/vagoneta tomada por el usuario
- schedule: El horario registrado por el usuario
- notes: Una serie de notas registradas por el usuario
- creationDate: La fecha de registro del recorrido
- trailStatus: El status actual del recorrido registrado. De acuerdo a la clase RegisteredTrailStatusEnum los valores pueden ser:
0. 0 = Válido
- 1 = Inválido por ser muy corto (distancia menor a 5 kilómetros o tiempo menor a 15 minutos)
- 2 = Inválido por ser registrado fuera de las fechas del concurso
- 3 = Inválido por otras razones
- invalidReason: En caso de ser Inválido por otras razones, la justificación de esa invalidez
- totalMinutes: Tiempo en minutos del recorrido (Para getAllTrails es 0 por causas de eficiencia)
- totalMeters: Distancia en metros del recorrido (Para getAllTrails es 0 por causas de eficiencia)
Método utilizado para obtener todos los puntos registrados en MapatónCDMX por un usuario.
-
Parámetros:
- trailId: El identificador único del recorrido del cual se quiere obtener los puntos
- cursor: Una cadena de texto que puede estar vacía que le indica al servidor el número de la página que se desea obtener. Para obtener la primer página se llama con una cadena vacía, para páginas posteriores, se utiliza una cadena que el servidor regresa después de cada petición llamada también cursor
- numberOfElements: Un entero que indica el número de elementos que uno desea que el servidor regrese
-
Retornos:
- cursor: Una cadena de texto utilizada para mandar al servidor y obtener el siguiente grupo de elementos paginados.
- points: Un arreglo de puntos del número de elementos solicitado por numberOfElements y ordenados de manera cronológica. Los puntos tienen los siguientes datos:
- location: Es la ubicación geográfica del punto registrado, contiene lo siguiente:
- latitude: La latitud del punto registrado
- longitude: La longitud del punto registrado
- radius: El radio de precisión del punto registrado
- timeStamp: Es el tiempo en el que el punto fue registrado, contiene lo siguiente:
- time: La tiempo del día en la que el punto fue registrado, contiene lo siguiente:
- hour: La hora en la que el punto fue registrado
- minute: El minuto en el que el punto fue registrado
- second: El segundo en el que el punto fue registrado
- date: La fecha en la que el punto fue registrado
- day: El día en el que el punto fue registrado
- month: El mes en el que el punto fue registrado
- year: El año en el que el punto fue registrado
- time: La tiempo del día en la que el punto fue registrado, contiene lo siguiente:
- position: La posición en del punto respecto a otros (no utilizado en mapatonPublicAPI.getTrailRawPoints)
Método utilizado para obtener todos los puntos registrados en MapatónCDMX por un usuario, y pegados a un camino o calle a través de Google SnapToRoad API.
-
Parámetros:
- trailId: El identificador único del recorrido del cual se quiere obtener los puntos
- cursor: Una cadena de texto que puede estar vacía que le indica al servidor el número de la página que se desea obtener. Para obtener la primer página se llama con una cadena vacía, para páginas posteriores, se utiliza una cadena que el servidor regresa después de cada petición llamada también cursor
- numberOfElements: Un entero que indica el número de elementos que uno desea que el servidor regrese
-
Retornos:
- cursor: Una cadena de texto utilizada para mandar al servidor y obtener el siguiente grupo de elementos paginados.
- points: Un arreglo de puntos del número de elementos solicitado por numberOfElements y ordenados de manera cronológica. Los puntos tienen los siguientes datos:
- location: Es la ubicación geográfica del punto registrado, contiene lo siguiente:
- latitude: La latitud del punto registrado
- longitude: La longitud del punto registrado
- radius: El radio de precisión del punto registrado
- position: La posición en del punto respecto a otros (no utilizado en mapatonPublicAPI.getTrailRawPoints)