November 22, 2021 8:59 pm

GBFS v2.3-RC está aqui para resolver (alguns) dos seus problemas

*Puede encontrar una traducción de este artículo al español aquí.*

*Vous pouvez trouver une version francophone de cet article ici.*

Temos gostado muito de ver feeds GBFS v2.2 surgindo no mundo todo – alimentando tantas novas integrações no planeamento de viagens, facilitando aos passageiros encontrar a bicicleta, scooter, ciclomotor ou carro mais próximos!

Mas embora amamos a v2.2, a GBFS estava pronta para algumas melhorias. Permita-nos apresentar a v2.3-RC!

Photo: Bicicleta Capital Bikeshare com etiqueta de reparo. Crédito: Charles Hagman 

Resumindo, a v2.3-RC adiciona informações sobre:

  • Estações com capacidade de recarga,
  • Restrições para devolução de veículos,
  • Ícones de veículos e informação de marca,
  • Tempos de reserva do veículo, e
  • Termos & política de privacidade.

Para facilitar a vida em sistemas baseados em estações, a v2.3-RC também possibilita apresentar informações de preço por tipo de veículo, em vez de apenas por veículo individual.

Por que escolher a GBFS v2.3-RC? Essa versão permite melhores descrições dos serviços disponíveis – facilitando aos produtores e consumidores fornecer aos viajantes as informações que precisam.

Vamos então detalhar um pouco mais cada uma dessas mudanças. Depois, forneceremos exemplos de dados para desenvolvedores.

Alterações em detalhe

Estações de recarga

Em versões anteriores da GBFS não era possível informar que uma estação poderia oferecer recarga para veículos. Sem surpresa, notamos uma variedade de soluções diferentes e não padronizadas adicionadas aos conjuntos-padrão de dados GBFS. A v2.3-RC adicionou uma forma simples de indicar se uma estação fornece recarga. No futuro, isso facilitará representar programas que fornecem incentivos para estacionamento tais estações, ou que exigem que um aluguel seja devolvido a uma delas.

Restrições para devolução de veículos

A maioria dos serviços compartilhados de bicicletas, scooters e ciclomotores permite aluguéis de um ponto a outro, ao contrário, por exemplo, de aluguéis tradicionais de carros, que são recolhidos e devolvidos no mesmo local. Mas como a GBFS é estendida para representar compartilhamento de carros (com seu universo de diferentes modelos operacionais), e como os serviços de mobilidade compartilhados incluem, cada vez mais, pilotos automáticos adaptativos (geralmente com regras de aluguel mais restritivas), a GBFS precisava de uma maneira de representar as restrições de entrega.

A v2.3-RC permite que os provedores de mobilidade compartilhada definam se a exigência de devolução do veículo é de flutuação livre (devolução em qualquer lugar dentro da área de serviço), ida e volta (devolução na estação de aluguel original) ou estação (devolução estação dentro da área de serviço).

Gráfico: exemplo de viagem que requer o retorno do veículo à sua estação original.

Ícones e Marcas

Os conjuntos públicos de dados GBFS facilitam a qualquer aplicativo de planejamento de viagem ofertar serviços de mobilidade compartilhados mais fáceis de localizar e utilizar. Mas, versões anteriores não forneciam uma forma de representar graficamente diferentes operadores ou veículos, demandando trabalho extra dos produtores e consumidores da especificação. A v2.3-RC adiciona informações sobre o logotipo e cores da marca do sistema de mobilidade compartilhada, além de ícones de tipo de veículo, para ajudar a garantir uma representação gráfica consistente (e, portanto, de fácil reconhecimento pelos viajantes!).

Tempo de reserva do veículo

 Muitos serviços de mobilidade compartilhada permitem ao viajante reservar um veículo imediatamente antes de um aluguel. O período de reserva é normalmente inferior a 30 minutos. Durante esse tempo, o veículo não pode ser alugado por outro usuário. Se a viagem não for iniciada antes do término do tempo de reserva, o veículo será liberado e ficará disponível para outros usuários. Na v2.3-RC, a GBFS pode representar o tempo de espera permitido por tipo de veículo, tornando mais fácil para os aplicativos de planejamento de viagem fornecerem aos viajantes opções com benefícios pela possibilidade de reserva do veículo.

