diff --git a/CITATION.cff b/CITATION.cff index c1abcc5b..79bd240d 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -97,6 +97,21 @@ references: email: dcooley@symbolix.com.au year: '2024' version: '>= 2.0.0' +- type: software + title: jsonlite + abstract: 'jsonlite: A Simple and Robust JSON Parser and Generator for R' + notes: Imports + url: https://jeroen.r-universe.dev/jsonlite + repository: https://CRAN.R-project.org/package=jsonlite + authors: + - family-names: Ooms + given-names: Jeroen + email: jeroen@berkeley.edu + orcid: https://orcid.org/0000-0002-4035-0289 + year: '2024' + identifiers: + - type: url + value: https://arxiv.org/abs/1403.2805 - type: software title: rappdirs abstract: 'rappdirs: Application Directories: Determine Where to Save Data, Caches, diff --git a/DESCRIPTION b/DESCRIPTION index a52a5d64..cf158161 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -24,6 +24,7 @@ Depends: Imports: countrycode (>= 1.2.0), geojsonsf (>= 2.0.0), + jsonlite, rappdirs (>= 0.3.0), sf (>= 0.9.0), utils diff --git a/NAMESPACE b/NAMESPACE index 1988463a..ad457df2 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,15 @@ # Generated by roxygen2: do not edit by hand +export(gisco_addressapi_bbox) +export(gisco_addressapi_cities) +export(gisco_addressapi_copyright) +export(gisco_addressapi_countries) +export(gisco_addressapi_housenumbers) +export(gisco_addressapi_postcodes) +export(gisco_addressapi_provinces) +export(gisco_addressapi_reverse) +export(gisco_addressapi_roads) +export(gisco_addressapi_search) export(gisco_attributions) export(gisco_bulk_download) export(gisco_check_access) @@ -19,6 +29,7 @@ export(gisco_get_postalcodes) export(gisco_get_units) export(gisco_get_urban_audit) export(gisco_set_cache_dir) +importFrom(utils,URLencode) importFrom(utils,download.file) importFrom(utils,menu) importFrom(utils,read.csv2) diff --git a/NEWS.md b/NEWS.md index 4e8f04c0..b721685d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,10 @@ - New functions: - `gisco_get_education()`. + - Add access to [GISCO Address + API](https://gisco-services.ec.europa.eu/addressapi/docs/screen/home) + through new functions. See `?gisco_addressapi` to know more (#84). +- New dependency: **jsonlite** added to 'Imports'. - Update `gisco_db` with the most up-to-date released data. - Default year of some functions updated to the latest available data: - `gisco_get_lau()` and `gisco_get_urban_audit()` default year now is @@ -30,7 +34,7 @@ # giscoR 0.3.5 -- Review examples to avoid CRAN errors and notes. +- Review examples to avoid **CRAN** errors and notes. - New helper function: `gisco_detect_cache_dir()`. - Now the functions fail gracefully with an informative message, instead of an error, and return `NULL`. @@ -45,12 +49,12 @@ # giscoR 0.3.2 -- Fix HTML5 issue as requested by CRAN. +- Fix HTML5 issue as requested by **CRAN**. # giscoR 0.3.1 -- Add `Copyright` on DESCRIPTION. -- Add `lwgeom` on `Suggests`. +- Add `Copyright` on `DESCRIPTION`. +- Add **lwgeom** on 'Suggests'. - `gisco_get_airports()` and `gisco_get_ports()`: - Only year available is 2013. - Now information is downloaded instead of using internal data. @@ -67,22 +71,22 @@ `gisco_clear_cache()`. - Fix an error when `cache = FALSE`. Now files are loaded instead throwing an error. -- New tests with `testthat`. +- New tests with **testthat**. - Update on docs. New examples - Refactor documents and codes for the previous `gisco_get` doc. -- Add `eurostat` package to `Suggests`. -- `lwgeom` dependency removed. +- Add **eurostat** package to ' Suggests'. +- **lwgeom** dependency removed. - Update internal grid object. -- `tmap` package replaced by `ggplot2` on vignettes and examples. +- **tmap** package replaced by **ggplot2** on vignettes and examples. # giscoR 0.2.4 - New `eu` field on `giscoR::gisco_countrycode`. -- Fix typos on documentation -- Include vignette on the package -- Move docs to `roxygen2` -- `lwgeom` moved to Import field. -- `cartography` package replaced by `tmap` on vignettes. +- Fix typos on documentation. +- Include vignette on the package. +- Move docs to **roxygen2**. +- **lwgeom** moved to 'Imports' field. +- **cartography** package replaced by **tmap** on vignettes. # giscoR 0.2.3 @@ -95,14 +99,14 @@ # giscoR 0.2.1 -- Remove CRAN notes. +- Remove **CRAN** notes. - Improve docs. -- Fix CRAN checks. +- Fix **CRAN** checks. # giscoR 0.2.0 -- Remove `colorspace` as dependency. -- Bump R minimal version to 3.6.0. +- Remove **colorspace** as dependency. +- Bump **R** minimal version to `3.6.0`. - Change order on parameters for `gisco_get()` functions. - Rewriting of internal functions and utils. - Add `verbose` parameter to functions. @@ -120,7 +124,7 @@ # giscoR 0.1.1 - Added `giscoR::tgs00026` dataset. -- Remove `eurostat` dependency. +- Remove **eurostat** dependency. # giscoR 0.1.0 diff --git a/R/giscoR-package.R b/R/giscoR-package.R index 8761733b..af913c20 100644 --- a/R/giscoR-package.R +++ b/R/giscoR-package.R @@ -2,5 +2,5 @@ "_PACKAGE" # import stuffs -#' @importFrom utils download.file unzip read.csv2 menu +#' @importFrom utils download.file unzip read.csv2 menu URLencode NULL diff --git a/R/gisco_addressapi.R b/R/gisco_addressapi.R new file mode 100644 index 00000000..92b62e18 --- /dev/null +++ b/R/gisco_addressapi.R @@ -0,0 +1,343 @@ +#' GISCO Address API +#' +#' @description +#' Access the [GISCO Address +#' API](https://gisco-services.ec.europa.eu/addressapi/docs/screen/home), that +#' allows to carry out both geocoding and reverse geocoding using a pan-european +#' address database. +#' +#' Each endpoint available is implemented through a specific function, see +#' **Details**. +#' +#' The API supports fuzzy searching (also referred to as approximate string +#' matching) for all parameters of each endpoint. +#' +#' @name gisco_addressapi +#' @rdname gisco_addressapi +#' +#' @param country Country code (`country = "LU"`). +#' @param x,y x and y coordinates (as longitude and latitude) to be converted +#' into a human-readable address. +#' @param province A province within a country. For a list of provinces within a +#' certain country use the provinces endpoint +#' (`gisco_addressapi_provinces(country = "LU")`). +#' @param city A city within a province. For a list of cities within a certain +#' province use the cities endpoint +#' (`gisco_addressapi_cities(province = "capellen")`). +#' @param road A road within a city. +#' @param housenumber The house number or house name within a road or street. +#' @param postcode Can be used in combination with the previous parameters. +#' +#' @inheritParams gisco_get_nuts +#' +#' @returns +#' +#' A `data.frame` object in most cases, except `gisco_addressapi_search()`, +#' `gisco_addressapi_reverse()` and `gisco_addressapi_bbox()`, that return a +#' [`sf`][sf::st_sf] object. +#' +#' +#' @details +#' +#' ```{r child = "man/chunks/addressapi.Rmd"} +#' ``` +#' +#' @seealso +#' +#' See the docs: +#' . +#' +#' @family tools +#' +#' @export +#' @examplesIf gisco_check_access() +#' \donttest{ +#' library(dplyr) +#' +#' # Cities in a region +#' +#' gisco_addressapi_cities(country = "PT", province = "LISBOA") %>% +#' as_tibble() +#' +#' +#' +#' # Geocode and reverse geocode with sf objects +#' library(ggplot2) +#' +#' # Structured search +#' +#' struct <- gisco_addressapi_search( +#' country = "ES", city = "BARCELONA", +#' road = "GRACIA" +#' ) +#' +#' struct %>% +#' ggplot() + +#' geom_sf(aes(color = PC)) + +#' labs(color = "POSTAL CODES") +#' +#' # Reverse geocoding +#' +#' reverse <- gisco_addressapi_reverse(x = struct$X[1], y = struct$Y[1]) +#' +#' glimpse(reverse) +#' } +gisco_addressapi_search <- function(country = NULL, province = NULL, + city = NULL, road = NULL, + housenumber = NULL, postcode = NULL, + verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/search?" + custom_query <- list( + country = country, + province = province, + city = city, + road = road, + housenumber = housenumber, + postcode = postcode + ) + + + call_api(custom_query, apiurl, verbose) +} + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_reverse <- function(x, y, country = NULL, verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/reverse?" + custom_query <- list( + x = x, + y = y, + country = country + ) + + call_api(custom_query, apiurl, verbose) +} + + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_bbox <- function(country = NULL, province = NULL, city = NULL, + road = NULL, postcode = NULL, + verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/bbox?" + custom_query <- list( + country = country, + province = province, + city = city, + road = road, + postcode = postcode + ) + + apiurl <- add_custom_query(custom_query, apiurl) + filename <- "address.json" + namefileload <- gsc_api_cache( + apiurl, filename, + cache_dir = tempdir(), update_cache = TRUE, + verbose = verbose + ) + + if (is.null(namefileload)) { + return(NULL) + } + + results <- jsonlite::read_json(namefileload, + simplifyVector = TRUE, + flatten = TRUE + ) + unlink(namefileload, force = TRUE) + + res <- results$results + res <- as.data.frame(res) + if (any(nrow(res) == 0, results$count == 0, is.na(res))) { + message("No results, returning NULL") + return(NULL) + } + + # Create polygon from WKT + wkt_str <- res$bbox + + wkt_str <- gsub("[A-Za-z]|\\(|\\)", "", wkt_str) + + bbox <- as.double(unlist(strsplit(wkt_str, " |,"))) + + # Mock class + mock <- sf::st_as_sfc("POINT (10 10)", crs = 4326) + bboxclass <- sf::st_bbox(mock) + # Input values + bboxclass[1:4] <- bbox + + bbox <- sf::st_as_sfc(bboxclass) + res <- sf::st_sf(bbox) + + res +} + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_countries <- function(verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/countries" + filename <- "address.json" + namefileload <- gsc_api_cache( + apiurl, filename, + cache_dir = tempdir(), update_cache = TRUE, + verbose = verbose + ) + + if (is.null(namefileload)) { + return(NULL) + } + + results <- jsonlite::read_json(namefileload, + simplifyVector = TRUE, + flatten = TRUE + ) + unlink(namefileload, force = TRUE) + + res <- results$results + res <- data.frame(L0 = unlist(res)) + + return(res) +} + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_provinces <- function(country = NULL, city = NULL, + verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/provinces?" + custom_query <- list( + country = country, + city = city + ) + + call_api(custom_query, apiurl, verbose) +} + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_cities <- function(country = NULL, province = NULL, + verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/cities?" + custom_query <- list( + country = country, + province = province + ) + + call_api(custom_query, apiurl, verbose) +} + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_roads <- function(country = NULL, province = NULL, city = NULL, + verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/roads?" + custom_query <- list( + country = country, + province = province, + city = city + ) + + call_api(custom_query, apiurl, verbose) +} + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_housenumbers <- function(country = NULL, province = NULL, + city = NULL, road = NULL, + postcode = NULL, verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/housenumbers?" + custom_query <- list( + country = country, + province = province, + city = city, + road = road, + postcode = postcode + ) + + call_api(custom_query, apiurl, verbose) +} + + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_postcodes <- function(country = NULL, province = NULL, + city = NULL, verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/postcodes?" + custom_query <- list( + country = country, + province = province, + city = city + ) + + call_api(custom_query, apiurl, verbose) +} + +#' @rdname gisco_addressapi +#' @export +gisco_addressapi_copyright <- function(verbose = FALSE) { + apiurl <- "https://gisco-services.ec.europa.eu/addressapi/copyright" + call_api(custom_query = NULL, apiurl, verbose) +} + +# Helpers +# General ---- + +call_api <- function(custom_query, apiurl, verbose = FALSE) { + apiurl <- add_custom_query(custom_query, apiurl) + filename <- "address.json" + namefileload <- gsc_api_cache( + apiurl, filename, + cache_dir = tempdir(), update_cache = TRUE, + verbose = verbose + ) + + if (is.null(namefileload)) { + return(NULL) + } + + results <- jsonlite::read_json(namefileload, + simplifyVector = TRUE, + flatten = TRUE + ) + unlink(namefileload, force = TRUE) + + res <- results$results + res <- as.data.frame(res) + if (nrow(res) == 0) { + message("No results, returning NULL") + return(NULL) + } + + if ("XY" %in% names(res)) { + # Extract XY coordinates as matrix + xy_coords <- as.data.frame(matrix(unlist(res$XY), ncol = 2, byrow = TRUE)) + names(xy_coords) <- c("X", "Y") + res_clean <- res[, setdiff(names(res), "XY")] + geometry <- sf::st_as_sf(xy_coords, coords = c("X", "Y"), crs = 4326) + + res_clean <- cbind(res_clean, xy_coords) + + res <- cbind(geometry, res_clean) + } + + res +} + +add_custom_query <- function(custom_query = list(), url) { + # Remove NULLs and not populated + custom_query <- custom_query[lengths(custom_query) > 0] + + if (any(length(custom_query) == 0)) { + return(url) + } + + # Collapse + custom_query <- lapply(custom_query, paste0, collapse = ",") + + + opts <- paste0(names(custom_query), "=", custom_query, collapse = "&") + + end_url <- paste0(url, opts) + + + URLencode(end_url) +} diff --git a/README.Rmd b/README.Rmd index 4b982a53..05c8bb1b 100644 --- a/README.Rmd +++ b/README.Rmd @@ -43,7 +43,6 @@ results](https://badges.cranchecks.info/worst/giscoR.svg)](https://cran.r-projec [![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.4317946-blue)](https://doi.org/10.5281/zenodo.4317946) [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![status](https://tinyverse.netlify.app/status/giscoR)](https://CRAN.R-project.org/package=giscoR) diff --git a/README.md b/README.md index 410f1b38..84de3911 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,6 @@ results](https://badges.cranchecks.info/worst/giscoR.svg)](https://cran.r-projec [![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.4317946-blue)](https://doi.org/10.5281/zenodo.4317946) [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![status](https://tinyverse.netlify.app/status/giscoR)](https://CRAN.R-project.org/package=giscoR) @@ -187,7 +186,6 @@ We now download the data from Eurostat: library(eurostat) popdens <- get_eurostat("demo_r_d3dens") %>% filter(TIME_PERIOD == "2021-01-01") -#> indexed 0B in 0s, 0B/sindexed 1.00TB in 0s, 415.28TB/s ``` By last, we merge and manipulate the data for creating the final plot: diff --git a/codemeta.json b/codemeta.json index 34063d23..02e00425 100644 --- a/codemeta.json +++ b/codemeta.json @@ -193,6 +193,18 @@ "sameAs": "https://CRAN.R-project.org/package=geojsonsf" }, "4": { + "@type": "SoftwareApplication", + "identifier": "jsonlite", + "name": "jsonlite", + "provider": { + "@id": "https://cran.r-project.org", + "@type": "Organization", + "name": "Comprehensive R Archive Network (CRAN)", + "url": "https://cran.r-project.org" + }, + "sameAs": "https://CRAN.R-project.org/package=jsonlite" + }, + "5": { "@type": "SoftwareApplication", "identifier": "rappdirs", "name": "rappdirs", @@ -205,7 +217,7 @@ }, "sameAs": "https://CRAN.R-project.org/package=rappdirs" }, - "5": { + "6": { "@type": "SoftwareApplication", "identifier": "sf", "name": "sf", @@ -218,7 +230,7 @@ }, "sameAs": "https://CRAN.R-project.org/package=sf" }, - "6": { + "7": { "@type": "SoftwareApplication", "identifier": "utils", "name": "utils" @@ -228,7 +240,7 @@ "applicationCategory": "cartography", "isPartOf": "http://ropengov.org/", "keywords": ["ropengov", "r", "spatial", "api-wrapper", "rstats", "r-package", "eurostat", "gisco", "thematic-maps", "eurostat-data", "cran", "ggplot2", "gis"], - "fileSize": "1224.516KB", + "fileSize": "1250.44KB", "citation": [ { "@type": "SoftwareSourceCode", diff --git a/inst/WORDLIST b/inst/WORDLIST index 3ee10841..acc5bf9f 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -1,3 +1,4 @@ +API's Arel Biecek Bundock @@ -7,6 +8,7 @@ COAS COmmission CodeFactor DOI +Designator EFTA EPSG ETRS @@ -34,20 +36,23 @@ URBN Urbanisation Verwaltungsgrenzen WGS +WKT administratives al bezuglich bezüglich codecov -codelist colorspace config countrycode der +dev dieghernan dir et +european eurostat +geocoding geojson geospatial ggplot @@ -55,12 +60,16 @@ ggspatial gisco giscoR’ httr +jsonlite kms les licence limites +lwgeom mapsf rOG rcartocolor +roxygen +testthat tidyterra tmap diff --git a/man/chunks/addressapi.Rmd b/man/chunks/addressapi.Rmd new file mode 100644 index 00000000..b4d7c3b7 --- /dev/null +++ b/man/chunks/addressapi.Rmd @@ -0,0 +1,32 @@ +Brief description of the API endpoints (source [GISCO Address API \> +Endpoints](https://gisco-services.ec.europa.eu/addressapi/docs/screen/endpoints): + +| **Endpoint** | **Description** | +|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/countries` | Returns all country codes that are compatible with the address API. Check the coverage map for available countries and see [here for a list of official country codes](https://publications.europa.eu/code/en/en-5000500.htm). | +| `/provinces` | Returns all provinces within the specified country. Can also be used to get the province of a specified city. | +| `/cities` | Returns all cities within a specified province or country. | +| `/roads` | Returns all roads or streets within a specified city. | +| `/housenumbers` | Returns all house numbers or names within the specified road. It is possible that in certain countries an address may not have a road component. In this case, if a road is not specified then the number of house numbers returned by **the API is limited to 1000**. | +| `/postcodes` | Returns all postcodes within the specified address component (Country or Province or City). | +| `/search` | The search endpoint allows structured queries to the address database. Please note that various combinations of each of the parameters can be used in order to retrieve the addresses that share an address component. **The API is limited to a maximum of 100 addresses**. | +| `/reverse` | The API's reverse theme allows you to specify x and y coordinates in order to retrieve a structured address. | +| `/bbox` | Returns a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) bounding box for an address component depending on the parameters specified. | +| `/copyright` | Returns the copyright text for each available country in the Address API. | + +The resulting object may present the following variables: + +| **Property name** | **Description** | +|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `LD` | Refers to "Locator Designator" and represents the house number part of the address | +| `TF` | Refers to "Thoroughfare" and represents the street or road part of the address | +| `L0` | Refers to Level 0 of the API administrative levels. Values are country codes consisting of 2 characters. | +| `L1` | Refers to Level 1 of the API administrative levels. Values are province names. Please note that "province" is a generic term that may differ between countries. | +| `L2` | Refers to Level 2 of the API administrative levels. Values are town or city names. Please note that "city" is a generic term that may differ between countries. | +| `PC` | Postal Code | +| `N0` | Refers to "NUTS 0" | +| `N1` | Refers to "NUTS 1" | +| `N2` | Refers to "NUTS 2" | +| `N3` | Refers to "NUTS 3" | +| `X` and `Y` | Refers to the x and y coordinates of the address point | +| `OL` | Refers to the address' [Open Location Code](https://github.com/google/open-location-code) | diff --git a/man/gisco_addressapi.Rd b/man/gisco_addressapi.Rd new file mode 100644 index 00000000..285c4bd2 --- /dev/null +++ b/man/gisco_addressapi.Rd @@ -0,0 +1,179 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/gisco_addressapi.R +\name{gisco_addressapi} +\alias{gisco_addressapi} +\alias{gisco_addressapi_search} +\alias{gisco_addressapi_reverse} +\alias{gisco_addressapi_bbox} +\alias{gisco_addressapi_countries} +\alias{gisco_addressapi_provinces} +\alias{gisco_addressapi_cities} +\alias{gisco_addressapi_roads} +\alias{gisco_addressapi_housenumbers} +\alias{gisco_addressapi_postcodes} +\alias{gisco_addressapi_copyright} +\title{GISCO Address API} +\usage{ +gisco_addressapi_search( + country = NULL, + province = NULL, + city = NULL, + road = NULL, + housenumber = NULL, + postcode = NULL, + verbose = FALSE +) + +gisco_addressapi_reverse(x, y, country = NULL, verbose = FALSE) + +gisco_addressapi_bbox( + country = NULL, + province = NULL, + city = NULL, + road = NULL, + postcode = NULL, + verbose = FALSE +) + +gisco_addressapi_countries(verbose = FALSE) + +gisco_addressapi_provinces(country = NULL, city = NULL, verbose = FALSE) + +gisco_addressapi_cities(country = NULL, province = NULL, verbose = FALSE) + +gisco_addressapi_roads( + country = NULL, + province = NULL, + city = NULL, + verbose = FALSE +) + +gisco_addressapi_housenumbers( + country = NULL, + province = NULL, + city = NULL, + road = NULL, + postcode = NULL, + verbose = FALSE +) + +gisco_addressapi_postcodes( + country = NULL, + province = NULL, + city = NULL, + verbose = FALSE +) + +gisco_addressapi_copyright(verbose = FALSE) +} +\arguments{ +\item{country}{Country code (\code{country = "LU"}).} + +\item{province}{A province within a country. For a list of provinces within a +certain country use the provinces endpoint +(\code{gisco_addressapi_provinces(country = "LU")}).} + +\item{city}{A city within a province. For a list of cities within a certain +province use the cities endpoint +(\code{gisco_addressapi_cities(province = "capellen")}).} + +\item{road}{A road within a city.} + +\item{housenumber}{The house number or house name within a road or street.} + +\item{postcode}{Can be used in combination with the previous parameters.} + +\item{verbose}{Logical, displays information. Useful for debugging, +default is \code{FALSE}.} + +\item{x, y}{x and y coordinates (as longitude and latitude) to be converted +into a human-readable address.} +} +\value{ +A \code{data.frame} object in most cases, except \code{gisco_addressapi_search()}, +\code{gisco_addressapi_reverse()} and \code{gisco_addressapi_bbox()}, that return a +\code{\link[sf:sf]{sf}} object. +} +\description{ +Access the \href{https://gisco-services.ec.europa.eu/addressapi/docs/screen/home}{GISCO Address API}, that +allows to carry out both geocoding and reverse geocoding using a pan-european +address database. + +Each endpoint available is implemented through a specific function, see +\strong{Details}. + +The API supports fuzzy searching (also referred to as approximate string +matching) for all parameters of each endpoint. +} +\details{ +Brief description of the API endpoints (source \href{https://gisco-services.ec.europa.eu/addressapi/docs/screen/endpoints}{GISCO Address API \> Endpoints}:\tabular{ll}{ + \strong{Endpoint} \tab \strong{Description} \cr + \verb{/countries} \tab Returns all country codes that are compatible with the address API. Check the coverage map for available countries and see \href{https://publications.europa.eu/code/en/en-5000500.htm}{here for a list of official country codes}. \cr + \verb{/provinces} \tab Returns all provinces within the specified country. Can also be used to get the province of a specified city. \cr + \verb{/cities} \tab Returns all cities within a specified province or country. \cr + \verb{/roads} \tab Returns all roads or streets within a specified city. \cr + \verb{/housenumbers} \tab Returns all house numbers or names within the specified road. It is possible that in certain countries an address may not have a road component. In this case, if a road is not specified then the number of house numbers returned by \strong{the API is limited to 1000}. \cr + \verb{/postcodes} \tab Returns all postcodes within the specified address component (Country or Province or City). \cr + \verb{/search} \tab The search endpoint allows structured queries to the address database. Please note that various combinations of each of the parameters can be used in order to retrieve the addresses that share an address component. \strong{The API is limited to a maximum of 100 addresses}. \cr + \verb{/reverse} \tab The API's reverse theme allows you to specify x and y coordinates in order to retrieve a structured address. \cr + \verb{/bbox} \tab Returns a \href{https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry}{WKT} bounding box for an address component depending on the parameters specified. \cr + \verb{/copyright} \tab Returns the copyright text for each available country in the Address API. \cr +} + + +The resulting object may present the following variables:\tabular{ll}{ + \strong{Property name} \tab \strong{Description} \cr + \code{LD} \tab Refers to "Locator Designator" and represents the house number part of the address \cr + \code{TF} \tab Refers to "Thoroughfare" and represents the street or road part of the address \cr + \code{L0} \tab Refers to Level 0 of the API administrative levels. Values are country codes consisting of 2 characters. \cr + \code{L1} \tab Refers to Level 1 of the API administrative levels. Values are province names. Please note that "province" is a generic term that may differ between countries. \cr + \code{L2} \tab Refers to Level 2 of the API administrative levels. Values are town or city names. Please note that "city" is a generic term that may differ between countries. \cr + \code{PC} \tab Postal Code \cr + \code{N0} \tab Refers to "NUTS 0" \cr + \code{N1} \tab Refers to "NUTS 1" \cr + \code{N2} \tab Refers to "NUTS 2" \cr + \code{N3} \tab Refers to "NUTS 3" \cr + \code{X} and \code{Y} \tab Refers to the x and y coordinates of the address point \cr + \code{OL} \tab Refers to the address' \href{https://github.com/google/open-location-code}{Open Location Code} \cr +} +} +\examples{ +\dontshow{if (gisco_check_access()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} +\donttest{ +library(dplyr) + +# Cities in a region + +gisco_addressapi_cities(country = "PT", province = "LISBOA") \%>\% + as_tibble() + + + +# Geocode and reverse geocode with sf objects +library(ggplot2) + +# Structured search + +struct <- gisco_addressapi_search( + country = "ES", city = "BARCELONA", + road = "GRACIA" +) + +struct \%>\% + ggplot() + + geom_sf(aes(color = PC)) + + labs(color = "POSTAL CODES") + +# Reverse geocoding + +reverse <- gisco_addressapi_reverse(x = struct$X[1], y = struct$Y[1]) + +glimpse(reverse) +} +\dontshow{\}) # examplesIf} +} +\seealso{ +See the docs: +\url{https://gisco-services.ec.europa.eu/addressapi/docs/screen/home}. +} +\concept{tools} diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 5c00deea..b6f55601 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -31,6 +31,10 @@ reference: These functions return sf objects with man-made features contents: has_concept("infrastructure") +- title: Tools + desc: > + Access to other GISCO tools + contents: has_concept("tools") - title: Misc desc: > These functions return other % # Eurostat data - Disposable income pps <- get_eurostat("tgs00026") %>% filter(TIME_PERIOD == "2021-01-01") -#> indexed 0B in 0s, 0B/s indexed 1.00TB in 0s, 4.79PB/s -``` - -``` r nuts2_sf <- nuts2 %>% left_join(pps, by = "geo") %>%