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,
  message = FALSE,
  warning = FALSE,
  dev = "ragg_png",
  tidy = "styler",
  dpi = 300,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

if (.Platform$OS.type != "windows") {
  options(download.file.method = "curl", download.file.extra = "-k -L")
}


library(CatastRo)
```

# CatastRo <a href="https://ropenspain.github.io/CatastRo/"><img src="man/figures/logo.png" align="right" height="139"/></a>

<!-- badges: start -->

[![rOS-badge](https://ropenspain.github.io/rostemplate/reference/figures/ropenspain-badge.svg)](https://ropenspain.es/)
[![CRAN-status](https://www.r-pkg.org/badges/version/CatastRo)](https://CRAN.R-project.org/package=CatastRo)
[![CRAN-results](https://badges.cranchecks.info/worst/CatastRo.svg)](https://cran.r-project.org/web/checks/check_results_CatastRo.html)
[![Downloads](https://cranlogs.r-pkg.org/badges/CatastRo)](https://CRAN.R-project.org/package=CatastRo)
[![r-universe](https://ropenspain.r-universe.dev/badges/CatastRo)](https://ropenspain.r-universe.dev/CatastRo)
[![R-CMD-check](https://github.com/rOpenSpain/CatastRo/actions/workflows/roscron-check-standard.yaml/badge.svg)](https://github.com/rOpenSpain/CatastRo/actions/workflows/roscron-check-standard.yaml)
[![R-hub](https://github.com/rOpenSpain/CatastRo/actions/workflows/rhub.yaml/badge.svg)](https://github.com/rOpenSpain/CatastRo/actions/workflows/rhub.yaml)
[![codecov](https://codecov.io/gh/rOpenSpain/CatastRo/graph/badge.svg?token=KPPwTkZjW6)](https://app.codecov.io/gh/rOpenSpain/CatastRo)
[![DOI](https://img.shields.io/badge/DOI-10.32614/CRAN.package.CatastRo-blue)](https://doi.org/10.32614/CRAN.package.CatastRo)
[![Project Status: Active -- The project has reached a stable, usable state and
is being actively
developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

<!-- badges: end -->

**CatastRo** is a package that provide access to different API services of the
[Spanish Cadastre](https://www.sedecatastro.gob.es/). With **CatastRo** it is
possible to download spatial objects (as buildings or cadastral parcels), maps
and geocode cadastral references.

## Installation

Install **CatastRo** from
[**CRAN**](https://CRAN.R-project.org/package=CatastRo):

```{r, eval = FALSE}
install.packages("CatastRo")
```

You can install the developing version of **CatastRo** using the
[r-universe](https://ropenspain.r-universe.dev/CatastRo):

```{r, eval = FALSE}
# Install CatastRo in R:
install.packages("CatastRo",
  repos = c(
    "https://ropenspain.r-universe.dev",
    "https://cloud.r-project.org"
  )
)
```

Alternatively, you can install the developing version of **CatastRo** with:

```{r, eval = FALSE}
remotes::install_github("rOpenSpain/CatastRo", dependencies = TRUE)
```

## Package API

The functions of **CatastRo** are organized by API endpoint. The package naming
convention is `catr_*api*_*description*`.

### OVCCoordenadas

These functions allow to geocode and reverse geocode cadastral references using
the
[OVCCoordenadas](https://ovc.catastro.meh.es/ovcservweb/OVCSWLocalizacionRC/OVCCoordenadas.asmx)
service.

These functions are named `catr_ovc_get_*` and returns a tibble, as provided by
the package **tibble**. See `vignette("ovcservice", package = "CatastRo")` where
these functions are described.

### INSPIRE

These functions return spatial object (on the formats provided by the **sf** or
**terra** using the [Catastro
INSPIRE](https://www.catastro.minhap.es/webinspire/index.html) service.

Note that the coverage of this service is 95% of the Spanish territory,
[excluding Basque Country and Navarre]{.underline}[^1] that have their own
independent cadastral offices.

[^1]: The package [**CatastRoNav**](https://ropenspain.github.io/CatastRoNav/)
    provides access to the Cadastre of Navarre, with similar functionalities
    than **CatastRo**.

There are three types of functions, each one querying a different service:

#### ATOM service

The ATOM service allows to batch-download vector objects of different cadastral
elements for a specific municipality. The result is provided as `sf` objects
(See **sf** package).

These functions are named `catr_atom_get_xxx`.

#### WFS service

The WFS service allows to download vector objects of specific cadastral
elements. The result is provided as `sf` class objects (see
[**sf**](https://r-spatial.github.io/sf/) package). Note that there are some
limitations on the extension and number of elements to query. For
batch-downloading the ATOM service is preferred.

These functions are named `catr_wms_get_xxx`.

#### WMS service

This service allows to download georeferenced images of different cadastral
elements. The result is a raster on the format provides by
[**terra**](https://rspatial.github.io/terra/reference/terra-package.html).

There is a single function for querying this service: `catr_wms_get_layer()`.

#### Terms and conditions of use

Please check the [downloading
provisions](https://www.catastro.minhap.es/webinspire/documentos/Licencia.pdf)
of the service.

## Examples

This script highlights some features of **CatastRo** :

### Geocode a cadastral reference

```{r}
library(CatastRo)

catr_ovc_get_cpmrc(rc = "13077A01800039")
```

### Extract a cadastral reference from a given set of coordinates

```{r}
catr_ovc_get_rccoor(
  lat = 38.6196566583596,
  lon = -3.45624183836806,
  srs = "4230"
)
```

### Extract geometries using the ATOM service

```{r atom}
bu <- catr_atom_get_buildings("Nava de la Asuncion", to = "Segovia")


# Map
library(ggplot2)

ggplot(bu) +
  geom_sf(aes(fill = currentUse), col = NA) +
  coord_sf(
    xlim = c(374500, 375500),
    ylim = c(4556500, 4557500)
  ) +
  scale_fill_manual(values = hcl.colors(6, "Dark 3")) +
  theme_minimal() +
  ggtitle("Nava de la Asunción, Segovia")
```

### Extract geometries using the WFS service

```{r wfs}
wfs_get_buildings <- catr_wfs_get_buildings_bbox(
  c(-5.569, 42.598, -5.564, 42.601),
  srs = 4326
)

# Map
ggplot(wfs_get_buildings) +
  geom_sf() +
  ggtitle("Leon Cathedral, Spain")
```

### Extract maps using the WMS service

```{r wms}
# For tiles better project

wfs_get_buildings_pr <- sf::st_transform(wfs_get_buildings, 25830)

wms_bu <- catr_wms_get_layer(wfs_get_buildings_pr,
  srs = 25830,
  bbox_expand = 0.2
)

# Map
# Load tidyterra
library(tidyterra)
ggplot() +
  geom_spatraster_rgb(data = wms_bu) +
  geom_sf(data = wfs_get_buildings_pr, fill = "red", alpha = 0.6)
```

## A note on caching

Some data sets and tiles may have a size larger than 50MB. You can use
**CatastRo** to create your own local repository at a given local directory
passing the following option:

```{r, eval = FALSE}
catr_set_cache_dir("./path/to/location")
```

When this option is set, **CatastRo** would look for the cached file and it will
load it, speeding up the process.

## Citation

```{r echo=FALSE, results='asis'}
print(citation("CatastRo"), style = "html")
```

A BibTeX entry for LaTeX users is:

```{r echo=FALSE, comment=''}
toBibtex(citation("CatastRo"))
```

## Contribute

Check the GitHub page for [source
code](https://github.com/ropenspain/CatastRo/).