README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# legistarapi

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- badges: end -->

The goal of legistarapi is to allow access to the [Legistar Web API](https://webapi.legistar.com/).

[Legistar](https://granicus.com/solution/govmeetings/legistar/) is "agenda and legislative management software for large municipalities and counties" supplied by Granicus. According to [promotional material](https://granicus.com/pdfs/product_legistar.pdf), Legistar is used by 70% of the largest cities and counties in the U.S.

## Installation

You can install the development version of legistarapi like so:

``` r
# pak::pkg_install("elipousson/legistarapi")
```

## Example

```{r setup}
library(legistarapi)
```

This easiest way to access Legistar data is using the dedicated functions that correspond to different types of information. For example, list Legistar users for a client using the `legis_get_persons()` function:

```{r bodies}
legis_get_persons(client = "seattle", top = 5)
```

The Legistar Web API has at least partial support for the [OData Version 3.0](https://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol/) URL conventions. Support for these conventions is incomplete but the `top`, `orderby`,  `select`, and `filter` query parameters are supported: 

```{r}
legis_get_persons(client = "seattle", top = 5, orderby = "PersonFullName", order = "asc", select = c("PersonFirstName", "PersonLastName", "PersonFullName"))
```

The functions starting with `legis_get_` are wrappers for the lower-level `legistar()` function. Using the `template` parameter, you can access the same data:

```{r persons}
legistar(template = "persons", client = "seattle", top = 5)
```

The full list of templates with a brief description of each API method is included in the `legistar_methods` reference data frame:

```{r}
str(legistar_methods)
```

Using the API to access data for your jurisdiction may require trial and error to figure out how the specific site organized information.

For example, in order to figure out how to list ordinances for Baltimore City, it is helpful to start by listing the "Matter Types":

```{r}
matter_types <- legistar(
  client = "baltimore",
  template = "matter_types"
)

str(matter_types)
```

For Baltimore City, the "Ordinance" Matter Type has a ID value of 1. We can use the filter parameter to return a data frame of ordinances:

```{r}
ordinances <- legistar(
  client = "baltimore",
  template = "matters",
  top = 5,
  filter = c(
    "year(MatterPassedDate) > 2022",
    "MatterTypeId == 1"
  ),
  orderby = "MatterPassedDate",
  direction = "desc"
)

str(ordinances)
```

Note that if `{stringr}` is installed the package will automatically convert R logical operators contained in the filter string into OData logical operators, e.g. ">" converted to "gt" and "==" converted to "eq". Only logical operators bracketed by spaces are converted. 

## Related projects

- [Python Legistar Scraper](https://github.com/opencivicdata/python-legistar-scraper)
- [scrapers-us-municipal](https://github.com/opencivicdata/scrapers-us-municipal): Scrapers for US municipal governments
- [Council Data Project](https://councildataproject.org/)
- [cdp-scrapers](https://councildataproject.org/cdp-scrapers/index.html): Scratchpad for scraper development and general utilities for the Council Data Project
- [legistar-rs](https://github.com/Subzidion/legistar-rs): Rust library to access the Legistar Web API.
- [civic-scraper](https://github.com/biglocalnews/civic-scraper): Tools for downloading agendas, minutes and other documents produced by local government