WMATA.swift

WMATA.swift is a lightweight Swift interface to the Washington Metropolitan Area Transit Authority API.

Note on WMATA.swift & coming package

In the future, WMATA.swift will be splitting into a few libraries. Currently, WMATA.swift provides a lot of high level functionality on top of the response from the WMATA. In order to better maintain this functionality and support it fully, I am planning on keeping WMATA.swift as a high level, WMATA focused framework, and introducing a new package. This new package will handle basic API interactions and will be a better choice for those looking for lower level interactions with the API. There won't be any feature regression on WMATA.swift, simply making the package simpler to maintain for me.

Note on GTFS

I released a GTFS and GTFS-RT package for Swift and soon this package will be using that package for interaction with GTFS-RT feeds.

Contents

• Requirements
• Installation
• Usage
  • Getting Started
  • Design
  • Using MetroRail
  • Using Station
  • Using MetroBus
  • Background Requests & WMATADelegate
• Dependencies
• Testing
• Contact
• Contributing
• License

Requirements

• Swift 5.1+

Installation

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/emma-k-alexandra/WMATA.swift.git", from: "8.3.0")
]

Usage

Getting Started

import WMATA

MetroRail(key: apiKey).nextTrains(at: .A01) { result in
    switch result {
    case .success(let predictions):
        print(predictions)

    case .failure(let error):
        print(error)

    }

}

Design

WMATA.swift breaks the WMATA API into MetroRail and MetroBus via the MetroRail and MetroBus.

Using MetroRail

lines

WMATA Documentation
Returns basic information on all MetroRail lines.

 MetroRail(key: apiKey).lines { result in
    switch result {
    case .success(let lines):
        print(lines)

    case .failure(let error):
        print(error)

    }

}

entrances

WMATA Documentation
Station entrances within a latlong pair and radius (in meters). Omit all parameters to receive all entrances.

MetroRail(key: apiKey).entrances(at: RadiusAtCoordinates(radius: 1000, coordinates: Coordinates(latitude: 38.8817596, longitude: -77.0166426))) { result in
    switch result {
    case .success(let entrances):
        print(entrances)

    case .failure(let error):
        print(error)

    }

}

stations

WMATA Documentation
Stations along a Line (optional)

MetroRail(key: apiKey).stations(for: .BL) { result in
    switch result {
    case .success(let stations):
        print(stations)

    case .failure(let error):
        print(error)

    }

}

station

WMATA Documentation
Distance, fare information and estimated travel time between two stations. Omit both station codes for all possible trips.

MetroRail(key: apiKey).station(.A01, to: .A02) { result in 
    switch result {
    case .success(let travelInfo):
        print(travelInfo)

    case .failure(let error):
        print(error)

    }

}

positions

WMATA Documentation
Uniquely identifiable trains in service and what track circuits they currently occupy

MetroRail(key: apiKey).positions { result in
    switch result {
    case .success(let positions):
        print(positions)

    case .failure(let error):
        print(error)

    }

}

routes

WMATA Documentation
Ordered list of track circuits, arranged by line and track number

MetroRail(key: apiKey).routes { result in 
    switch result {
    case .success(let routes):
        print(routes)

    case .failure(let error):
        print(error)

    }

}

circuits

WMATA Documentation
List of all track circuits - also see TrainPositionsFAQ

MetroRail(key: apiKey).circuits { result in 
    switch result {
    case .success(let circuits):
        print(circuits)

    case .failure(let error):
        print(error)

    }

}

elevatorAndEscalatorIncidents

WMATA Documentation
Reported elevator and escalator incidents

MetroRail(key: apiKey).elevatorAndEscalatorIncidents(at: .A01) { result in
    switch result {
    case .success(let incidents):
        print(incidents)

    case .failure(let error):
        print(error)

    }

}

incidents

WMATA Documentation
Reported MetroRail incidents at a particular station (optional)

MetroRail(key: apiKey).incidents(at: .A01) { result in
    switch result {
    case .success(let incidents):
        print(incidents)

    case .failure(let error):
        print(error)
    }

}

stations

WMATA Documentation
Stations along a Line

 MetroRail(key: apiKey).stations(for: .BL) { result in 
    switch result {
    case .success(let stations):
        print(stations)

    case .failure(let error):
        print(error)

    }

}

nextTrains

WMATA Documentation
Next train arrivals for this station.

MetroRail(key: apiKey).nextTrains(at: .A01) { result in
    switch result {
    case .success(let predictions):
        print(predictions)

    case .failure(let error):
        print(error)

    }

}

information

WMATA Documentation
Location and address information for this station.

MetroRail(key: apiKey).information(for: .A01) { result in
    switch result {
    case .success(let information):
        print(information)

    case .failure(let error):
        print(error)

    }

}

parkingInformation

WMATA Documentation
Parking information for this station.

MetroRail(key: apiKey).parkingInformation(for: .A01) { result in
    switch result {
    case .success(let parkingInfo):
        print(parkingInfo)

    case .failure(let error):
        print(error)

    }

}

path

WMATA Documentation
Returns a set of ordered stations and distances between stations on the same line

MetroRail(key: apiKey).path(from: .A01 to: .A02) { result in
    switch result {
    case .success(let path):
        print(path)

    case .failure(let error):
        print(error)

    }

}

timings

