gisco_address_api: GISCO Address API
In giscoR: Download 'Eurostat' 'GISCO' Spatial Data

gisco_address_api

R Documentation

GISCO Address API

Description

Functions to interact with the GISCO Address API, which supports geocoding and reverse geocoding with a pan-European address database.

Each endpoint supported by giscoR has a specific function. See Details. Search supports structured queries and freeform queries with q. Autocomplete through ⁠/search?suggest=⁠ is not implemented in giscoR.

Structured searches support approximate string matching. The API's freeform query parameter q does not support approximate string matching.

Usage

gisco_address_api_search(
  country = NULL,
  province = NULL,
  city = NULL,
  road = NULL,
  housenumber = NULL,
  postcode = NULL,
  verbose = FALSE,
  q = NULL
)

gisco_address_api_reverse(x, y, country = NULL, verbose = FALSE)

gisco_address_api_bbox(
  country = NULL,
  province = NULL,
  city = NULL,
  road = NULL,
  postcode = NULL,
  verbose = FALSE
)

gisco_address_api_countries(verbose = FALSE)

gisco_address_api_provinces(country = NULL, city = NULL, verbose = FALSE)

gisco_address_api_cities(country = NULL, province = NULL, verbose = FALSE)

gisco_address_api_roads(
  country = NULL,
  province = NULL,
  city = NULL,
  verbose = FALSE
)

gisco_address_api_housenumbers(
  country = NULL,
  province = NULL,
  city = NULL,
  road = NULL,
  postcode = NULL,
  verbose = FALSE
)

gisco_address_api_postcodes(
  country = NULL,
  province = NULL,
  city = NULL,
  verbose = FALSE
)

gisco_address_api_copyright(verbose = FALSE)

gisco_address_api_most_populated_cell(
  province = NULL,
  city = NULL,
  verbose = FALSE
)

Arguments

`country`	A country code (`country = "LU"`).
`province`	A province within a country. This is a generic term whose administrative level varies by country. For a list of provinces within a country, use the provinces endpoint (`gisco_address_api_provinces(country = "LU")`).
`city`	A city within a province. This is a generic term whose administrative level varies by country. For a list of cities within a province, use the cities endpoint (`gisco_address_api_cities(province = "capellen")`).
`road`	A road within a city.
`housenumber`	The house number or house name within a road or street.
`postcode`	A postcode to use with the previous arguments.
`verbose`	A logical value indicating whether to display informational messages.
`q`	A single non-empty string for a freeform address search, or `NULL` for a structured search. The string can contain a street, house number, city or postcode. Freeform queries do not support approximate matching.
`x`, `y`	Longitude and latitude coordinates to convert into human-readable addresses. Reverse geocoding returns at most five results.

Details

For gisco_address_api_most_populated_cell(), supply a non-empty string for province or city. If both are supplied, the search is restricted to the city within the province.

The following table describes the endpoints supported by giscoR, based on the GISCO Address API endpoint documentation:

Endpoint	Description
`⁠/countries⁠`	All country codes compatible with the GISCO Address API. Check the coverage map for available countries and see the list of official country codes.
`⁠/provinces⁠`	All provinces within the specified country. The endpoint can also retrieve the province for a specified city.
`⁠/cities⁠`	All cities within a specified province or country.
`⁠/roads⁠`	Roads or streets within a specified city, limited to 1,000 results.
`⁠/housenumbers⁠`	House numbers or names within the specified road, limited to 1,000 results. In some countries, an address may not have a road component, so the road can be omitted.
`⁠/postcodes⁠`	Postcodes within the specified address component, such as country, province or city, limited to 1,000 results.
`⁠/search⁠`	Structured or freeform queries to the address database. Various argument combinations can retrieve addresses that share an address component. The API returns at most 1,000 addresses.
`⁠/reverse⁠`	Structured addresses for longitude and latitude coordinates, limited to five results.
`⁠/bbox⁠`	A WKT bounding box for an address component, depending on the specified arguments.
`⁠/most-populated-cell⁠`	The most populated census grid cell for a province or city. If both are supplied, the search is restricted to the city within the province.
`⁠/copyright⁠`	The copyright text for each available country in the GISCO Address API.

Use q in gisco_address_api_search() for a freeform search. Unlike structured searches, freeform queries do not support approximate matching. Autocomplete through ⁠/search?suggest=⁠ is not implemented in giscoR.

The resulting object may include these variables:

Property name	Description
`LD`	Locator designator, which represents the house number part of the address.
`TF`	Thoroughfare, which represents the street or road part of the address.
`L0`	Level 0 of the API administrative levels. Values are two-character country codes.
`L1`	Level 1 of the API administrative levels. Values are province names. "Province" is a generic term that may vary by country.
`L2`	Level 2 of the API administrative levels. Values are town or city names. "City" is a generic term that may vary by country.
`I3`	ISO 3166-1 alpha-3 country code.
`PC`	Postal code.
`N0`	NUTS 0.
`N1`	NUTS 1.
`N2`	NUTS 2.
`N3`	NUTS 3.
`X` and `Y`	Numeric coordinates extracted from the API's `XY` pair. Search and reverse geocoding return longitude and latitude. The most-populated-cell function preserves the API coordinates, whose CRS is not specified in the API documentation.
`OL`	The Open Location Code for the address.

Value

A tibble in most cases, except gisco_address_api_search(), gisco_address_api_reverse() and gisco_address_api_bbox(), which return an sf object when geometry is available. Searches with no results return an empty tibble. gisco_address_api_bbox() returns NULL when no bounding box is found. Failed requests return NULL.

gisco_address_api_most_populated_cell() returns a one-row tibble for the most populated census grid cell, or NULL when no cell is found or the request fails. Its numeric X and Y columns preserve the API coordinates, whose CRS is not specified in the API documentation.

Source

https://gisco-services.ec.europa.eu/addressapi/docs/screen/home.

Examples


# Cities in a region.

gisco_address_api_cities(country = "PT", province = "LISBOA")

# Geocode and reverse geocode with `sf` objects.
# Structured search.
struct <- gisco_address_api_search(
  country = "LU", city = "Luxembourg",
  road = "Rue Alphonse Weicker"
)

struct

# Freeform search.
gisco_address_api_search(q = "alphonse weicker luxembourg")

# Reverse geocoding.
reverse <- gisco_address_api_reverse(x = struct$X[1], y = struct$Y[1])

reverse

# Most populated census grid cell in Madrid.
gisco_address_api_most_populated_cell(city = "Madrid")

giscoR documentation built on Oct. 1, 2026, 5:13 p.m.