Type:	Package
Title:	R Tools for Helsinki Open Data
Version:	1.0.6
Date:	2022-11-30
Description:	Tools for accessing various open data APIs in the Helsinki region in Finland. Current data sources include the Service Map API, Linked Events API, and Helsinki Region Infoshare statistics API.
License:	BSD_2_clause + file LICENSE
Depends:	R (≥ 3.1.0)
Imports:	jsonlite, httr, purrr, xml2, methods, dplyr, sf, curl,
Suggests:	knitr, rmarkdown, remotes, ggplot2, covr, testthat (≥ 3.0.0),
URL:	http://ropengov.github.io/helsinki/, https://github.com/rOpenGov/helsinki
BugReports:	https://github.com/ropengov/helsinki/issues
VignetteBuilder:	knitr
NeedsCompilation:	no
Repository:	CRAN
Encoding:	UTF-8
RoxygenNote:	7.2.1
Config/testthat/edition:	3
X-schema.org-isPartOf:	http://ropengov.org/
X-schema.org-keywords:	ropengov
Packaged:	2022-12-02 07:52:31 UTC; juusoparkkinen
Author:	Juuso Parkkinen [aut, cre], Joona Lehtomaki [aut], Pyry Kantanen [aut], Leo Lahti [aut]
Maintainer:	Juuso Parkkinen <juuso.parkkinen@iki.fi>
Date/Publication:	2022-12-02 09:30:05 UTC

Helsinki open data R tools

Description

Brief summary of the helsinki package

Details

Tools for accessing various open data sources in the Helsinki region in Finland.

Author(s)

Juuso Parkkinen, Leo Lahti, Joona Lehtomaki and Pyry Kantanen louhos@googlegroups.com

References

See citation("helsinki") https://github.com/rOpenGov/helsinki

Examples

# library(helsinki)

Get city administrative regions

Description

Sf object of city districts in the Helsinki Capital Region.

Usage

get_city_map(city = NULL, level = NULL, ...)

Arguments

Details

See get_feature_list() for a list of all available features

Value

sf object

Author(s)

Pyry Kantanen pyry.kantanen@gmail.com

Source

Metropolitan area in districts: https://hri.fi/data/en_GB/dataset/seutukartta

Examples

## Not run: 
map <- get_city_map(city = "helsinki", level = "suuralue")

## End(Not run)

Produce an SF object

Description

Produces an sf object for easy visualization

Usage

get_feature(
  base.url = "https://kartta.hsy.fi/geoserver/wfs",
  typename = "asuminen_ja_maankaytto:Vaestotietoruudukko_2015",
  CRS = 3879
)

Arguments

Value

sf object

Author(s)

Pyry Kantanen pyry.kantanen@gmail.com

See Also

Use get_feature_list to list all available features for a given WFS, select_feature for listing and selecting a feature

Print all available Features

Description

Basically a neat wrapper for "request=GetCapabilities".

Usage

get_feature_list(base.url = NULL, queries = c(request = "GetCapabilities"))

Arguments

Details

Lists all ⁠<FeatureType>⁠ nodes.

Value

data frame

Author(s)

Pyry Kantanen pyry.kantanen@gmail.com

See Also

Use get_feature() to download feature, select_feature() for menu-driven listing and downloading

Examples

## Not run: 
dat <- get_feature_list(base.url = "https://kartta.hsy.fi/geoserver/wfs")

## End(Not run)

List HRI datasets

Description

List HRI datasets

Usage

get_hri_dataset_list()

Details

This function lists all available HRI datasets.

Get HRI dataset metadata

Description

Get HRI dataset metadata

Usage

get_hri_dataset_metadata(id)

Details

This function fetches metadata for HRI datasets.

Helsinki Region Infoshare statistics API

Description

Retrieves data from the Helsinki Region Infoshare (HRI) statistics API: http://dev.hel.fi/stats/. Currently provides access to the aluesarjat data: https://stat.hel.fi/pxweb/fi/Aluesarjat/.

Usage

get_hri_stats(query = "", verbose = TRUE)

Arguments

Details

Current implementation is very simple. You can either get the list of resources with query="", or query for a specific resources and retrieve it in a three-dimensional array form.

Value

multi-dimensional array

Author(s)

Juuso Parkkinen louhos@googlegroups.com

References

See citation("helsinki")

See Also

