---
title: "Get started"
description: Brief introduction to 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 different API services of the [Spanish
Cadastre](https://www.sedecatastro.gob.es/). With **CatastRo**, you can download
official information on addresses, properties, parcels, and buildings.

## OVCCoordenadas service

The
[OVCCoordenadas](https://ovc.catastro.meh.es/ovcservweb/OVCSWLocalizacionRC/OVCCoordenadas.asmx)
service allows retrieving 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 in a tibble format. 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 will enable the sharing of environmental spatial information
among public sector organisations, facilitate 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 on the Spanish Cadastre (see
[Catastro 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.
  These objects are provided by **CatastRo** as `sf` objects, using the **sf**
  package.
- **Imagery:** Image layers representing the same information as the vector
  objects. These objects are provided by **CatastRo** as `SpatRaster` objects,
  using the **terra** package.

Note that the coverage of this service is 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 functionalities to
    **CatastRo**.

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

1.  **ATOM service**: The ATOM service allows batch downloading vector objects
    of different cadastral elements for a specific municipality.

2.  **WFS service**: The WFS service allows downloading vector objects of
    specific cadastral elements. Note that there are restrictions on the extent
    and number of elements that can be queried. For batch downloading, the ATOM
    service is preferred.

3.  **WMS service**: This service allows downloading georeferenced images of
    different cadastral elements.

## Examples

### Working with layers

In this example, we will demonstrate 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 will use the **WMS and WFS services** to get different layers, in order to
show some of the capabilities of the package:


``` 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
)

# Now extract cadastral parcels. We can use spatial objects on the query

stadium_parcel <- catr_wfs_get_parcels_bbox(stadium)

# Project for tiles

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

# Extract imagery: Labels of the parcel

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: Example - Santiago Bernabeu" width="100%" />
<p class="caption">Figure 1: Example - Santiago Bernabeu</p>
</div>

### Thematic maps

We can also create thematic maps using the information available on the spatial
objects. We will 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 the city center of Granada using
**mapSpain**:


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

# Use mapSpain for getting the coords

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

The next step is to extract the buildings using the ATOM service. We will also
use the function `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    cm   
#>   <chr>   <chr>   <chr>      <chr>    <chr> <chr> <chr>   <chr>   <chr> <chr> <chr> <chr>
#> 1 GRANADA 18      900        18900    18    087   18087   GRANADA 18    900   18    87

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

The next step in creating the visualization is to limit the analysis to a circle
with a radius of 1.5 km around the city center:


``` r
buff <- city |>
  # Adjust CRS to 25830: (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 4 initial positions
year <- substr(dataviz$beginning, 1, 4)

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


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

# New column
dataviz <- dataviz |>
  mutate(year = year)
```

The last step is to create groups based on the year and create the data
visualization. Here we use the function `cut()` to create classes for every
decade starting from year 1900:


``` 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