Saltar a contenido

Gu铆a de implementaci贸n para productores de GBFS

Introducci贸n

Esta gu铆a est谩 destinada a equipos t茅cnicos de servicios de movilidad compartida. En esta gu铆a encontrar谩 recomendaciones y recursos para publicar el estado de su sistema de movilidad en formato GBFS (Especificaci贸n general de alimentaci贸n de bicicletas compartidas). Utilice esta gu铆a adem谩s de la referencia de GBFS.

Prop贸sito de GBFS

La Especificaci贸n general de alimentaci贸n de bicicletas compartidas (GBFS) se cre贸 en 2014 por Mitch Vars, que luego fue adoptado por NABSA, para estandarizar la forma en que los sistemas de bicicletas compartidas se comunican con las aplicaciones de planificaci贸n de trip .

Desarrollado por MobilityData desde 2019 y transferido oficialmente a MobilityData en 2022, GBFS ha evolucionado para permitir m谩s de 800 sistemas acoplados y sin acoplamiento en todo el mundo, como scooters, ciclomotores y coches compartidos aparecer谩n en las aplicaciones de planificaci贸n de trip .

Logotipos de consumidores de productores de GBFS

GBFS es un formato de datos estandarizado utilizado por m谩s de 800 servicios de movilidad compartidos en todo el mundo para aparecer en planificadores de trip y otras aplicaciones de consumo.

Descripci贸n general de un feed GBFS

GBFS es una especificaci贸n de datos basada en extracci贸n en tiempo real que describe el estado actual de un sistema de movilidad.

Un feed GBFS se compone de una serie de archivos JSON. Cada archivo modela un aspecto particular de un sistema de movilidad: estado de veh铆culos y/o estaciones, reglas geogr谩ficas, precios, etc. Los detalles de cada archivo se definen en la referencia GBFS con ejemplos.

Descripci贸n general de GBFS

La aplicaci贸n consumidora solicita el estado actual del sistema de movilidad al operador, quien responde con los feeds GBFS en formato JSON.

Hacer que un feed GBFS est茅 disponible p煤blicamente

Los feeds p煤blicos permiten la integraci贸n de servicios de movilidad compartidos con el transporte p煤blico. GBFS respeta la privacidad del usuario ya que no contiene ning煤n dato del usuario.

La forma m谩s sencilla de hacer p煤blico un feed es alojarlo en un servidor web o exponerlo a trav茅s de una API y publicar un anuncio que lo haga disponible para su uso.

Una lista de archivos compartidos Los servicios de movilidad que brindan transmisiones p煤blicas est谩n disponibles en el cat谩logo MobilityData systems.csv. Permite a los desarrolladores crear software sobre 茅l, proporciona una fuente para proyectos de investigaci贸n y demuestra el alcance de la especificaci贸n en todo el mundo.

Si tiene o conoce un sistema que no aparece en la lista, agr茅guelo abriendo un extracto. solicite o notifique a MobilityData en: sharedmobility@mobilitydata.org.

Veh铆culos compartidos

Foto de Lucian Alexe en Unsplash. Bruselas, B茅lgica.

Pasos de implementaci贸n

Esta gu铆a divide el script de publicaci贸n del feed en 4 pasos: extraer, transformar, cargar y validar.

ETL

Estos 4 pasos permiten a cualquier operador de movilidad compartida publicar un feed GBFS v谩lido.

1. Extraiga datos de su sistema de movilidad

Extraer los datos de su sistema de movilidad es el primer paso para publicar su estado actual.

Extraer datos desde un software de gesti贸n de flotas de terceros

Si su sistema de movilidad est谩 gestionado por un software de gesti贸n de flotas, es posible que el proveedor que est谩 utilizando ya ofrezca un complemento GBFS. Preg煤ntele a su proveedor de software actual si ofrece un complemento GBFS o considere este factor al elegir su proveedor. Algunos software ofrecen un complemento GBFS, que incluye, entre otros: ATOM, Fifteen, goUrban, Joyride, PBSC, Flota urbana, Vulog y Wunder Mobility.

Si el proveedor de software de gesti贸n de flotas que est谩 utilizando no ofrece un complemento GBFS, es posible que proporcione una API que pueda consultar para extraer el estado actual de su sistema de movilidad.

Extraer datos de un Software interno de gesti贸n de flotas

Si construy贸 su sistema de movilidad internamente, puede leer el estado actual de su sistema de movilidad directamente desde su base de datos operativa. Los operadores generalmente eligen escribir su script de publicaci贸n de feeds en el mismo language de programaci贸n que el resto de su sistema.

