Feeds GBFS 3.0

GBFS 3.0 e a spec contra a qual o validador da MobilityData agora verifica, e a maioria das novas licencas de cidades tier-1 a referenciam explicitamente. O Levy Fleets publica ambos os feeds em paralelo:

Raiz do feed -- gbfs.json

curl https://fleets.levyelectric.com/api/gbfs/v3/<subaccountId>/gbfs.json

Retorna o documento de discovery com caminhos para todo outro arquivo de feed:

{
  "last_updated": "2026-05-18T12:00:00Z",
  "ttl": 60,
  "version": "3.0",
  "data": {
    "feeds": [
      { "name": "manifest", "url": "..." },
      { "name": "system_information", "url": "..." },
      { "name": "vehicle_types", "url": "..." },
      { "name": "vehicle_status", "url": "..." },
      { "name": "station_information", "url": "..." },
      { "name": "station_status", "url": "..." },
      { "name": "system_regions", "url": "..." },
      { "name": "system_pricing_plans", "url": "..." },
      { "name": "geofencing_zones", "url": "..." },
      { "name": "system_alerts", "url": "..." }
    ]
  }
}

O que ha de novo vs GBFS 2.x

manifest.json

Novo em 3.0. Declara idiomas, a versao GBFS e o esquema de auth (se houver). O manifest do Levy e gerado da default_language da subconta mais quaisquer idiomas com pelo menos um campo localizado.

{
  "last_updated": "2026-05-18T12:00:00Z",
  "ttl": 60,
  "version": "3.0",
  "data": {
    "datasets": [
      {
        "system_id": "levy-<subaccountId>",
        "versions": [
          { "version": "3.0", "url": ".../v3/<subaccountId>/gbfs.json" },
          { "version": "2.3", "url": ".../<subaccountId>/gbfs.json" }
        ]
      }
    ]
  }
}

O manifest e o que diz aos agregadores de discovery (MobilityData, apps de transito) que tanto 2.x quanto 3.0 estao disponiveis para o mesmo sistema.

vehicle_status.json

Substitui free_bike_status.json. Cada linha carrega uma vehicle_type_id que referencia vehicle_types.json:

{
  "version": "3.0",
  "last_updated": "2026-05-18T12:00:00Z",
  "ttl": 60,
  "data": {
    "vehicles": [
      {
        "vehicle_id": "abc123",
        "vehicle_type_id": "scooter_standard",
        "lat": 40.0149,
        "lon": -105.2705,
        "current_range_meters": 18000,
        "is_reserved": false,
        "is_disabled": false,
        "last_reported": "2026-05-18T11:59:47Z"
      }
    ]
  }
}

O vehicle_type_id do veiculo flui de vehicles.model_id -> vehicle_models.gbfs_type_id. Defina o segundo em Configuracoes -> Modelos de Veiculos ao importar novos SKUs.

geofencing_zones.json -- zonas de operador + politica mescladas

Este e o arquivo onde a conformidade municipal aparece no feed publico. Ele contem toda zona do operador (parking, no-parking, slow, no-go, ride zones) mais toda linha policy_geofences ativa para a subconta. Cada feature emite o vehicle_type_id correto por regra por Policy MDS.

A ordem importa: features sao ordenadas por prioridade descendente, entao consumidores que escolhem o "primeiro match" obtem a regra mais restrita. Veja Prioridade de Geofences Empilhados.

{
  "version": "3.0",
  "last_updated": "2026-05-18T12:00:00Z",
  "ttl": 60,
  "data": {
    "geofencing_zones": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {
            "name": "Boulder Pearl Street No-Ride",
            "rules": [
              {
                "vehicle_type_ids": ["scooter_standard"],
                "ride_allowed": false,
                "ride_through_allowed": false
              }
            ],
            "priority": 950,
            "source": "city",
            "source_jurisdiction_id": "boulder-co"
          },
          "geometry": { "type": "Polygon", "coordinates": [ ... ] }
        }
      ]
    }
  }
}

As propriedades priority, source e source_jurisdiction_id sao extensoes Levy sobre o esquema GBFS -- sao ignoradas por validadores e consumidas por clientes (incluindo nosso proprio app movel) que entendem a semantica de pilha.

system_regions.json

Novo em 3.0. Util quando uma unica subconta opera em multiplas regioes geograficas distintas (por exemplo, campus separados ou bairros). O Levy emite uma regiao por linha mds_jurisdictions por padrao; voce pode editar nomes e rotulos de idioma em Compliance -> Jurisdicoes -> Editar -> Regioes.

system_alerts.json

Carrega alertas publicados pelo operador (interrupcoes planejadas, eventos especiais, restricoes climaticas). Atualmente dirigido pela UI Configuracoes -> Alertas; ligado a subconta, nao por jurisdicao.

Cache

Como o feed MDS, endpoints GBFS 3.0 sao cacheados na borda por 60 segundos (Cache-Control: public, s-maxage=60). O valor ttl em cada payload de arquivo corresponde a janela de cache.

Configuracao do validador

Use o gbfs-validator da MobilityData para verificacoes ponta a ponta:

gbfs-validator https://fleets.levyelectric.com/api/gbfs/v3/<subaccountId>/gbfs.json

Um run limpo reporta Errors: 0, Warnings: 0. Avisos comuns ao fazer primeiro onboarding:

• vehicle_type_id ausente em um veiculo -- defina vehicle_models.gbfs_type_id para cada modelo em sua frota.
• system_regions.json vazio -- adicione pelo menos uma linha mds_jurisdictions, ou remova o arquivo de gbfs.json se voce nao opera em multiplas regioes.
• pricing_plans ausente -- defina pelo menos uma linha em pricing_plans para a subconta.

Como v2 e v3 ficam em sincronia

Ambos os feeds leem das mesmas tabelas subjacentes (vehicles, vehicle_models, zones, policy_geofences, stations, pricing_plans). Nao ha caminho de escrita separado para v3, entao uma mudanca no dashboard aparece em ambos os feeds no proximo ciclo de cache de 60 segundos.

Os unicos arquivos que vivem apenas em v3 sao manifest.json e system_regions.json. Remover o feed v3 (se uma cidade so precisa de v2.x) e apenas uma questao de nao apontar para a URL /v3/.

Proximos passos

• Ingestao de Politica de Cidades -- de onde vem os geofences de politica mesclados em geofencing_zones.json.
• Prioridade de Geofences Empilhados -- a escada de prioridade aplicada quando zonas se sobrepoem.
• Configuracao do MDS Provider -- os endpoints MDS assinados que cidades consomem ao lado do GBFS.