Getting Started with chiOpenData

The chi_pull_dataset() function

The primary way to pull data in this package is the chi_pull_dataset() function, which works in tandem with chi_list_datasets(). You do not need to know anything about API keys or authentication.

The first step would be to call the chi_list_datasets() to see what datasets are in the list and available to use in the chi_pull_dataset() function. This provides information for thousands of datasets found on the portal.

chi_list_datasets() |> head()

The output includes columns such as the dataset title, description, and link to the source. The most important fields are the dataset key and id. You need either in order to use the chi_pull_dataset() function. You can put either the key value or id value into the dataset = filter inside of chi_pull_dataset().

For instance, if we want to pull the dataset Crimes - 2001 to Present, we can use either of the methods below:

chi_motor_vehicle_collisions_data <- chi_pull_dataset(
  dataset = "ijzp-q8t2", limit = 2, timeout_sec = 90)

chi_motor_vehicle_collisions_data <- chi_pull_dataset(
  dataset = "crimes_2001_to_present", limit = 2, timeout_sec = 90)

No matter if we put the id or the key as the value for dataset =, we successfully get the data!

The chi_any_dataset() function

The easiest workflow is to use chi_list_datasets() together with chi_pull_dataset().

In the event that you have a particular dataset you want to use in R that is not in the list, you can use the chi_any_dataset(). The only requirement is the dataset’s API endpoint (a URL provided by the Chicago Open Data portal). Here are the steps to get it:

1. On the Chicago Open Data Portal, go to the dataset you want to work with.
2. Click on “Export” (next to the actions button on the right hand side).
3. Click on “API Endpoint”.
4. Click on “SODA2” for “Version”.
5. Copy the API Endpoint.

Below is an example of how to use the chi_any_dataset() once the API endpoint has been discovered, that will pull the same data as the chi_pull_dataset() example:

chi_motor_vehicle_collisions_data <- chi_any_dataset(json_link = "  
https://data.cityofchicago.org/resource/ijzp-q8t2.json", limit = 2)

Rule of Thumb

While both functions provide access to Chicago Open Data, they serve slightly different purposes.

In general:

• Use chi_pull_dataset() when the dataset is available in chi_list_datasets()
• Use chi_any_dataset() when working with datasets outside the catalog

Together, these functions allow users to either quickly access the datasets or flexibly query any dataset available on the Chicago Open Data portal.

Mini analysis

Now that we have successfully pulled the data and have it in R, let’s do a mini analysis on using the primary_type column, to figure out what are the main types of crimes.

To do this, we will create a bar graph of the crime types.

# Visualizing the distribution, ordered by frequency
chicago_crimes |>
  count(primary_type) |>
  ggplot(aes(
    x = n,
    y = reorder(primary_type, n)
  )) +
  geom_col(fill = "steelblue") +
  theme_minimal() +
  labs(
    title = "Top 50 Crime Types on the Street That Are Not Domestic",
    x = "Number of Crimes",
    y = "Primary Crime Type"
  )

This graph shows us not only which crimes were committed, but how many of each crime occurred. This suggests that theft is the most common crime type among recent non-domestic street incidents.