See https://dev.hel.fi/apis/statistics/dev.hel.fi website and http://dev.hel.fi/stats/API documentation (in Finnish)

Examples

## Not run: 
stats_array <- get_hri_stats("aluesarjat_a03s_hki_vakiluku_aidinkieli")

## End(Not run)

Access Helsinki Linked Events API

Description

Easy access to Helsinki Linked Events API

Usage

get_linkedevents(query, ...)

Arguments

Details

Complete list of possible query input: "keyword", "keyword_set", "place", "language", "organization", "image", "event", "search", "user".

With "..." the user can pass on additional parameters that depend on the chosen query input. For example, when performing a search (query = "search"), the search can be narrowed down with parameters such as:

• q="konsertti" complete search, returns events that have the word "konsertti"

• input="konse" partial search, returns events with words that contain "konse"

• type="event" returns only "events"

• start="2017-01-01" events starting on 2017-01-01 or after

• end="2017-01-10" events ending on 2017-01-10 or before

For more detailed explanation, see http://api.hel.fi/linkedevents/v1/.

Value

Data frame or a list

Author(s)

Juuso Parkkinen louhos@googlegroups.com, Pyry Kantanen

Source

Helsinki Linked Events API v1. Developed by the City of Helsinki Open Software Development team. Event data from Helsinki Marketing, Helsinki Cultural Centres, Helmet metropolitan area public libraries and City of Helsinki registry of service unit. CC BY 4.0. https://creativecommons.org/licenses/by/4.0/

For more API documentation and license information see the API link: http://api.hel.fi/linkedevents/v1/

Examples

## Not run: 
events <- get_linkedevents(query="search", q="teatteri", start="2020-01-01")

## End(Not run)

Produce an SF object: Rakennustietoruudukko

Description

Produces an sf object for Rakennustietoruudukko (building information grid).

Usage

get_rakennustietoruudukko(year = NULL)

Arguments

Details

Additional data not available here can be manually downloaded from HRI website: https://hri.fi/data/fi/dataset/rakennustietoruudukko

Years 2015-2021 are tested to work at the time of development. Additional years may be added in the future and older datasets may be removed from the API. Datasets from years 2015-2021 are downloaded from HSY WFS API and datasets for other years are downloaded as zip files from HRI website. The format of the output might be a bit different between datasets downloaded from the WFS API and datasets downloaded from HRI website.

Additional years may be added in the future and older datasets may be removed from the API. See package NEWS for more information.

The current datasets can be listed with get_feature_list() or select_feature().

Value

sf object

Author(s)

Pyry Kantanen pyry.kantanen@gmail.com

Examples

## Not run: 
building_grid <- get_rakennustietoruudukko(year = 2021)

## End(Not run)

Access Helsinki region Service Map API

Description