Captura de tela: aplicativo Baywheels.

Termos e política de privacidade

A v2.3-RC inclui campos para um provedor de mobilidade compartilhada divulgar seus termos de uso e política de privacidade, tornando mais fácil para os viajantes acessarem essas informações ao considerar um serviço.

Preços para sistemas baseados em estações

 Como dissemos antes, estamos entusiasmados em ver a v2.2 adotada tão amplamente! Essa versão melhorou e muito as informações sobre preços (leia mais sobre isso aqui). Uma mudança que ela trouxe foi adicionar uma id de planos de preços de preços às informações sobre uma bicicleta disponível, associando tais planos a veículos individuais. A ideia era que fazer isso a nível de veículo individual permitiria uma precificação dinâmica com base na localização do veículo – o que de fato ocorre! Mas essa solução representou um desafio para os sistemas baseados em estações, uma vez que eles não são obrigados a publicar o arquivo com informações sobre as bicicletas individuais disponíveis (eles podem publicar essas informações a nível de estação). Ela também limitou os veículos a um plano de preços único.

A v2.3-RC permite uma precificação representada por tipo de veículo, onde é possível que mais de uma categoria de preços seja aplicada, e que operadores definam uma tabela de preços padrão, a ser utilizada por planejadores de viagem ao calcular o custo.

Quer mais detalhes? Leia a seção abaixo!


Descrições e exemplos de código

Estações de recarga

A v2.3-RC adiciona um campo booleano opcional is_charging_station a station_information.json. Ele indica se uma estação suporta o carregamento de veículos elétricos. Veja o exemplo abaixo no bloco de código station_information.json.

Restrições para devolução de veículos

A v2.3-RC adiciona um campo return_type opcional a vehicle_types.json, que permite aos operadores definir se o veículo é free_floating (devolução em qualquer lugar dentro da área de serviço), ida e volta (devolução na estação de aluguel original) ou estação (devolução em qualquer estação dentro da área de serviço). O campo é moldado como uma matriz para levar em conta veículos híbridos com múltiplas opções de devolução. Veja o exemplo abaixo no bloco de código vehicle_types.json.

Além disso, para englobar exceções onde um veículo deve ser devolvido a uma estação específica que não é a original, um campo home_station_id foi adicionado a free_bike_status.json. Veja o exemplo abaixo no bloco de código free_bike_status.json.

Ícones e informações de marca

A v2.3-RC adiciona campos a system_information.json e vehicle_types.json para suportar informações de marca e ícones dos veículos.

Em vehicle_types.json, um novo campo opcional de objeto JSON – vehicle_assets – foi adicionado. Dentro de vehicle_assets um operador pode compartilhar:

  • um URL para um arquivo SVG v1.1 de ícone gráfico de veículo (icon_url),
  • um URL para um arquivo SVG v1.1 de ícone gráfico de veículo para o modo escuro (icon_url_dark), e
  • a última vez que os ícones referenciados foram atualizados (icon_last_modified).

Se vehicle_assets for definido, icon_url e icon_last_modified são condicionalmente necessários. Veja o exemplo abaixo no bloco de código vehicle_types.json.

Em system_information.json, um novo campo opcional de objeto JSON – brand_assets – foi adicionado. Neste campo um operador pode compartilhar:

  • um URL para uma imagem gráfica SVG v1.1 da marca (brand_image_url),
  • um URL para uma imagem gráfica SVG v1.1 da marca para modo escuro (brand_image_url_dark),
  • a última vez que as imagens referenciadas foram atualizadas (brand_last_modified),
  • uma cor usada para representar a marca, expressa por um código de cor hexadecimal de seis dígitos, e
  • um link para os termos de licença de uso dos ativos da marca (brand_terms_url).

Se brand_assets for definido, brand_image_url e brand_last_modified são condicionalmente necessários. Veja o exemplo abaixo no bloco de código station_information.json.

