Helps Make Socrata Open Data API Calls

Description

Used to construct the URLs and parameters of 'Socrata Open Data API' <https://dev.socrata.com> calls, using the API's 'SoQL' parameter format. Has method-chained and sensical syntax. Plays well with pipes.

Details

To create a SoQL URL, or just parameters for one, start with soql(). Then chain the result into other functions, such as soql_where() or soql_order(). When you're done, use as.character() to retrieve the finished URL, for use with any networking package.

Author(s)

Zeb Burke-Conte

Maintainer: "Zeb Burke-Conte" <zmbc@uw.edu>

References

Documentation for the SODA API

Examples

if (require(magrittr)) {
  # With pipes
  my_url <- soql() %>%
    soql_where("height > 30") %>%
    soql_limit(20) %>%
    as.character()
} else {
  # Without pipes
  soql_chain <- soql()
  soql_chain <- soql_where(soql_chain, "height > 30")
  soql_chain <- soql_limit(20)
  my_url <- as.character(soql_chain)
}

Create a soql object

Description

This is the constructor for soql objects. It will most often be called with no parameters, and be used at the start of a chain of functions. It is necessary to use this function before any others in the soql package.

Usage

soql(query = "")

Arguments

Value

Returns a soql object.

Examples

soql()

soql("a.socrata.endpoint?$select=*&$order=height")

Internal Functions

Description

These functions are for use internally only.

Usage

## S3 method for class 'soql'
as.character(x, ...)
## S3 method for class 'soql'
print(x, ...)

Arguments

Examples

as.character.soql(soql())
print.soql(soql())

Add SODA API endpoint

Description

Add an endpoint to an already-existing soql object.

Usage

soql_add_endpoint(soql_list, endpoint)

Arguments

Value

Returns a new soql object, with the endpoint added, for use in other functions.

References

Socrata's documentation on what an endpoint is

See Also

soql

Examples

if (require(magrittr)) {
  # With pipes
  my_url <- soql() %>%
    soql_add_endpoint("https://fake.soda.api/resource.json") %>%
    as.character()
} else {
  # Without pipes
  soql_chain <- soql()
  soql_chain <- soql_add_endpoint(soql_chain, "https://fake.soda.api/resource.json")
  my_url <- as.character(soql_chain)
}

Limit the number of results from a SODA response

Description

Adds a parameter to the SODA URL that limits how many responses the API will send back.

Usage

soql_limit(soql_list, limit)

Arguments

Value

Returns a new soql object, with a limit parameter added, for use in other functions.

References

Documentation on the SODA website

See Also

soql_offset

Examples

if (require(magrittr)) {
  # With pipes
  my_url <- soql() %>%
    soql_limit(5) %>%
    as.character()
} else {
  # Without pipes
  soql_chain <- soql()
  soql_chain <- soql_limit(soql_chain, 5)
  my_url <- as.character(soql_chain)
}

Control which records you receive from a SODA API

Description

This function adds a parameter to a soql object that controls what index the returned records start at. For more information, view the SODA documentation linked in the References section below.

Usage

soql_offset(soql_list, offset)

Arguments

Value

Returns a new soql object, with an offset parameter added, for use in other functions.

References

Documentation on the SODA website

See Also

soql_limit

Examples

if (require(magrittr)) {
  # With pipes
  my_url <- soql() %>%
    soql_offset(50) %>%
    as.character()
} else {
  # Without pipes
  soql_chain <- soql()
  soql_chain <- soql_offset(soql_chain, 50)
  my_url <- as.character(soql_chain)
}

SoQL Queries

Description

Wrapper functions around the SODA API's queries: select, where, order, group, and q.

Usage

soql_select(soql_list, select_clause)
soql_where(soql_list, where_clause)
soql_order(soql_list, column, desc = FALSE)
soql_group(soql_list, group_clause)
soql_q(soql_list, q_clause)

Arguments

Value

Returns a new soql object, with parameters added, for use in other functions.

References

Documentation about these queries on the SODA website

See Also

soql_simple_filter for an easier method of doing where with equality.

Examples

if (require(magrittr)) {
  # With pipes
  my_url <- soql() %>%
    soql_select("height,weight") %>%
    soql_where("height > 30") %>%
    soql_order("height", desc=TRUE) %>%
    soql_group("type") %>%
    soql_q("a") %>%
    as.character()
} else {
  # Without pipes
  soql_chain <- soql()
  soql_chain <- soql_select(soql_chain, "height,weight")
  soql_chain <- soql_where(soql_chain, "height > 30")
  soql_chain <- soql_order(soql_chain, "height", desc=TRUE)
  soql_chain <- soql_group(soql_chain, "type")
  soql_chain <- soql_q(soql_chain, "a")
  my_url <- as.character(soql_chain)
}

Create a simple equality filter

Description

This function adds a parameter to the URL to filter records in a simple way, using equality only. For more advanced filters, see soql_where.

Usage

soql_simple_filter(soql_list, column, value)

Arguments

Value

Returns a new soql object, with a filter parameter added, for use in other functions.

References

Documentation on the SODA website

See Also

soql_where

Examples

if (require(magrittr)) {
  # With pipes
  my_url <- soql() %>%
    soql_simple_filter("height", 50) %>%
    as.character()
} else {
  # Without pipes
  soql_chain <- soql()
  soql_chain <- soql_simple_filter(soql_chain, "height", 50)
  my_url <- as.character(soql_chain)
}