valh

Interface between R and the OpenStreetMap-based routing service Valhalla

https://github.com/riatelab/valh

Keywords

openstreetmap r r-package routing valhalla

Keywords from Contributors

cartography

Last synced: 4 months ago · JSON representation ·

Repository

Interface between R and the OpenStreetMap-based routing service Valhalla

Basic Info

Host: GitHub
Owner: riatelab
License: gpl-3.0
Language: R
Default Branch: main
Homepage:
Size: 999 KB

Statistics

Stars: 20
Watchers: 5
Forks: 1
Open Issues: 1
Releases: 1

Topics

openstreetmap r r-package routing valhalla

Created 10 months ago · Last pushed 9 months ago

Metadata Files

Readme Changelog Contributing License Citation Codemeta

README.Rmd

---
output: github_document
---
# valh 

[![CRAN](https://www.r-pkg.org/badges/version/valh)](https://CRAN.R-project.org/package=valh)
[![R build status](https://github.com/riatelab/valh/actions/workflows/check-standard.yaml/badge.svg)](https://github.com/riatelab/valh/actions)
[![codecov](https://codecov.io/gh/riatelab/valh/graph/badge.svg)](https://app.codecov.io/gh/riatelab/valh)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

[Valhalla](https://valhalla.github.io/valhalla/) is a routing service that is based on OpenStreetMap data.
This package provides an interface to the Valhalla API from R.
It allows you to query the Valhalla API for routes, isochrones, time-distance matrices,
nearest point on the road network, and elevation data.

This package relies on the usage of a [running Valhalla server](https://github.com/riatelab/valh?tab=readme-ov-file#installing-your-own-valhalla-server) (tested with versions 3.4.x and 3.5.x of Valhalla).


  

[code for the map](https://gist.github.com/rCarto/8dfba641b807c20c8cbf72ef8ed0c9c5)


## Features 

- `vl_route()`: Get route between locations.
- `vl_matrix()`: Get travel time matrices between points.
- `vl_locate()`: Get the nearest point on the road network.
- `vl_elevation()`: Get elevation data at given location(s).
- `vl_isochrone()`: Get isochrone polygons.
- `vl_optimized_route()`: Get optimized route between locations.
- `vl_status()`: Get information on Valhalla service.

## Installation

- Stable version from CRAN:
```{r}
#| eval: false
install.packages("valh")
```

- Development version from the r-universe.
```{r, eval=FALSE}
install.packages("valh", repos = "https://riatelab.r-universe.dev")
```


## Demo

This is a short overview of the main features of `valh`. The dataset
used here is shipped with the package, it is a sample of 100 random
pharmacies in Berlin ([© OpenStreetMap
contributors](https://www.openstreetmap.org/copyright/en)) stored in a
[geopackage](https://www.geopackage.org/) file.

It demonstrates the use of  `vl_matrix`, `vl_route` and `vl_elevation` functions.

```{r}
library(valh)
library(sf)
pharmacy <- st_read(system.file("gpkg/apotheke.gpkg", package = "valh"), quiet = TRUE)
pharmacy <- pharmacy[1:10, ]
```

One of valhalla's strengths is that it allows you to use dynamic costing options at query time.
For example, we can compare the travel time between each pharmacy by bicycle:

- with the default bicycle parameters (type of bicycle "hybrid" with an average speed
  of 18 km/h and a propensity to use roads, alongside other vehicles, of 0.5 out of 1 - the
  default value),
- with the road bicycle parameters (type of bicycle "road" with an average speed of
  25 km/h and a propensity to use roads, alongside other vehicles, of 1 out of 1).

These costing options for each costing model ('auto', 'bicycle', etc.) are documented in
[Valhalla's documentation](https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/#costing-models).

```{r}
default_bike <- vl_matrix(loc = pharmacy, costing = "bicycle")

road_bike <- vl_matrix(loc = pharmacy, costing = "bicycle",
                       costing_options = list(bicycle_type = "Road", use_roads = "1"))
```

The object returned by `vl_matrix` is a list with 4 elements:

- `sources`: origin point coordinates,
- `destinations`: destination point coordinates,
- `distances` : distance matrix between sources and destinations,
- `durations` : travel time matrix between sources and destinations.


```{r}
default_bike$durations[1:5, 1:5]
road_bike$durations[1:5, 1:5]
```


We can see not only that travel times are different (which is to be expected,
given that we've changed the cyclist's default speed), but also that the path
taken are different (as a consequence of the change in preference for using
roads rather than cycle paths).

```{r}
default_bike$distances - road_bike$distances
```

We now calculate a route between two points, by foot, using the `vl_route`
function and calculate the elevation profile of the returned route, using
the `vl_elevation` function.


```{r, eval = FALSE}
p1 <- pharmacy[3, ]
p2 <- pharmacy[6, ]
route <- vl_route(p1, p2, costing = "pedestrian")
plot(st_geometry(route), main = "Route between 2 pharmacies")
plot(c(st_geometry(p1), st_geometry(p2)), pch = 21, cex = 2, add = TRUE)
```


```{r, echo=FALSE, fig.path="man/figures/README", fig.width=3, fig.height=4, }

p1 <- pharmacy[3, ]
p2 <- pharmacy[6, ]

route <- vl_route(p1, p2, costing = "pedestrian")
par(mar = c(0, 0, 2, 0))
# We plot the route and pharmacies
plot(st_geometry(route), main = "Route between 2 pharmacies")
plot(c(st_geometry(p1), st_geometry(p2)), pch = 21, cex = 2, add = TRUE)
```

```{r}
# We transform the LineString to Point geometries
pts_route <- sf::st_cast(st_geometry(route), "POINT")

elev <- vl_elevation(loc = pts_route, sampling_dist = 100)
```

The object returned is an sf object with a point for each location where the
altitude has been sampled and with the attributes 'distance' (the cumulative
distance to the first point) and 'height' (the altitude).

We can use it to plot the elevation profile of the route.

```{r, fig.width=7, fig.height=4,  fig.path="man/figures/README"}
plot(as.matrix(st_drop_geometry(elev)), type = "l", lwd = 2, ylim = c(20, 70), asp = 100,
     main = "Elevation Profile")
```


## Installing your own Valhalla server

We've included a [vignette](https://CRAN.R-project.org/package=valh/vignettes/install-valhalla.html) showing how to install
your own instance of Valhalla, either locally or on a remote server, using Docker.

## Motivation & Alternatives

The package is designed to provide an easy-to-use interface to the Valhalla routing service from R.
Special care has been taken to support multiple input formats, 
and the package treats `sf` objects as first-class citizens in both input and output.
Additionally, we have tried to maintain a minimal number of dependencies.   

This package offers an API that closely resembles that of the [`osrm`](https://github.com/riatelab/osrm)
package which provides an R interface to the OSRM routing service.

Note that there are other packages that provide an interface to Valhalla API from R :

- [valhallr](https://github.com/chris31415926535/valhallr/): This package is on CRAN. It provides access to some of Valhalla's services (*height*, *locate* and *optimized route* are notably missing). It depends on a number of rather heavy packages and it does not allow `sf` objects as input.
- [rvalhalla](https://github.com/Robinlovelace/rvalhalla): This package is not on CRAN. Although it can provide access to several Valhalla services, it only makes it easy to use two of them (*route* and *sources_to_target*). It does not accept `sf` objects as input.

## Community Guidelines

One can contribute to the package through [pull requests](https://github.com/riatelab/valh/pulls) and
report issues or ask questions [here](https://github.com/riatelab/valh/issues).
See the [CONTRIBUTING.md](https://github.com/riatelab/valh/blob/master/CONTRIBUTING.md)
file for detailed instructions.

Owner

Name: riatelab
Login: riatelab
Kind: organization
Location: Paris

Website: https://riate.cnrs.fr
Repositories: 49
Profile: https://github.com/riatelab

Spatial analysis and mapping software packages created by the Center for Spatial Analysis and Geovisualization - RIATE

Citation (CITATION.cff)

# --------------------------------------------
# CITATION file created with {cffr} R package
# See also: https://docs.ropensci.org/cffr/
# --------------------------------------------
 
cff-version: 1.2.0
message: 'To cite package "valh" in publications use:'
type: software
license: GPL-3.0-or-later
title: 'valh: Interface Between R and the OpenStreetMap-Based Routing Service ''Valhalla'''
version: 0.1.0
doi: 10.32614/CRAN.package.valh
abstract: An interface between R and the 'Valhalla' API. 'Valhalla' is a routing service
  based on 'OpenStreetMap' data. See <https://valhalla.github.io/valhalla/> for more
  information. This package enables the computation of routes, trips, isochrones and
  travel distances matrices (travel time and kilometer distance).
authors:
- family-names: Giraud
  given-names: Timothée
  email: timothee.giraud@cnrs.fr
  orcid: https://orcid.org/0000-0002-1932-3323
- family-names: Viry
  given-names: Matthieu
  orcid: https://orcid.org/0000-0002-0693-8556
repository: https://CRAN.R-project.org/package=valh
repository-code: https://github.com/riatelab/valh
url: https://github.com/riatelab/valh
contact:
- family-names: Giraud
  given-names: Timothée
  email: timothee.giraud@cnrs.fr
  orcid: https://orcid.org/0000-0002-1932-3323
keywords:
- openstreetmap
- r
- r-package
- routing
- valhalla
references:
- 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: jeroenooms@gmail.com
    orcid: https://orcid.org/0000-0002-4035-0289
  year: '2025'
  doi: 10.32614/CRAN.package.jsonlite
- type: software
  title: googlePolylines
  abstract: 'googlePolylines: Encoding Coordinates into ''Google'' Polylines'
  notes: Imports
  url: https://github.com/SymbolixAU/googlePolylines
  repository: https://CRAN.R-project.org/package=googlePolylines
  authors:
  - family-names: Cooley
    given-names: David
    email: dcooley@symbolix.com.au
  year: '2025'
  doi: 10.32614/CRAN.package.googlePolylines
- type: software
  title: curl
  abstract: 'curl: A Modern and Flexible Web Client for R'
  notes: Imports
  url: https://jeroen.r-universe.dev/curl
  repository: https://CRAN.R-project.org/package=curl
  authors:
  - family-names: Ooms
    given-names: Jeroen
    email: jeroenooms@gmail.com
    orcid: https://orcid.org/0000-0002-4035-0289
  year: '2025'
  doi: 10.32614/CRAN.package.curl
- type: software
  title: utils
  abstract: 'R: A Language and Environment for Statistical Computing'
  notes: Imports
  authors:
  - name: R Core Team
  institution:
    name: R Foundation for Statistical Computing
    address: Vienna, Austria
  year: '2025'
- type: software
  title: sf
  abstract: 'sf: Simple Features for R'
  notes: Imports
  url: https://r-spatial.github.io/sf/
  repository: https://CRAN.R-project.org/package=sf
  authors:
  - family-names: Pebesma
    given-names: Edzer
    email: edzer.pebesma@uni-muenster.de
    orcid: https://orcid.org/0000-0001-8049-7069
  year: '2025'
  doi: 10.32614/CRAN.package.sf
- type: software
  title: 'R: A Language and Environment for Statistical Computing'
  notes: Depends
  url: https://www.R-project.org/
  authors:
  - name: R Core Team
  institution:
    name: R Foundation for Statistical Computing
    address: Vienna, Austria
  year: '2025'
  version: '>= 3.5.0'
- type: software
  title: knitr
  abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
  notes: Suggests
  url: https://yihui.org/knitr/
  repository: https://CRAN.R-project.org/package=knitr
  authors:
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  year: '2025'
  doi: 10.32614/CRAN.package.knitr
- type: software
  title: rmarkdown
  abstract: 'rmarkdown: Dynamic Documents for R'
  notes: Suggests
  url: https://pkgs.rstudio.com/rmarkdown/
  repository: https://CRAN.R-project.org/package=rmarkdown
  authors:
  - family-names: Allaire
    given-names: JJ
    email: jj@posit.co
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  - family-names: Dervieux
    given-names: Christophe
    email: cderv@posit.co
    orcid: https://orcid.org/0000-0003-4474-2498
  - family-names: McPherson
    given-names: Jonathan
    email: jonathan@posit.co
  - family-names: Luraschi
    given-names: Javier
  - family-names: Ushey
    given-names: Kevin
    email: kevin@posit.co
  - family-names: Atkins
    given-names: Aron
    email: aron@posit.co
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  - family-names: Cheng
    given-names: Joe
    email: joe@posit.co
  - family-names: Chang
    given-names: Winston
    email: winston@posit.co
  - family-names: Iannone
    given-names: Richard
    email: rich@posit.co
    orcid: https://orcid.org/0000-0003-3925-190X
  year: '2025'
  doi: 10.32614/CRAN.package.rmarkdown
- type: software
  title: tinytest
  abstract: 'tinytest: Lightweight and Feature Complete Unit Testing Framework'
  notes: Suggests
  url: https://github.com/markvanderloo/tinytest
  repository: https://CRAN.R-project.org/package=tinytest
  authors:
  - family-names: Loo
    given-names: Mark
    name-particle: van der
    email: mark.vanderloo@gmail.com
    orcid: https://orcid.org/0000-0002-9807-4686
  year: '2025'
  doi: 10.32614/CRAN.package.tinytest

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "valh",
  "description": "An interface between R and the 'Valhalla' API. 'Valhalla' is a routing service based on 'OpenStreetMap' data. See <https://valhalla.github.io/valhalla/> for more information. This package enables the computation of routes, trips, isochrones and travel distances matrices (travel time and kilometer distance).",
  "name": "valh: Interface Between R and the OpenStreetMap-Based Routing Service 'Valhalla'",
  "codeRepository": "https://github.com/riatelab/valh",
  "issueTracker": "https://github.com/riatelab/valh/issues",
  "license": "https://spdx.org/licenses/GPL-3.0",
  "version": "0.1.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.4.3 (2025-02-28)",
  "provider": {
    "@id": "https://cran.r-project.org",
    "@type": "Organization",
    "name": "Comprehensive R Archive Network (CRAN)",
    "url": "https://cran.r-project.org"
  },
  "author": [
    {
      "@type": "Person",
      "givenName": "Timothe",
      "familyName": "Giraud",
      "email": "timothee.giraud@cnrs.fr",
      "@id": "https://orcid.org/0000-0002-1932-3323"
    },
    {
      "@type": "Person",
      "givenName": "Matthieu",
      "familyName": "Viry",
      "@id": "https://orcid.org/0000-0002-0693-8556"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Timothe",
      "familyName": "Giraud",
      "email": "timothee.giraud@cnrs.fr",
      "@id": "https://orcid.org/0000-0002-1932-3323"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "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=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "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=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "tinytest",
      "name": "tinytest",
      "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=tinytest"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@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"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "googlePolylines",
      "name": "googlePolylines",
      "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=googlePolylines"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "curl",
      "name": "curl",
      "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=curl"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "utils",
      "name": "utils"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "sf",
      "name": "sf",
      "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=sf"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.5.0"
    },
    "SystemRequirements": null
  },
  "fileSize": "252.169KB"
}

GitHub Events

Total

Create event: 1
Issues event: 3
Release event: 1
Watch event: 15
Push event: 12
Pull request event: 2

Last Year

Create event: 1
Issues event: 3
Release event: 1
Watch event: 15
Push event: 12
Pull request event: 2

Committers

Last synced: 7 months ago

All Time

Total Commits: 91
Total Committers: 2
Avg Commits per committer: 45.5
Development Distribution Score (DDS): 0.341

Past Year

Commits: 91
Committers: 2
Avg Commits per committer: 45.5
Development Distribution Score (DDS): 0.341

Top Committers

Name	Email	Commits
rCarto	t**d@c**r	60
Matthieu Viry	m**y@c**r	31

Committer Domains (Top 20 + Academic)

cnrs.fr: 2

Issues and Pull Requests

Last synced: 5 months ago

All Time

Total issues: 1
Total pull requests: 1
Average time to close issues: 1 day
Average time to close pull requests: about 4 hours
Total issue authors: 1
Total pull request authors: 1
Average comments per issue: 0.0
Average comments per pull request: 0.0
Merged pull requests: 1
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 1
Pull requests: 1
Average time to close issues: 1 day
Average time to close pull requests: about 4 hours
Issue authors: 1
Pull request authors: 1
Average comments per issue: 0.0
Average comments per pull request: 0.0
Merged pull requests: 1
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

mthh (2)

Pull Request Authors

mthh (2)

Top Labels

Issue Labels

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- cran 145 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 1
Total maintainers: 1

cran.r-project.org: valh

Interface Between R and the OpenStreetMap-Based Routing Service Valhalla

Homepage: https://github.com/riatelab/valh
Documentation: http://cran.r-project.org/web/packages/valh/valh.pdf
License: GPL (≥ 3)
Latest release: 0.1.0
published 9 months ago

Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 145 Last month

Rankings

Dependent packages count: 26.8%

Dependent repos count: 33.0%

Average: 48.9%

Downloads: 86.7%

Maintainers (1)

timothee.giraud@cnrs.fr

Last synced: 5 months ago

valh

Science Score: 62.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.Rmd

Owner

Citation (CITATION.cff)

CodeMeta (codemeta.json)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

cran.r-project.org: valh

Rankings

Maintainers (1)