Tempo de reserva do veículo

v2.3-RCA v2.3-RC adiciona um campo opcional default_reserve_time a vehicle_types.json, que define a duração máxima da reserva de um veículo antes do início de uma locação. O nome do campo foi escolhido para poder incluir outros casos de uso no futuro (por exemplo, tempo máximo de reserva associado a um plano de preços). Veja o exemplo abaixo no bloco de código vehicle_types.json.

Termos e política de privacidade

A v2.3-RC adiciona quatro novos campos opcionais a system_information.json. Um operador agora pode compartilhar um URL (terms_url) direcionando a seus termos de serviço (“termos de uso” ou “termos e condições”), e um URL (privacy_url) para a política de privacidade. Ambos são acompanhados de outros dois para indicar a última vez em que a política foi atualizada no URL – terms_last_updated e privacy_last_updated. Se privacy_url for definido, privacy_last_updated é necessário. Da mesma forma, se terms_url for definido, terms_last_updated é requerido. Veja o exemplo abaixo no bloco de código station_information.json.

Preços

A v2.3-RC adiciona uma matriz pricing_plan_ids a vehicle_types.json que contém os IDs de todos os planos de preços aplicáveis àquele tipo de veículo. Ela também adiciona um campo (default_pricing_plan_id) que define um plano padrão a ser usado pelos planejadores de viagens ao calcularem custos de uma viagem única.

A capacidade de definir planos de preços a nível de veículo individual está mantida, permitindo preços determinados com base na localização do veículo ou outros fatores. Qualquer plano de preços atribuído a veículos individuais em free_bike_status.json substitui o plano padrão definido em vehicle_types.json. Veja o exemplo abaixo no bloco de código vehicle_types.json.

Mais detalhes para os Desenvolvedores de Mobilidade Compartilhada

–> vehicle_types.json

Exemplo de representação de restrições para entrega de veículos, ícones e ativos de marca, tempos de reserva de veículo e preços por tipo de veículo.

Neste exemplo, temos três tipos de veículos diferentes:

  • Uma bicicleta não elétrica que pode ser reservada por 30 minutos antes da viagem, devolução em qualquer estação ou em qualquer lugar na área de serviço (ou conforme restrição em geofencing_zones.json), ícones do veículo disponíveis para o modo normal e escuro, e a qual três planos de preços diferentes podem ser aplicados (sendo um identificado como padrão).
  • Uma scooter elétrica que pode ser reservada por 30 minutos antes da viagem, alcance máximo de 12.345 metros com carga total, devolução em qualquer lugar na área de serviço (ou restrita por geofencing_zones.json), ícones do veículo disponíveis para o modo normal e escuro e um plano de preços único aplicado.
  • Um sedã de quatro portas com motor a combustão que não pode ser reservado antes da viagem, alcance máximo de X com tanque cheio, devolução na estação de locação original, ícones do veículo disponíveis para o modo normal e escuro, e para o qual se aplica um plano único de preços.
{
  "last_updated": 1632269413,
  "ttl": 60,
  "version": "2.3",
  "data": {
    "vehicle_types": [
      {
        "vehicle_type_id": "abc123",
        "form_factor": "bicycle",
        "propulsion_type": "human",
        "name": "Example Basic Bike",
        "default_reserve_time": 30,
        "return_type": [
          "any_station",
          "free_floating"
        ],
        "vehicle_assets": {
          "icon_url": "https://www.example.com/assets/icon_bicycle.svg",
          "icon_url_dark": "https://www.example.com/assets/icon_bicycle_dark.svg",
          "icon_last_modified": "2021-06-15"
        },
        "default_pricing_plan_id": "bike_plan_1",
        "pricing_plan_ids": [
          "bike_plan_1",
          "bike_plan_2",
          "bike_plan_3"
        ]
      },
      {
        "vehicle_type_id": "def456",
        "form_factor": "bicycle",
        "propulsion_type": "electric",
        "name": "Example E-bike V2",
        "default_reserve_time": 30,
        "max_range_meters": 12345,
        "return_type": [
          "any_station"
        ],
        "vehicle_assets": {
          "icon_url": "https://www.example.com/assets/icon_ebike.svg",
          "icon_url_dark": "https://www.example.com/assets/icon_ebike_dark.svg",
          "icon_last_modified": "2021-06-15"
        },
        "default_pricing_plan_id": "ebike_plan_1"
      },
      {
        "vehicle_type_id": "car1",
        "form_factor": "car",
        "propulsion_type": "combustion",
        "name": "Four-door Sedan",
        "default_reserve_time": 0,
        "max_range_meters": 523992,
        "return_type": [
          "roundtrip_station"
        ],
        "vehicle_assets": {
          "icon_url": "https://www.example.com/assets/icon_car.svg",
          "icon_url_dark": "https://www.example.com/assets/icon_car_dark.svg",
          "icon_last_modified": "2021-06-15"
        },
        "default_pricing_plan_id": "car_plan_1"
      }
    ]
  }
}

