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,
  dpi = 1000,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%")
```

# municoder

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![R-CMD-check](https://github.com/wcurrangroome/municoder/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/wcurrangroome/municoder/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

## Overview

**municoder** provides an R interface to the [municode.com](https://municode.com) API, giving programmatic access to municipal ordinances from 1,000+ jurisdictions across all 50 U.S. states and territories. The package enables researchers, urban planners, and policy analysts to access zoning codes, building ordinances, and other regulatory documents for spatial analysis, policy research, and comparative studies.

## Installation

You can install the development version of `library(municoder)` like so:

``` r
renv::install("wcurrangroome/municoder")
```

```{r}
#| include: false

library(municoder)
library(tidyverse)
library(urbnthemes)
library(janitor)
library(tigris)
library(urbnthemes)

set_urbn_defaults()
options(scipen = 999999)
```

## Quick Start

Get started with municoder in just a few lines:

```{r quickstart, eval = FALSE}
library(municoder)

# Get all jurisdictions in Virginia
va_clients <- get_clients_in_state("VA")

# Get all available ordinances for Alexandria, VA (the easy way!)
products <- get_jurisdiction_products(
  state_abbreviation = "VA", 
  client_name = "Alexandria")

# Get the table of contents for Alexandria's zoning ordinance
toc <- get_ordinance_toc(
  state_abbreviation = "VA", 
  client_name = "Alexandria", 
  product_name = "Zoning")

# Extract a specific section of the ordinance
content <- get_ordinance_section(
  state_abbreviation = "VA", 
  client_name = "Alexandria", 
  product_name = "Zoning", 
  node_id = "ARTIIIREZORE")
```

The new workflow helper functions (`get_jurisdiction_products()`, `get_ordinance_toc()`, `get_ordinance_section()`) automatically handle the multi-step process of looking up IDs and navigating the API, making common tasks much simpler.

## Common Workflows

### Discovery: Find jurisdictions and their ordinances

```{r discovery, eval = FALSE}
# Get all states
states <- get_states()

# Get all municipalities in a state
va_clients <- get_clients_in_state("VA")

# Get metadata for a specific municipality
alexandria <- get_client_metadata("VA", "Alexandria")

# Get all ordinance types available for a jurisdiction
products <- get_jurisdiction_products("VA", "Alexandria")
```

### Navigation: Explore ordinance structure

```{r navigation, eval = FALSE}
# Get table of contents (the easy way)
toc <- get_ordinance_toc("VA", "Alexandria", "Zoning")

# Or do it step-by-step for more control
client_id <- get_client_metadata("VA", "Alexandria")$client_id
product_id <- get_client_products(client_id) %>%
  filter(product_name == "Zoning") %>%
  pull(product_id)
job_id <- get_current_version(product_id)$id
toc <- get_codes_toc(job_id, product_id)
```

### Extraction: Get ordinance text

```{r extraction, eval = FALSE}
# Extract a specific section (the easy way)
section <- get_ordinance_section("VA", "Alexandria", "Zoning", "ARTIIIREZORE")

# Get all child sections and their content
children_ids <- section %>% pull(id)
all_content <- map_dfr(
  children_ids,
  ~ get_section_text(
    product_id = product_id, 
    node_id = .x))
```

## Case Studies

### Spatial Coverage Analysis

Map the geographic distribution of jurisdictions with ordinances on municode.com:

```{r map-of-municode-coverage-by-state}
all_states <- municoder::get_states()

all_clients <- all_states %>%
  dplyr::pull(state_abbreviation) %>%
  purrr::discard(~ str_detect(.x, "Tribes")) %>% ## "Tribes" throws an error for some reason
  purrr::map_dfr(~ get_clients_in_state(.x))

states_sf <- tigris::states(cb = TRUE, progress_bar = FALSE) %>%
  dplyr::filter(GEOID < 60) %>%
  tigris::shift_geometry() %>%
  dplyr::left_join(
    all_clients %>% dplyr::count(state_abbreviation),
    by = c("STUSPS" = "state_abbreviation"))

states_sf %>%
  ggplot2::ggplot() +
  ggplot2::geom_sf(ggplot2::aes(fill = n)) +
  ggplot2::geom_sf(data = states_sf %>% dplyr::filter(n == 0), fill = "lightgrey") +
  ggplot2::labs(
    title = "Municode Clients Span All 51 States",
    fill = "Entities with ordinances on municode.com" %>% str_wrap(30)) +
  ggplot2::scale_fill_continuous(trans = "reverse") +
  urbnthemes::theme_urbn_map()
```

### Comparative Zoning Analysis

Compare zoning ordinance language across different zones. This example examines the "Purpose" statements for Alexandria, VA's residential zones to identify policy priorities:

```{r comparative-zoning}
# Get all residential zones using the workflow helper
content <- get_ordinance_section("VA", "Alexandria", "Zoning", "ARTIIIREZORE")

# Extract all child zone sections
zone_ids <- content %>% dplyr::pull(id)
all_zones <- purrr::map_dfr(zone_ids,
  ~ get_section_text(product_id = 12429, node_id = .x))

# Filter to Purpose statements
purpose_statements <- all_zones %>%
  dplyr::filter(
    !is.na(content),
    stringr::str_detect(heading, "Purpose")) %>%
  dplyr::select(heading, content)

# Do any zones mention affordability?
purpose_statements %>% 
  dplyr::pull(content) %>% 
  keep(~ str_detect(.x, "affordability|affordable"))
```