Swift SODA SDK

Heads up! Swift (the language) is currently still in beta, but if you're a registered Apple developer, you can download the XCode Beta and try it out yourself. For more information, see the Swift resources page.

Swift is an exciting new programming language from Apple. Part of the release of iOS8 for mobile devices and OSX Yosemite for Mac hardware, it makes it dramatically to develop Cocoa and Cocoa Touch apps without needing to write Objective C, yet it works alongside your existing Objective C code and libraries.

Our Swift SDK and sample app make it easy to get started with Swift and help you quickly get up to speed and start building mobile open data applications. Our SDK provides two components for you to leverage:

SODAKit, which provides SODAClient, a wrapper library that helps you to connect to a Socrata Open Data API, formulate SoQL queries, and manipulate the data that is returned.
SODASample, a simple iOS app that queries the City of Chicago’s dataset of Alternative Fuel Locations and renders them in a map view on your iPhone

Getting Started

To get started with the Swift SODA SDK:

Register for an application token for your application
Clone soda-swift
Reference SODAKit/SODAClient.swift in Xcode
Initialize SODAClient:

let client = SODAClient(domain: "data.yourcity.gov", token: "yourapplicationtoken")

Once you have your client, you can get started issuing queries.

Querying Datasets

Here is a simple filter query to find compressed natural gas stations in Chicago:

let fuelLocations = client.queryDataset("f7f2-ggz5")

fuelLocations.filterColumn ("fuel_type_code", "CNG").get { res in
  switch res {
  case .Dataset (let data):
    // Handle data
  case .Error (let error):
    // Deal with the error
  }
}

Note the use of filterColumn to get only compressed natural gas stations.

Also note that the final get function is asynchronous and that the last argument is a completion handler. For your convenience, soda-swift automatically schedules the handler on the main operation queue.

That completion handler is given an enumeration SODADatasetResult with two possible values:

Dataset with an array of rows, if the query succeeded.
Error with the NSError, if the query failed.

Query Options

There are many more query options than just filterColumn. We could have also written:

fuelLocations.filter("fuel_type_code = 'CNG'")

We can also order the results:

fuelLocations.orderAscending("station_name")

We can then limit the results and control the offset to perform paging:

fuelLocations.limit(10).offset(0)

Chaining Queries

Queries can be easily composed and stored in variables. This allows you to keep your code clean and easily construct derivative queries.

For example, we may have an app that has a base query called fuelLocations:

let fuelLocations = client.queryDataset("f7f2-ggz5")

The sample app allows the user to choose two types of stations: natural gas and electric. This decision is encapsulated in the query stations.

let userWantsNaturalGas = true // Get this from the UI

let stations = fuelLocations.filterColumn("fuel_type_code", userWantsNaturalGas ? "CNG" : "ELEC")

The app can also display the data sorted in two different directions and stores this in orderedStations:

let userWantsAscending = true // Get this from the UI

let orderedStations = userWantsAscending ?
    stations.orderAscending("station_name") :
    stations.orderDescending("station_name")

Now the app can easily query the results:

orderedStations.get { result in
    // Display the data or the error
}

API Reference

The full API Reference can be found in Reference.md.

Sample App

A sample app that shows alternative fuel locations in Chicago is included.

Open soda-swift.xcodeproj
Modify SODASample/AppDelegate.swift to insert your access token
Ensure that the target SODASample is selected
Run