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,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# nutscoder

<!-- badges: start -->
[![DOI](https://zenodo.org/badge/476698751.svg)](https://zenodo.org/badge/latestdoi/476698751)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![R-CMD-check](https://github.com/RegioHub/nutscoder/workflows/R-CMD-check/badge.svg)](https://github.com/RegioHub/nutscoder/actions)
<!-- badges: end -->

{nutscoder} provides the function `nuts_geocode`, which attempts to find [NUTS region codes](https://ec.europa.eu/eurostat/web/nuts/background) for location names by using [Nominatim](https://nominatim.org) to search [OpenStreetMap (OSM)](https://www.openstreetmap.org) data.

## Installation

You can install the development version of {nutscoder} like so:

``` r
remotes::install_github("RegioHub/nutscoder")
```

## Usage

```{r}
library(nutscoder)
nuts_geocode(c("Hamburgo", "هامبورغ", "HH", "Berlin", "🐻Bärlin", "ベルリン",
               "North Rhine-Westphalia", "nrw"))
```

The [sf](https://r-spatial.github.io/sf/) geometry of the geocoded NUTS regions can be returned:

```{r}
nuts_geocode(c("berlin", "brandenburg"), return_geometry = TRUE) |> 
  sf::st_geometry() |> 
  plot()
```

The argument `nominatim_api` can be used to specify the API URL of the Nominatim instance used to search for OSM data. By default, `nuts_geocode()` uses the public Nominatim instance (`nominatim_api = "https://nominatim.openstreetmap.org"`), which has an absolute maximum of 1 request per second and is not suitable for intensive use. You can [install your own instance of Nominatim](https://nominatim.org/release-docs/latest/admin/Installation/) to avoid the limitations of the public instance.

## Citation

```{r echo=FALSE, results='asis'}
print(citation("nutscoder"), bibtex = FALSE)
```

A BibTeX entry for LaTeX users is

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

## Disclaimers

The use of the server running at <https://nominatim.openstreetmap.org> is governed by the [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/). 

Geodata from OpenStreetMap are licensed under the terms of the [Open Database License (ODbL) 1.0](http://www.opendatacommons.org/licenses/odbl/).

Use of any OSMF provided service is further governed by the [OSMF Terms of Use](https://wiki.osmfoundation.org/wiki/Terms_of_Use).