Access the new Helsinki region Service Map (Paakaupunkiseudun Palvelukartta, https://palvelukartta.hel.fi/fi/) data through the API: http://api.hel.fi/servicemap/v2/. For more API documentation and license information see the API link.

Usage

get_servicemap(query, ...)

Arguments

Details

Complete list of possible query input:

• "unit" unit, or service point

• "service" category of service provided by a unit

• "organization" organization providing services

• "search" full text search for units, services and street addresses

• "accessibility" rule database for calculating accessibility scores

• "geography" spatial information, where services are located

With "..." the user can pass on additional parameters that depend on the chosen query input. For example, when performing a search (query = "search"), the search can be narrowed down with parameters such as:

• "q" complete search

• "input" partial search

• "type" valid types: service_node, service, unit, address

• "language" as two-character ISO-639-1 code: fi, sv, en

• "municipality" comma-separated list of municipalities, lower-case, in Finnish

• "service" comma-separated list of service IDs

• "include" include the complete content from certain fields with a comma-separated list of field names with a valid type prefix

• "only" restricts the results with a comma-separated list of field names with a valid type prefix

• "page" request a certain page number

• "page_size" determine number of entries in one page

For more detailed explanation, see https://dev.hel.fi/apis/service-map-backend-api/.

Value

Data frame or a list

Author(s)

Juuso Parkkinen louhos@googlegroups.com, Pyry Kantanen

Source

API contents: All content is available under CC BY 4.0, except where otherwise stated. The City of Helsinki logo is a registered trademark. The Helsinki Grotesk Typeface is a proprietary typeface licensed by Camelot Typefaces. https://creativecommons.org/licenses/by/4.0/

API Location: https://api.hel.fi/servicemap/v2/

API documentation: https://dev.hel.fi/apis/service-map-backend-api/

Examples

## Not run: 
# A data.frame with 47 variables
search_puisto <- get_servicemap(query="search", q="puisto")
# A data.frame with 7 variables
search_padel <- get_servicemap(query="search", input="padel", 
only="unit.name, unit.location.coordinates, unit.street_address", 
municipality="helsinki")

## End(Not run)

Produce an SF object: Vaestotietoruudukko

Description

Produces an sf object for Väestötietoruudukko (population grid).

Usage

get_vaestotietoruudukko(year = NULL)

Arguments

Details

Additional data not available here can be manually downloaded from HRI website: https://hri.fi/data/fi/dataset/vaestotietoruudukko

Years 1997-2003 and 2008-2021 are tested to work at the time of development. Datasets from years 2015-2021 are downloaded from HSY WFS API and datasets for other years are downloaded as zip files from HRI website. The format of the output might be a bit different between datasets downloaded from the WFS API and datasets downloaded from HRI website.

Additional years may be added in the future and older datasets may be removed from the API. See package NEWS for more information.

The current datasets can be listed with get_feature_list() or select_feature().

Value

sf object

Author(s)

Pyry Kantanen pyry.kantanen@gmail.com

Examples

## Not run: 
pop_grid <- get_vaestotietoruudukko(year = 2021)

## End(Not run)

Gracefully fail internet resources

Description

Function for gracefully failing internet resources

Usage

gracefully_fail(remote.file, timeout.s = NULL)

Author(s)

Kostas Vasilopoulos

Source

Gracefully failing HTTP request code (slightly adapted by Pyry Kantanen) from RStudio community member kvasilopoulos. Many thanks!

Source of the original RStudio community discussion: https://community.rstudio.com/t/internet-resources-should-fail-gracefully/49199

Deprecated functions in package helsinki.

Description

The functions listed below are deprecated and will be defunct in the near future. When possible, alternative functions with similar functionality are also mentioned. Help pages for deprecated functions are available at help("<function>-deprecated").

Interactively browse and select features

Description

Use an interactive menu to select and download a feature for use in other functions

Usage

select_feature(base.url = NULL, get = FALSE)

Arguments

Value

feature Title (character) or feature object (sf), if get parameter is TRUE

Author(s)

Pyry Kantanen pyry.kantanen@gmail.com

See Also

get_feature, get_feature_list

Examples

## Not run: 
selection <- select_feature(base.url = "https://kartta.hsy.fi/geoserver/wfs")
feature <- get_feature(base.url = "https://kartta.hsy.fi/geoserver/wfs", type_name = selected)
ggplot(feature) +
  geom_sf()

## End(Not run)

Transform to sf-object

Description

Transform a wfs_api object into a sf object.

Usage

to_sf(api_obj)

Arguments

Details

FMI API response object's XML (GML) content is temporarily wrtitten on disk and then immediately read back in into a sf object.

Value

sf object

Note

For internal use, not exported.

Author(s)

Joona Lehtomäki joona.lehtomaki@iki.fi

WFS API

Description

Requests to various WFS API.

Usage

wfs_api(base.url = NULL, queries, ...)

Arguments

Details

Make a request to the spesific WFS API. The base url is https://kartta.hsy.fi/geoserver/wfs to which other components defined by the arguments are appended.

This is a low-level function intended to be used by other higher level functions in the package.

Value

wfs_api (S3) object with the following attributes:

content

XML payload.

path

path provided to get the resonse.

response

the original response object.

Author(s)

Joona Lehtomäki joona.lehtomaki@iki.fi, Kostas Vasilopoulos, Pyry Kantanen

Source

Gracefully failing HTTP request code (slightly adapted by Pyry Kantanen) from RStudio community member kvasilopoulos. Many thanks!

Source of the original RStudio community discussion: https://community.rstudio.com/t/internet-resources-should-fail-gracefully/49199

Examples

## Not run: 
  wfs_api(base.url = "https://kartta.hsy.fi/geoserver/wfs", 
          queries = c("service" = "WFS", 
          "version" = "1.0.0", 
          "request" = "getFeature", 
          "typeName" = "ilmanlaatu:Ilmanlaatu_nyt")
          )

## End(Not run)