Si planea crear un software de gesti贸n de flotas interno, puede ser una buena idea que las tablas de la base de datos operativa utilicen el mismo estructura como la referencia de GBFS. Esta elecci贸n t茅cnica hace que la publicaci贸n de feeds GBFS sea significativamente m谩s f谩cil.

2. Transforme sus datos en una estructura GBFS

A continuaci贸n, deber谩 modelar los datos en la estructura GBFS.

La estructura GBFS

estructura GBFS

Un conjunto de datos GBFS v3 se compone de 12 archivos JSON, algunos siempre obligatorio, otros obligatorio bajo ciertas condiciones y otros opcional. El archivo manifest.json enumera las URL de descubrimiento autom谩tico para cada conjunto de datos GBFS producido por un editor.

Esta estructura fue dise帽ada para informaci贸n separada en tiempo real (por ejemplo: station_status.json y vehicle_status.json) a partir de informaci贸n est谩tica (por ejemplo: system_information.json , station_information.json y vehicle_types.json). Esto hace posible tener una duraci贸n de cach茅 m谩s larga para la informaci贸n que cambia con menos frecuencia.

Ejemplo de archivo station_status.json

Estaci贸n de bicicletas compartidas

Foto de Dylan Patterson en Unsplash

Ejemplo de station_status.json archivo obligatorio para sistemas de movilidad basados 鈥嬧媏n estaciones:

{
  "last_updated": "2023-07-30T13:45:29+02:00",
  "ttl": 0,
  "version": "3.0",
  "data": {
    "stations": [
      {
        "station_id": "station1",
        "last_reported": "2023-07-30T13:45:29+02:00",
        "num_vehicles_available": 10,
        "vehicle_types_available": [
          {
            "vehicle_type_id": "bike_type_1",
            "count": 10
          }
        ],
        "num_vehicles_disabled": 0,
        "num_docks_available": 3,
        "vehicle_docks_available": [
          {
            "vehicle_type_ids": ["bike_type_1", "bike_type_2"],
            "count": 3
          }
        ],
        "num_docks_disabled": 0,
        "is_installed": true,
        "is_renting": true,
        "is_returning": true
      },
      ... more stations
    ]
  }
}

Ejemplo de archivo vehicle_status.json

Scooter compartido

Foto deElizabeth Woolner en Unsplash

Ejemplo de vehicle_status.json archivo obligatorio para veh铆culos flotantes (sin muelle) y opcional para veh铆culos basados 鈥嬧媏n estaciones (acoplados):

{
  "last_updated": "2023-07-30T13:45:29+02:00",
  "ttl": 0,
  "version": "3.0",
  "data": {
    "vehicles": [
      {
        "vehicle_id": "973a5c94",
        "last_reported": "2023-07-30T13:45:29+02:00",
        "lat": 12.345678,
        "lon": 56.789012,
        "is_reserved":false,
        "is_disabled":false,
        "rental_uris": {
          "android": "https://www.example.com/app?vehicle_id=973a5c94&platform=android",
          "ios": "https://www.example.com/app?vehicle_id=973a5c94&platform=ios",
          "web": "https://www.example.com/app?vehicle_id=973a5c94"
        },
        "vehicle_type_id": "bike_type_1",
        "current_range_meters": "6543.0",
        "current_fuel_percent": "0.65",
        "station_id": "station1",
        "home_station_id": "station1",
        "pricing_plan_id": "pricing_plan_1",
        "vehicle_equipment": [],
        "available_until": "2023-07-30T13:45:29+02:00"
      },
      ... more vehicles
    ]
  }
}

Para proteger la privacidad del usuario, los veh铆culos en alquiler activo no deber铆a incluirse en este feed. Adem谩s, la identificaci贸n del vehicle deber铆a rotarse despu茅s de cada viaje. Esto se aplica a vehicle_id y a los enlaces profundos en rental_uris en vehicle_status.json Puede encontrar m谩s informaci贸n sobre la implementaci贸n de identificaciones de vehicle rotativas en el blog de ingenier铆a publicaci贸n por TIER.

Utilice la versi贸n actual de GBFS

Utilice la versi贸n actual de la especificaci贸n para beneficiarse de la mayor cobertura de tipos y caracter铆sticas de vehicle. Esta gu铆a utiliza la versi贸n 3.0 de la especificaci贸n GBFS. Candidatos de lanzamiento (-RC) son versiones que recibir谩n el estado de Versi贸n actual cuando se hayan implementado completamente en los feeds p煤blicos.

Generar un modelo de datos a partir del esquema JSON

La mejor manera de garantizar que los feeds que produce sean v谩lidos es generar un modelo de datos a partir del esquema JSON GBFS. Varios operadores han notado grandes ganancias en eficiencia al utilizar un modelo de datos generado a partir del esquema JSON, especialmente al actualizar a una nueva versi贸n de GBFS.

