Mobility Database¶

The mdb-v1 module is a client for the Mobility Database Catalog API.

The types are handwritten against the OpenAPI assets from the MobilityData/mobility-feed-api release named in mdb-v1/specs/pin.toml.

Features¶

JSON encoding and decoding with kotlinx-serialization
HTTP client for the catalog using Ktor
Refresh-token exchange with a single retry on 401
Kotlin Multiplatform support (JVM, Native, JS, WASM)

Installation¶

Add the dependency to your build.gradle.kts. The client functionality requires Ktor, so also add a Ktor engine:

dependencies {
    implementation("dev.sargunv.mobility-data:mdb-v1:0.5.0")
    implementation("io.ktor:ktor-client-cio:3.5.2") // or another engine
}

Example¶

MdbV1Client(auth = CatalogAuth.Refresh("<refresh token>")).use { mdb -> // (1)!
  val feeds = mdb.getFeeds(FeedQuery(limit = 10)).getOrThrow() // (2)!

  feeds.forEach { feed ->
    when (feed) { // (3)!
      is Feed.Gtfs -> println("GTFS ${feed.id} ${feed.provider}")
      is Feed.GtfsRt -> println("GTFS-RT ${feed.id} ${feed.provider}")
      is Feed.Gbfs -> println("GBFS ${feed.id} ${feed.provider}")
      is Feed.Unknown -> println("${feed.dataType} ${feed.id} ${feed.provider}")
    }
  }
}

Create a catalog client with a refresh token. The client implements AutoCloseable so it can be used with .use.
List feeds. The first call posts to /v1/tokens/access, then retries the request with the bearer token. A bare getFeeds() uses the catalog default of 3500 rows. The example passes limit = 10. Other list paths default to 2500 (GTFS), 1000 (GTFS-RT), 500 (GBFS and datasets), or 100 (locations, licenses, availability).
Read the sealed Feed subclass. GTFS, GTFS-RT, and GBFS share status, official, seasonal, and related links. An unrecognized data_type decodes as Feed.Unknown.

API Reference¶

For detailed API documentation, see the API Reference.