WMATA Documentation
Opening times and scheduled first and last trains for this station

MetroRail(key: apiKey).timings(for: .A01) { result in
    switch result {
    case .success(let timings):
        print(timings)

    case .failure(let error):
        print(error)

    }

}

Using Station

The Station enum provides a lot of additional information for stations that you can use without having to make network requests.

name

let name = Station.A01.name // "Metro Center"

name provides an easy way to get a human readable and presentable string of the station's name.

lines

let lines = Station.A01.lines // [.BL, .OR, .SV, .RD]

lines provides the Lines a station is on without making a network request.

openingTime(:)

let openingTime = Station.A01.openingTime() // ("2020-01-12 08:14:00 +0000")

openingTime provides the opening time of a station without making a network request. Note: This is only accurate generally, not on event days. For guaranteed accurate information use the timings method on a Station or MetroRail.

Using MetroBus

positions

WMATA Documentation
Bus positions along a route (optional), at a latlong and within a radius (in meters)

MetroBus(key: apiKey).positions(on: ._10A, at: RadiusAtCoordinates(radius: 1000, coordinates: Coordinates(latitude: 38.8817596, longitude: -77.0166426))) { result in
    switch result {
    case .success(let positions):
        print(positions)

    case .failure(let error):
        print(error)

    }

}

routes

WMATA Documentation
All bus routes

MetroBus(key: apiKey).routes { result in
    switch result {
    case .success(let routes):
        print(routes)

    case .failure(let error):
        print(error)

    }

}

searchStops

WMATA Documentation
Stops near a given latlong and within a given radius. Omit all parameters to receive all stops.

MetroBus(key: apiKey).searchStops(at: RadiusAtCoordinates(radius: 1000, coordinates: Coordinates(latitude: 38.8817596, longitude: -77.0166426))) { result in
    switch result {
    case .success(let stops):
        print(stops)

    case .failure(let error):
        print(error)

    }

}

incidents

WMATA Documentation
MetroBus incidents along an optional route.

MetroBus(key: apiKey).incidents(on: ._10A) { result in
    switch result {
    case .success(let incidents):
        print(incidents)

    case .failure(let error):
        print(error)

    }

}

positions

WMATA Documentation
Bus positions along this route, within an optional latlong and radius (in meters).

MetroBus(key: apiKey).positions(at: ._10A, at: RadiusAtCoordinates(radius: 1000, coordinates: Coordinates(latitude: 38.8817596, longitude: -77.0166426))) { result in
    switch result {
    case .success(let positions):
        print(positions)

    case .failure(let error):
        print(error)

    }

}

pathDetails

WMATA Documentation
Ordered latlong points along this Route for a given date. Omit for today.

MetroBus(key: apiKey).pathDetails(for: ._10A) { result in
    switch result {
    case .success(let path):
        print(path)

    case .failure(let error):
        print(error)

    }

}

schedule

WMATA Documentation
Scheduled stops for this Route

MetroBus(key: apiKey).schedule(for: ._10A) { result in
    switch result {
    case .success(let schedule):
        print(schedule)

    case .failure(let error):
        print(error)

    }

}

nextBuses

WMATA Documentation
Next bus arrivals at this Stop

MetroBus(key: apiKey).nextBuses(for: Stop(id: "1001195")) { result in
    switch result {
    case .success(let predictions):
        print(predictions)

    case .failure(let error):
        print(error)

    }

}

schedule

WMATA Documentation
Buses scheduled to arrival at this Stop at a given date. Omit for today.

MetroBus(key: apiKey).schedule(for: Stop(id: "1001195")) { result in
    switch result {
    case .success(let schedule):
        print(schedule)

    case .failure(let error):
        print(error)

    }

}

Background Requests & WMATADelegate

Background requests can be made using aWMATADelegate on MetroRail or MetroBus. First, create a class implementing WMATADelegate:

import WMATA

class Delegate: WMATADelegate {

}

Then implement the received method for whichever method you plan on calling on the MetroBus or MetroRail object this delegate belongs to. For example, if yoy plan on calling lines on MetroRail, implement received(linesResponse: on your delegate.

class Delegate: WMATADelegate {
    func received(linesResponse result: Result<LinesResponse, WMATAError>) {
        switch result {
        case .success(let lines):
            print(lines)

        case .failure(let error):
            print(error)

        }

    }

}

Finally, create a MetroBus or MetroRail instance with an instance of your delegate and make requests!

let delegate = Delegate()
let metroRail = MetroRail(key: apiKey, delegate: delegate)

metroRail.lines()

Dependencies

• swift-protobuf, for GTFS-RT feeds.

Testing

Currently, afaik Xcode doesn't provide a way to run tests in succession rather than in parallel. So, as of v5, tests musts be run manually & individually. No fun, I know. Working on a solution for future versions.

Contact

Feel free to email questions and comments to emma@emma.sh

Contributing

Todo:

• ☐ Last Train times (API doesn't provide full information here)
• ☐ Documentation of response structs a la wmata
• ☐ Figure out README structure
• ☐ Provide more documentation for methods on Station, Line, Route and Stop
• ☐ Figure out how to serialize tests
• ☐ Automated builds
• ☐ Possible support for CocoaPods/Carthage?

License

WMATA.swift is released under the MIT license. See LICENSE for details.