README.qmd

---
format: gfm
---

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

```{r setup}
#| include: false

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

desc_title <- readLines(here::here("DESCRIPTION")) |>
  stringr::str_subset("^Title") |>
  stringr::str_extract("(?<=: ).*")

desc_text <- readLines(here::here("DESCRIPTION")) |>
  stringr::str_subset("^Description") |>
  stringr::str_extract("(?<=: ).*")

```

# mapirosa


<!-- badges: start -->
<!-- badges: end -->

## `r desc_title`

`r desc_text`


<!-- http://www.rocketandco.co.uk/Site/Butterfly_Map_Art_files/final1.jpg -->

![two butterfly shapes cut out from paper maps](buttermap.jpg)

## Installation

```r
remotes::install_github("francisbarton/mapirosa")
```

To use the package you will need to have an API key from the Ordnance Survey
website.
Save this as an environment variable called `OS_DATA_KEY`

The easiest way to do this is to add a line to your `.Renviron` file like:

`OS_DATA_KEY = abcd1234`


## Create basemaps using raster data (PNGs)

### Examples:

```{r examples-1}
#| cache: true

library(mapirosa)

if (requireNamespace("osmdata")) {
  oxford1 <- create_bbox("Oxford", 27700)
} else {
  oxford1 <- c(
    xmin = 448100.3,
    ymin = 201646.6,
    xmax = 457014.2,
    ymax = 211088.8
  )
}

oxford_basemap1 <- build_basemap(
  bbox = oxford1,
  zoom = 5,
  style = "road",
  squarify = FALSE,
  crs = 27700
)
```


```{r examples-1-out}
oxford_basemap1
```


```{r examples-1-tmap-out}
if (requireNamespace("tmap")) {
  suppressMessages(tmap::tmap_mode("plot"))
  tmap::tm_shape(oxford_basemap1, raster.downsample = FALSE) +
    tmap::tm_rgb(max.value = 1)
}
```



```{r examples-2}
#| cache: true

if (requireNamespace("osmdata", quietly = TRUE)) {
  oxford2 <- create_bbox("Oxford", 3857)
} else {
  oxford2 <- c(
    xmin = -145188.1,
    ymin = 6748034.5,
    xmax = -130890.9,
    ymax = 6763371.2)
}

oxford_basemap2 <- build_basemap(
  bbox = oxford2,
  zoom = 12,
  style = "outdoor",
  squarify = TRUE,
  crs = 3857
)
```


```{r examples-2-out}
oxford_basemap2
```


```{r examples-2-ggplot}
# tidyterra: https://dieghernan.github.io/tidyterra/reference/geom_spatraster_rgb.html)

if (requireNamespace("ggplot2") & requireNamespace("tidyterra")) {
  ggplot2::ggplot() +
    tidyterra::geom_spatraster_rgb(
      data = oxford_basemap2,
      maxcell = 1e7,
      max_col_value = 1) +
    ggplot2::coord_sf() +
    ggplot2::theme_void()
}
```


### Names API

The spec for the Names API can be found on the OS website [here][names-api].

Currently we just use the `find` endpoint.
The `nearest` endpoint may be added later.

Without a `bounds` argument, the function will search nationally.
You can specify how many results you want to receive (up to a maximum of 100).

```{r examples-names-1}

query_names_api("Summertown", local_types = "Suburban Area", max_results = 2) |>
  tibble::glimpse()

```

To restrict results to a certain area, use the `bounds` argument with a "bbox"
(the `create_bbox()` function can help you).

Use OS National Grid (CRS 27700) numbers for your bbox.


```{r examples-names-2}

query_names_api("Summertown", "Suburban Area", bounds = oxford1) |>
  tibble::glimpse()

```


### Features API

The spec for the Features API can be found on the OS website [here][feats-api].

`query_features_api()` is designed to work with this API.
Unfortunately it is not yet functional.

Documentation to follow.



[names-api]: https://osdatahub.os.uk/docs/names/technicalSpecification
[feats-api]: https://osdatahub.os.uk/docs/wfs/technicalSpecification