Modelo de datos

Un modelo de datos generado a partir del esquema GBFS JSON es la forma m谩s segura y eficiente de transformar sus datos en la estructura GBFS.

Para ayudar con la migraci贸n a v3.0, hemos trabajado con Entur para publicar tipos GBFS en TypeScript (paquete NPM) y Java (paquete Maven Central). Se generan autom谩ticamente a partir de los [esquemas JSON GBFS] oficiales (https://github.com/MobilityData/gbfs-json-schema). Entonces, cuando la especificaci贸n cambia, su modelo de datos evoluciona con ella. Puede encontrar herramientas generadoras para muchos lenguajes de programaci贸n en json-schema.org.

Crear un modelo de datos manualmente desde la referencia de GBFS es posible, pero no recomendado, ya que es propenso a errores y m谩s dif铆cil de actualizar cuando cambia la especificaci贸n GBFS.

3. Cargar o exponga sus feeds GBFS

Una vez que los datos de su sistema de movilidad est茅n modelados en la estructura GBFS, deber谩 ponerlos a disposici贸n del p煤blico.

Aloje sus feeds GBFS en un servidor web o en un dep贸sito de almacenamiento web

Como soluci贸n rentable, los feeds GBFS puede estar alojado en un servidor web, como NGINX. Schedule su secuencia de comandos para actualizar las fuentes en tiempo real al menos cada 30 segundos (station_status.json y vehicle_status.json). Cualquier valor por encima de esta frecuencia de actualizaci贸n puede afectar la experiencia del usuario.

Como soluci贸n m谩s simple pero m谩s costosa, los feeds GBFS puede alojar en un dep贸sito de almacenamiento web como Google Cloud Platform, Amazon S3 o Azure Blob. Administre los costos eligiendo un dep贸sito de almacenamiento web con el modelo de precios adecuado para usted y adjuntando un equilibrador de carga al dep贸sito, como Google Cloud CDN. Aseg煤rese de que la duraci贸n del cach茅 sea menor que la frecuencia de actualizaci贸n para ofrecer siempre la 煤ltima versi贸n de sus feeds.

Cree una API para exponer sus feeds GBFS

Como alternativa, puede exponer sus feeds a trav茅s de puntos finales de API en lugar de un dep贸sito de almacenamiento web.

Sin embargo, requerir autenticaci贸n de datos GBFS no cumple con la especificaci贸n y disminuye en gran medida su valor para los operadores. De hecho, al abrir sus datos, permite que los desarrolladores e investigadores los utilicen para mejorar las ofertas de movilidad compartida y aumentar la capacidad de descubrimiento de sus servicios.

Los operadores que reciben muchas solicitudes que sobrecargan su sistema a menudo implementan una estrategia de almacenamiento en cach茅, como Amazon CloudFront o Varnish Cache.

Licencias

Recomendamos especificar t茅rminos de uso liberales (consulte la lista de licencias comunes). Esto permite a los defensores, acad茅micos o los medios almacenar y analizar sus feeds p煤blicos para mejorar los servicios de movilidad compartida. debe especificar el tipo de licencia en system_information.json.

Agregar el gbfs.json URL del archivo o punto final API en MobilityData systems.csv cat谩logo. Permite a los desarrolladores crear software sobre 茅l, proporciona una fuente para proyectos de investigaci贸n y demuestra el alcance de la especificaci贸n en todo el mundo. Para agregar un sistema, bifurque el repositorio y env铆e una Pull Request. Mantenga esta lista ordenada alfab茅ticamente por pa铆s y nombre del sistema. Alternativamente, complete este formulario de contribuci贸n para una contribuci贸n sin Github.

Todos los sistemas debe tener una entrada en systems.csv para que sea compatible con GBFS. Este cat谩logo son datos p煤blicos que nadie puede poseer ni vender, incluido MobilityData. El prop贸sito de este cat谩logo es permitir a los consumidores de datos GBFS encontrar m煤ltiples fuentes en un solo lugar. Tambi茅n puede publicar un anuncio que haga que sus feeds est茅n disponibles para su uso a trav茅s del canal que prefiera (por ejemplo, publicaci贸n de blog, comunicado de prensa, bolet铆n informativo, etc.).

Esfu茅rcese por lograr un tiempo de actividad del 99,9 %

Tener un tiempo de actividad alto es la mejor manera de Garantizar una buena experiencia de usuario en las aplicaciones de planificaci贸n de trip . Utilice un software de monitoreo de tiempo de actividad para garantizar que sus feeds GBFS est茅n disponibles tanto como sea posible.

Aqu铆 hay un ejemplo en el que Transit analiz贸 el tiempo de actividad de 40 feeds en 8 operadores diferentes y comparti贸 los resultados. en esta publicaci贸n de blog (los resultados son de Puede de 2022 y podr铆an estar desactualizados).

4. Valide sus feeds GBFS

El 煤ltimo paso es validar el cumplimiento de sus feeds GBFS para garantizar que las aplicaciones de planificaci贸n de trip y otros consumidores puedan utilizarlos.

Validaci贸n en su proceso

Incluya validaci贸n en sus datos canalizaci贸n para garantizar que sus feeds GBFS sean siempre v谩lidos. Utilice una secuencia de comandos para validar la estructura y los datos de su feed con el esquema GBFS JSON. Si su canalizaci贸n de datos est谩 escrita en Java, puede utilizar Entur de c贸digo abierto validador Java GBFS que utiliza el [esquema JSON GBFS] oficial (https://github.com/MobilityData/gbfs-json-schema).

Validador en l铆nea

Tambi茅n puede utilizar el [validador GBFS] en l铆nea de c贸digo abierto (https://gbfs-validator.mobilitydata.org/?utm_campaign=producer-guide) para identificar errores o advertencias en los datos o la estructura de sus feeds. Gracias a Fluctuo por crear este validador y abrirlo a la comunidad (Github).

Informe del validador

C贸digo abierto en l铆nea creado por la comunidad validador GBFS basado en el esquema JSON GBFS.

Visualizador en l铆nea

Utilice el visualizador GBFS incluido en el validador en l铆nea, para ver la ubicaci贸n de estaciones (si corresponde) y veh铆culos, as铆 como las zonas de geocercado en un mapa.

Visualizador del validador

C贸digo abierto creado por la comunidad visualizador GBFS.

Aparecer en aplicaciones de planificaci贸n de trip que sus feeds son v谩lidos y est谩n disponibles p煤blicamente, puede notifique a las aplicaciones de planificaci贸n de trip que pueden usar sus feeds GBFS para mostrar su servicio de movilidad a los usuarios.

Para aparecer en las aplicaciones de planificaci贸n de trip , aseg煤rese de publicar la informaci贸n de su feed en MobilityData systems.csv cat谩logo (consulte la secci贸n Agregar sus feeds al cat谩logo). Las aplicaciones de planificaci贸n de viajes comprueban peri贸dicamente los feeds presentes en este cat谩logo para a帽adirlos a sus opciones de ruta. Tambi茅n puede comunicarse con el equipo de datos de las aplicaciones para notificarles que su feed est谩 disponible en el cat谩logo, que incluye, entre otros: Citymapper, Moovit, Tr谩nsito y 驴Ad贸nde?.

Para aparecer en Google Maps en dispositivos m贸viles, siga las implementaci贸n del nuevo proveedor instrucciones. Tenga en cuenta que Google Maps tiene directrices para la entrega de feeds espec铆ficas, como la frecuencia de actualizaci贸n y la latencia, y requisitos espec铆ficos para las definiciones de GBFS con algunos campos obligatorio adicionales que son opcional en la referencia de GBFS.

OpenTripPlanner tambi茅n puede obtener datos en tiempo real sobre Sistemas de movilidad compartida con soporte parcial tanto para v1 como para v2.2. Este proyecto de c贸digo abierto es implementado por varias autoridades oficiales de transporte como Entur, como as铆 como aplicaciones independientes. Esta configuraci贸n de ejemplo muestra c贸mo obtener una fuente GBFS de una instancia de OpenTripPlanner. Tenga en cuenta que solo se obligatorio las propiedades url, type y sourceType.

Finalmente, use una soluci贸n de medici贸n de aplicaciones como Google Analytics para Firebase para ver el impacto de publicar GBFS actualizados en la adquisici贸n de usuarios y los ingresos.

Aplicaci贸n de planificaci贸n de viajes

Foto de CardMapr.nl en Unsplash

Obteniendo ayuda

Para participar en debates sobre GBFS y sugerir cambios y adiciones a la especificaci贸n, 煤nase al canal Slack de GBFS y al repositorio de Github.

Las preguntas se pueden dirigir a la comunidad a trav茅s del [canal GBFS Slack] p煤blico (https://share.mobilitydata.org/slack) o al equipo de movilidad compartida en MobilityData: sharedmobility@mobilitydata.org.

Agradecimientos

Agradecemos a los miembros de la comunidad GBFS que respondieron nuestras preguntas t茅cnicas y revisaron esta gu铆a: Entur, Flamingo, Fluctuo, Google, Joyride, Lime, Lyft, Superpeatonal, TIER, transport.data.gouv.fr, Urban Sharing, Vulog y Where To?.