GOFS

The GOFS module provides an implementation of the General On-Demand Feed Specification (GOFS) for Kotlin Multiplatform.

GOFS is a standardized data feed for real-time access to information about on-demand mobility services such as ride-hailing, taxi services, and other demand-responsive transportation.

Modules

• gofs-v1: Implementation of the GOFS v1.0 specification.

Features

• JSON encoding and decoding with kotlinx-serialization
• HTTP client for fetching feeds using Ktor
• Strong type safety, with appropriate standard library or kotlinx-datetime types
• Kotlin Multiplatform support (JVM, Native, JS, WASM)
• GeoJSON support using Spatial-K

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:gofs-v1:0.5.0")
    implementation("io.ktor:ktor-client-cio:3.5.2") // or another engine
}

Example

GofsV1Client().use { gofs -> // (1)!
  val manifest =
    gofs
      .getSystemManifest( // (2)!
        discoveryUrl = "<discovery url>"
      )
      .getOrThrow()
      .data

  context(manifest.getService("en")) { // (3)!
    val systemInfo = gofs.getSystemInformation().getOrThrow().data // (4)!

    println("System: ${systemInfo.name}")
    println("Operator: ${systemInfo.operator}")
    println("Timezone: ${systemInfo.timezone}")

    val serviceBrands = gofs.getServiceBrands().getOrThrow().data // (5)!

    println("\nService Brands:")
    serviceBrands.forEach { brand -> println("  - ${brand.brandName} (ID: ${brand.brandId})") }

    val waitTimes = // (6)!
      gofs.getWaitTimes(pickupLat = 41.8781, pickupLon = -87.6298).getOrThrow().data

    println("\nWait Times:")
    waitTimes.forEach { waitTime ->
      println("  - Brand ${waitTime.brandId}: ${waitTime.waitTime} seconds")
    }
  }
}

1. Create a GOFS client instance. The client implements AutoCloseable so it can be used with .use to ensure proper cleanup.
2. Fetch the manifest (auto-discovery file) which contains URLs for all available feeds in different languages.
3. Use a context parameter to specify which language service to use for subsequent feed requests.
4. Fetch system information including the system name, operator, and timezone.
5. Fetch the list of available service brands with their IDs and names.
6. Fetch real-time wait time estimates for a specific pickup location using latitude and longitude coordinates.

API Reference

For detailed API documentation, see the API Reference.