–> free_bike_status.json

Exemplo de representação de restrição de devolução de veículo em que este deve ser devolvido a uma estação específica, podendo não ser a estação de retirada (home_station_id).

Neste exemplo, você pode ver duas bicicletas – ambas disponíveis para aluguel (para ambas, is_reserved e is_disabled são falsos). Uma não é elétrica e a outra sim, localizada em uma estação (station_id 86). A bicicleta elétrica localizada na estação pode percorrer 6.543 metros com a carga atual, tem um plano único de preços e deve ser devolvida em outra estação (station_id 146) ao final da viagem. Para este exemplo, o arquivo acompanhante vehicle_types.json precisa definir vehicle_type_id como pelo menos o campo any_station return_type.

{
  "last_updated": 1609866247,
  "ttl": 0,
  "version": "3.0",
  "data": {
    "bikes": [
      {
        "bike_id": "ghi789",
        "last_reported": 1609866109,
        "lat": 12.345678,
        "lon": 56.789012,
        "is_reserved": false,
        "is_disabled": false,
        "vehicle_type_id": "abc123"
      },
      {
        "bike_id": "jkl012",
        "last_reported": 1609866204,
        "is_reserved": false,
        "is_disabled": false,
        "vehicle_type_id": "def456",
        "current_range_meters": 6543,
        "station_id": "86",
        "pricing_plan_id": "plan3",
        "home_station_id": "146"
      }
    ]
  }
}

–> system_information.json

Exemplo de representação dos campos termos, política de privacidade e ativos de marca.

Neste exemplo, você pode ver um sistema que definiu muitos campos opcionais, incluindo todos os novos campos adicionados na v2.3-RC: terms_url, terms_last_updated, privacy_url, privacy_last_updated, e todos os campos disponíveis em brand_assets (brand_last_modified, brand_image_url, brand_image_url_dark, color e terms_url).

{
  "last_updated": 1611598155,
  "ttl": 1800,
  "version": "3.0",
  "data": {
    "system_id": "example_cityname",
    "language": "en",
    "name": "Example Bike Rental",
    "short_name": "Example Bike",
    "operator": "Example Sharing, Inc",
    "url": "https://www.example.com",
    "purchase_url": "https://www.example.com/join",
    "start_date": "2010-06-10",
    "phone_number": "1-800-555-1234",
    "email": "customerservice@example.com",
    "feed_contact_email": "datafeed@example.com",
    "timezone": "US/Central",
    "license_url": "https://www.example.com/data-license.html",
    "terms_url": "https://www.example.com/terms-of-service.html",
    "terms_last_updated": "2021-09-23",
    "privacy_url": "https://www.example.com/privacy-policy.html",
    "privacy_last_updated": "2021-09-25",
    "brand_assets": {
        "brand_last_modified": "2021-06-15",
        "brand_image_url": "https://www.example.com/assets/brand_image.svg",
        "brand_image_url_dark": "https://www.example.com/assets/brand_image_dark.svg",
        "color": "#C2D32C",
        "terms_url": "https://www.example.com/assets/brand.pdf"
      }
      
  }
}

Em breve voltaremos com mais atualizações!