---
title: "Get started"
description: Brief introduction to the CatastRo package.
vignette: >
  %\VignetteIndexEntry{Get started}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
bibliography: REFERENCES.bib
link-citations: true
---

<!-- CatastRo.qmd is generated from CatastRo.qmd.orig. Please edit that file -->



**CatastRo** provides access to services from the [Spanish
Cadastre](https://www.sedecatastro.gob.es/). With **CatastRo**, you can
download official address, cadastral parcel, building and map data.

## OVCCoordenadas service

The
[OVCCoordenadas](https://ovc.catastro.meh.es/ovcservweb/OVCSWLocalizacionRC/OVCCoordenadas.asmx)
service retrieves the coordinates of a known cadastral reference
(geocoding). It is also possible to retrieve the cadastral references around a
specific pair of coordinates (reverse geocoding). **CatastRo** returns the
results as a tibble. This functionality is described in detail in the
corresponding vignette (see `vignette("ovcservice", package = "CatastRo")`).

## INSPIRE services

<figure>

<blockquote class="blockquote">

The INSPIRE Directive aims to create a European Union Spatial Data
Infrastructure (SDI) for the purposes of EU environmental policies and policies
or activities which may have an impact on the environment. This European Spatial
Data Infrastructure enables the sharing of environmental spatial information
among public sector organizations, facilitates public access to spatial
information across Europe and assist in policy-making across boundaries.

</blockquote>

```{=html}
<figcaption class="blockquote-footer">Source: <cite title="INSPIRE Knowledge
Base"><a href="https://knowledge-base.inspire.ec.europa.eu/overview_en"
class="external-link uri">INSPIRE Knowledge Base</a>
</cite>
</figcaption>
```

</figure>

The implementation of the INSPIRE directive in the Spanish Cadastre (see
[Spanish Cadastre INSPIRE](https://www.catastro.hacienda.gob.es/webinspire/index.html))
allows retrieval of spatial objects from the cadastral database:

- **Vector objects:** Parcels, addresses, buildings, cadastral zones and more.
  **CatastRo** returns these objects as `sf` objects, using the **sf** package.
- **Imagery:** Image layers representing the same information as the vector
  objects. **CatastRo** returns these objects as `SpatRaster` objects, using
  the **terra** package.

Note that these services cover 95% of the Spanish territory,
excluding the Basque Country and Navarre[^1], which have their own independent
cadastral offices.

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

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

1.  **ATOM service**: The ATOM service downloads complete municipal datasets
    for different cadastral elements.

2.  **WFS service**: The WFS service downloads vector objects for specific
    cadastral elements. Note that there are restrictions on the extent and
    number of elements that can be queried. For full municipal downloads,
    prefer the ATOM service.

3.  **WMS service**: The WMS service downloads georeferenced map images for
    different cadastral elements.

## Examples

### Working with layers

This example demonstrates some of the main capabilities of the package by
recreating a cadastral map of the surroundings of the [Santiago Bernabéu
Stadium](https://en.wikipedia.org/wiki/Santiago_Bernab%C3%A9u_Stadium). We use
the WMS and WFS services to retrieve different layers.


``` r
# Extract buildings by bounding box.
# Check https://boundingbox.klokantech.com/

library(CatastRo)

stadium <- catr_wfs_get_buildings_bbox(
  c(-3.6891446916, 40.4523311971, -3.687462138, 40.4538643165),
  srs = 4326
)

# Extract cadastral parcels using spatial objects in the query.

stadium_parcel <- catr_wfs_get_parcels_bbox(stadium)

# Project for tiles.

stadium_parcel_pr <- sf::st_transform(stadium_parcel, 25830)

# Extract parcel label imagery.

labs <- catr_wms_get_layer(
  stadium_parcel_pr,
  what = "parcel",
  styles = "BoundariesOnly",
  srs = 25830
)

# Plot.
library(ggplot2)
library(tidyterra) # For terra tiles.

ggplot() +
  geom_spatraster_rgb(data = labs) +
  geom_sf(
    data = stadium_parcel_pr,
    fill = NA, col = "red", linewidth = 2
  ) +
  geom_sf(data = stadium, fill = "red", alpha = .5) +
  coord_sf(crs = 25830)
```

<div class="figure">
<img src="./santbernabeu-1.png" alt="Figure 1: Santiago Bernabéu example" width="100%" />
<p class="caption">Figure 1: Santiago Bernabéu example</p>
</div>

### Thematic maps

We can also create thematic maps using the information available on the spatial
objects. We produce a visualization of the urban growth of Granada using
**CatastRo**, replicating the map produced by [Dominic
Royé](https://dominicroye.github.io) [@roye19], using the **ATOM service**.

First, we extract the coordinates of Granada's city center with
**mapSpain**:


``` r
library(dplyr)
library(sf)
library(mapSpain)

# Use mapSpain to get the coordinates.

city <- esp_get_capimun(munic = "^Granada$")
```

The next step is to extract the buildings using the ATOM service. We also use
`catr_get_code_from_coords()` to identify Granada's code in the Cadastre and
download the buildings with `catr_atom_get_buildings()`.


``` r
city_catr_code <- catr_get_code_from_coords(city)

city_catr_code
#> # A tibble: 1 × 12
#>   munic   catr_to catr_munic catrcode cpro  cmun  inecode nm     cd    cmc   cp   
#>   <chr>   <chr>   <chr>      <chr>    <chr> <chr> <chr>   <chr>  <chr> <chr> <chr>
#> 1 GRANADA 18      900        18900    18    087   18087   GRANA… 18    900   18   
#> # ℹ 1 more variable: cm <chr>

city_bu <- catr_atom_get_buildings(city_catr_code$catrcode)
```

Next, we limit the analysis to a circle with a radius of 1.5 km around the city
center:


``` r
buff <- city |>
  # Adjust CRS to 25830 for buildings.
  st_transform(st_crs(city_bu)) |>
  # Buffer.
  st_buffer(1500)

# Cut buildings.
dataviz <- st_intersection(city_bu, buff)

ggplot(dataviz) +
  geom_sf()
```

<div class="figure">
<img src="./minimal-1.png" alt="Figure 2: Minimal cadastral map of Granada" width="100%" />
<p class="caption">Figure 2: Minimal cadastral map of Granada</p>
</div>

Now let's extract the construction year, available in the column `beginning`:


``` r
# Extract the first four positions.
year <- substr(dataviz$beginning, 1, 4)

# Replace entries that do not look like numbers with 0000.
year[!(year %in% 0:2500)] <- "0000"

# Convert to numeric.
year <- as.integer(year)

# Add a new column.
dataviz <- dataviz |>
  mutate(year = year)
```

The last step is to group the data by construction year and create the
visualization. Here, `cut()` creates classes for each decade from 1900 onward:


``` r
dataviz <- dataviz |>
  mutate(
    year_cat = cut(year, breaks = c(0, seq(1900, 2030, by = 10)), dig.lab = 4)
  )

ggplot(dataviz) +
  geom_sf(aes(fill = year_cat), color = NA, na.rm = TRUE) +
  scale_fill_manual(
    values = hcl.colors(15, "Spectral"),
    na.translate = FALSE
  ) +
  theme_void() +
  labs(title = "GRANADA", fill = "") +
  theme(
    panel.background = element_rect(fill = "black"),
    plot.background = element_rect(fill = "black"),
    legend.justification = .5,
    legend.text = element_text(
      colour = "white",
      size = 12
    ),
    plot.title = element_text(
      colour = "white",
      hjust = .5,
      margin = margin(t = 30),
      size = 30
    ),
    plot.caption = element_text(
      colour = "white",
      margin = margin(b = 20),
      hjust = .5
    ),
    plot.margin = margin(r = 40, l = 40)
  )
```

<div class="figure">
<img src="./dviz-1.png" alt="Figure 2: Granada - Urban growth" width="100%" />
<p class="caption">Figure 2: Granada - Urban growth</p>
</div>

## References