北京实时公交 API 使用指南

项目介绍

Fucking Beijing Bus API 是一个 Swift 语言开发的北京实时公交 API 库，能够获取北京市公交车的实时信息，包括车站公交的到站情况以及公交车的实时定位。数据来源于北京实时公交 App 的接口，相比地图应用提供的信息更加准确。

快速开始

环境要求

• Swift 5.0 或更高版本
• macOS 10.12+ 或 iOS 10+

安装方式

Swift Package Manager 在 Package.swift 文件中添加依赖：

dependencies: [
    .package(url: "https://gitcode.com/gh_mirrors/fu/fucking-beijing-bus-api.git", from: "1.1.0")
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: [.product(name: "fucking-beijing-bus-api", package: "fucking-beijing-bus-api")]
    )
]

CocoaPods 在 Podfile 中添加：

pod 'fucking-beijing-bus-api', :git => 'https://gitcode.com/gh_mirrors/fu/fucking-beijing-bus-api.git'

然后运行 pod install 安装依赖。

核心功能

静态数据获取

import FuckingBeijingBusAPI

// 获取所有公交线路
BeijingBusAPI.Static.getAllLines { result in
    switch result {
    case .success(let lines):
        print("获取到 \(lines.count) 条线路")
    case .failure(let error):
        print("获取失败: \(error)")
    }
}

// 获取线路详细信息
BeijingBusAPI.Static.getLineDetail(ofLine: "线路ID") { result in
    // 处理结果
}

实时数据查询

// 批量获取车站的公交状态
let stations = [
    (lineID: "线路ID1", stationName: "车站名称", indexInBusLine: 1),
    (lineID: "线路ID2", stationName: "另一个车站", indexInBusLine: 2)
]

BeijingBusAPI.RealTime.getLineStatusForStation(stations) { result in
    // 处理实时公交状态
}

// 获取线路所有车辆状态
BeijingBusAPI.RealTime.getAllBusesStatus(
    ofLine: "线路ID", 
    referenceStation: 车站序号
) { result in
    // 处理车辆实时位置信息
}

数据模型

线路元数据 (LineMeta)

包含线路基本信息：

• ID: 线路唯一标识
• busNumber: 公交线路号
• departureStationName: 始发站名称
• terminalStationName: 终点站名称

线路详情 (LineDetail)

包含线路详细信息和站点信息：

• stations: 线路所有车站列表
• operationTime: 运营时间
• 每个车站包含名称、序号和坐标位置

公交状态 (BusStatusForStation)

提供实时公交信息：

• currentLocation: 车辆当前位置坐标
• distanceRemain: 距离参考站点的剩余距离
• estimatedArrivedTime: 预计到达时间
• comingStation: 下一站信息

使用示例

构建公交查询应用

func queryBusArrivalTime(lineID: String, stationName: String, stationIndex: Int) {
    BeijingBusAPI.RealTime.getLineStatusForStation([
        (lineID: lineID, stationName: stationName, indexInBusLine: stationIndex)
    ]) { result in
        DispatchQueue.main.async {
            switch result {
            case .success(let statuses):
                if let status = statuses.first {
                    print("下一班车预计 \(status.estimatedRunDuration) 秒后到达")
                }
            case .failure(let error):
                print("查询失败: \(error.localizedDescription)")
            }
        }
    }
}

缓存策略建议

由于线路信息相对稳定，建议对静态数据进行缓存：

// 使用智能缓存获取线路信息
BeijingBusAPI.Static.Cache.getAllLinesSmartly { result in
    // 优先使用缓存，无缓存时请求网络
}

注意事项

• 所有回调都在主线程返回，编写命令行程序时注意避免死锁
• 线路ID需要通过 getAllLines 接口获取，不是公交车上的线路号码
• 同一个线路的两个方向视为不同的线路，有各自的ID
• 建议对静态线路信息进行本地缓存以减少网络请求

技术实现

该项目基于 Alamofire 进行网络请求，使用 Mappable 进行 JSON 映射，实现了北京实时公交 App 接口的逆向解析和数据加解密处理。

通过合理使用此 API，开发者可以构建各种公交相关的应用，如实时公交查询、出行规划、交通数据分析等工具，为北京市民提供更准确的公共交通信息服务。