soql

R package that helps construct queries for the Socrata Open Data API (SODA), using the Socrata Query Language (SoQL) format. Documentation for SoQL in general, apart from this package, can be found here.

Install

install.packages("soql")

Purpose

soql is not a package for parsing JSON/CSV/XML retrieved from SODA. It only exists to make constructing SODA request URLs easy. Once the URL is created, it can be used by anything: read.socrata from the RSocrata package, fromJSON from jsonlite, or getURL from RCurl if you're really a minimalist. It's up to you.

Usage

Step 1

Always start building your URL with a call to soql(). Optionally, you can pass a string parameter containing an already-created SODA URL you'd like to add to.

Step 2

Next, add to it. soql uses method chaining: each function outputs a new object that can be passed to more functions. Functions always accept this object as their first parameter, which means that soql works beautifully with pipes (%>%).

Functions used to add to a URL, and the documentation for their corresponding parameters, are listed below.

• soql_select: $select
• soql_where: $where
• soql_order: $order
• soql_group: $group
• soql_limit: $limit
• soql_offset: $offset
• soql_q: $q
• soql_simple_filter: simple filters

For more information on any of these functions, simply run ?function_name_here in the R console.

Step 3

When you're ready to use your URL, simply call as.character on it. You can pipe it into as.character as well. This will return your URL in string form.

Step 4

Use your URL!

Example

# Using pipes
library(soql)
soql() %>%
	soql_add_endpoint('https://data.seattle.gov/resource/kzjm-xkqj.json') %>%
	soql_where('datetime IS NOT NULL') %>%
	soql_where('longitude > -122.5') %>%
	soql_q('St') %>%
	as.character()
	#=> [1] "https://data.seattle.gov/resource/kzjm-xkqj.json?$where=datetime%20IS%20NOT%20NULL%20AND%20longitude%20%3E%20-122.5&$q=St"