---
title: "Your first walkability map"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Your first walkability map}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = nzchar(Sys.getenv("CLOSECITY_KEY"))
)
library(closecity)
close <- closecity::close_client(api_key = Sys.getenv("CLOSECITY_KEY"))
```

The quickest way to feel what Close gives you: read the walk times from a starting
point, map the supermarkets you can reach on foot, then draw how far a 30-minute
walk takes you. The example city is Providence, Rhode Island.

*Running this tutorial uses about 90 tokens.*

## Set up

Build a client, then read what you need from the free catalog.

```r
library(closecity)
close <- closecity::close_client(api_key = "ck_live_your_key")   # use your own key here
```

```{r}
amenity_types <- close$destination_types()
supermarket_type <- amenity_types[amenity_types$label == "grocery_stores", ]$dest_type_id

providence_ri <- close$places(q = "Providence")[1, ]
start_lon <- providence_ri$lon
start_lat <- providence_ri$lat
```

## Read travel times from a starting point

Pick a starting point (here the centre of Providence) and ask how long it takes
to walk to each kind of amenity. `$point_summary()` takes a `lat`/`lon` instead of a
block GEOID. Join the catalog's readable `name` and sort by time, so the nearest
things are on top.

```{r}
walk_times <- close$point_summary(lat = start_lat, lon = start_lon, mode = "walk")
walk_times <- merge(
  walk_times,
  amenity_types[, c("dest_type_id", "name")],
  by = "dest_type_id"
)
walk_times[order(walk_times$travel_time), c("name", "travel_time")]
```

## Map the supermarkets within a 30-minute walk

A 30-minute walk is a travel-time question, not a distance one, so let the routing
answer it directly: `$point_pois()` returns every POI reachable from the starting
point within `max_minutes`, each carrying its walk time, with no isochrone to overlay.
`close_map()` draws them in one line, shaded by that walk time (blue = closest),
with the starting point marked by an X and the city boundary behind for context.

```{r}
nearby_supermarkets <- close$point_pois(
  lat = start_lat,
  lon = start_lon,
  mode = "walk",
  type = supermarket_type,
  max_minutes = 30
)

city_boundary <- close$place_boundary(geoid = providence_ri$geoid)
closecity::close_map(
  x = nearby_supermarkets,
  fill = "travel_time",
  boundary = city_boundary,
  label = "name",
  mark = c(start_lon, start_lat)
)
```

## Draw how far you can walk

An isochrone is the headline map: the area you can reach on foot in 10, 20, and 30
minutes. Shade it by the `contour` minutes; blue marks the nearest, most-reachable
ring.

```{r}
rings <- close$isochrone(
  lon = start_lon,
  lat = start_lat,
  mode = "walk",
  direction = "from",
  contours = c(10, 20, 30),
  format = "geojson"
)
closecity::close_map(x = rings, fill = "contour")
```

## Walk versus transit

Comparing the same starting point and the same 30-minute budget, on foot and by
bus, is the clearest way to see what transit buys you.

```{r}
walk <- close$isochrone(
  lon = start_lon,
  lat = start_lat,
  mode = "walk",
  direction = "from",
  minutes = 30,
  format = "geojson"
)
transit <- close$isochrone(
  lon = start_lon,
  lat = start_lat,
  mode = "transit",
  direction = "from",
  minutes = 30,
  format = "geojson"
)

closecity::close_map(x = walk, color = "#058040")
closecity::close_map(x = transit, color = "#202a5b")
```
```