flightstats-client-scala - a scala client for FlightStats

flightstats-client-scala makes use of Dispatch and Jackson to provide a dead-simple asynchronous client for FlightStats API.

Each API is suppororted by a client class which provides methods for each available endpoint. Response objects are modeled by case classes, except where the number of fields surpasses the case class limit.

Example usage:

// create an instance of a client for the Airports API
val airports = FSAirports(appId, appKey)

// fetch active airports
val activeAirports:Future[Seq[FSAirport]] = airports.active


// create an instance of a client for the Delay Indexes API
val delayIndexes = FSDelayIndexes(appId, appKey)

// optional arguments passed as a map
val delayIndex:Future[FSDelayIndexResponse] =
  delayIndexes.byRegion("Caribbean", Map("classification" -> "3", "score" -> "3"))

Organization:

Each FlightStats API has a corresponding class in com.mobilerq.flightstats.client:

• FSAirports for the Airports API
• FSAlerts for the Alerts API
• FSDelayIndexes for the Delay Index API
• FSFlightStatusByAirport for the Flight Status & Track by Airport API
• FSFlightStatusByFlight for the Flight Status & Track by Flight API
• FSFlightStatusByRoute for the Flight Statys & Track by Route API
• FSFlightsNear for the Flights Near API
• FSRatings for the Ratings API
• FSConnections for the Schedules/Connections API
• FSWeather for the Weather API

Responses are modeled as case classes wherever possible. The three response objects that are not modeled as case classes (due the the restriction of a maximum of 22 fields) are FSFlightLeg, FSRating and FSAirport.

No method on any response object should ever return null - if one does, please submit a bug.

Appendix Helpers:

Many of the FlightStats APIs return an appendix along with the response, containing details about airports or airlines. Users need to look up the details of an airport or airline in the appendix (for example, to fetch the name).

flightstats-client-scala provies a few utilities for helping out with this.

The RichFSAppendix adds lookup methods to the appendix. An implicit conversion from FSAppendix -> RichFSAppendix is provided in the com.mobilerq.flightstats.api.v1 package object. Example usage:

import com.mobilerq.flightstats.api.v1._   // get the implicit conversions

val response = statuses.flightStatus(285645279)

for(r <- response) yield {
  val carrierName = r.flightStatus.carrierFsCode flatMap { r.appendix.airlinesMap.get(_) }
  val arrivalAirportName = r.flightStatus.arrivalAirportFsCode flatMap { r.appendix.airportsMap.get(_) }
}

Looking things up in the appendix is still a bit of a pain, so there are rich response types that can be used for greater convenience. Implicit conversions are provided for most response types that include an appendix. Note that you must explicitly require the rich type on the response, as the compiler cannot figure out that the future needs to be converted for you. If you can improve on this, please send a pull request! Example usage:

import com.mobilerq.flightstats.api.v1._

val response: Future[RichFSFlightStatusResponse] = statuses.flightStatus(285645279)

for(r <- response) yield {
  val carrierName = r.flightStatus.carrier map {_.name}
  val arrivalAirportName = r.flightStatus.arrivalAirport map {_.name}
}

Caching:

All clients support caching using a user supplied guava CacheBuilder. All Client factories accept a guava CacheBuilder as a third argument (after appId and appKey). You can specify the cache properties (for example, the expiration policy) before constructing the client.

val cacheBuilder = CacheBuilder.newBuilder()
                               .expireAfterAccess(10, TimeUnit.MINUTES)
                               .maximumSize(1000)
                               .recordStats()

val client = FSFlightStatusByFlight(appId, appKey, cacheBuilder)

// do some stuff

val cacheStats = client.cacheStats  // NOTE you must have called .recordStats() on the builder in order for stats to have been collected

Running the tests:

The tests run against static JSON test files captured from FlightStats API. You can run the tests against FlightStats live API by supplying your credentials as properties:

mvn -Dflightstats.appId=<my appId> -Dflightstats.appKey=<my appKey> test

If you would like to capture new static JSON test files, add -Dtest.capture=true.