---
title: "Fetching OSM roads"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Fetching OSM roads}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Overview

`fetch_osm_roads()` provides a lightweight wrapper around **osmdata** that
returns a road-line `sf` object you can pass directly into the rest of the
`trafficCAR` workflow. It accepts either a place name (geocoded to a bounding
box) or explicit bounding-box coordinates. Note that `fetch_osm_roads()` requires the **osmdata** package.

## Fetch by place name

```{r eval=FALSE}
library(trafficCAR)

# Query a place name (uses osmdata::getbb() under the hood)
roads_sf <- fetch_osm_roads("College Station, TX")

segments <- roads_to_segments(roads_sf)
net <- build_network(segments)
```

## Fetch by bounding box

```{r eval=FALSE}
library(trafficCAR)

# xmin, ymin, xmax, ymax
bbox <- c(-96.38, 30.59, -96.33, 30.63)
roads_sf <- fetch_osm_roads(bbox)

segments <- roads_to_segments(roads_sf)
net <- build_network(segments)
```

## Filtering the OSM query

You can refine the query by passing highway values or additional tags.

```{r eval=FALSE}
roads_sf <- fetch_osm_roads(
  "College Station, TX",
  value = c("primary", "secondary"),
  extra_tags = list(surface = "asphalt")
)
```