The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Version: 0.3.3
Title: Tools for Working with Geohashes
Maintainer: Michael Chirico <MichaelChirico4@gmail.com>
Depends: R (≥ 3.0.0)
Description: Tools for working with Gustavo Niemeyer's geohash coordinate system, including API for interacting with other common R GIS libraries.
URL: https://github.com/MichaelChirico/geohashTools
License: MPL-2.0 | file LICENSE
Imports: methods
Suggests: sf, sp, testthat (≥ 3.0.0), knitr, rmarkdown, ggplot2
Config/testthat/edition: 3
VignetteBuilder: knitr
Encoding: UTF-8
RoxygenNote: 7.2.3
NeedsCompilation: yes
Packaged: 2023-10-21 19:43:30 UTC; michael
Author: Michael Chirico [aut, cre], Dmitry Shkolnik [ctb]
Repository: CRAN
Date/Publication: 2023-10-21 20:10:02 UTC

Geohash decoding

Description

Convert geohash-encoded strings into latitude/longitude coordinates

Usage

gh_decode(geohashes, include_delta = FALSE, coord_loc = 'c')

Arguments

geohashes

character or factor vector or of input geohashes. There's no need for all inputs to be of the same precision.

include_delta

logical; should the cell half-width delta be included in the output?

coord_loc

character specifying where in the cell points should be mapped to; cell centroid is mapped by default; case-insensitive. See Details.

Details

coord_loc can be the cell's center ('c' or 'centroid'), or it can be any of the 8 corners (e.g. 's'/'south' for the midpoint of the southern boundary of the cell, or 'ne'/'northeast' for the upper-right corner.

For factor input, decoding will be done on the levels for efficiency.

Value

list with the following entries:

latitude

numeric vector of latitudes (y-coordinates) corresponding to the input geohashes, with within-cell position dictated by coord_loc

longitude

numeric vector of longitudes (x-coordinates) corresponding to the input geohashes, with within-cell position dictated by coord_loc

delta_latitude

numeric vector of cell half-widths in the y direction (only included if include_delta is TRUE

delta_longitude

numeric vector of cell half-widths in the x direction (only included if include_delta is TRUE

Author(s)

Michael Chirico

References

http://geohash.org/ ( Gustavo Niemeyer's original geohash service )

Examples

# Riddle me this
gh_decode('stq4s8c')

# Cell half-widths might be convenient to include for downstream analysis
gh_decode('tjmd79', include_delta = TRUE)

Geohash encoding

Description

Convert latitude/longitude coordinates into geohash-encoded strings

Usage

gh_encode(latitude, longitude, precision = 6L)

Arguments

latitude

numeric vector of input latitude (y) coordinates. Must be in [-90, 90).

longitude

numeric vector of input longitude (x) coordinates. Should be in [-180, 180).

precision

Positive integer scalar controlling the 'zoom level' – how many characters should be used in the output.

Details

precision is limited to at most 28. This level of precision encodes locations on the globe at a nanometer scale and is already more than enough for basically all applications.

Longitudes outside [-180, 180) will be wrapped appropriately to the standard longitude grid.

Value

character vector of geohashes corresponding to the input. NA in gives NA out.

Author(s)

Michael Chirico

References

http://geohash.org/ ( Gustavo Niemeyer's original geohash service )

Examples

# scalar input is treated as a vector
gh_encode(2.345, 6.789)

# geohashes are left-closed, right-open, so boundary coordinates are
#   associated to the east and/or north
gh_encode(0, 0)

Geohash neighborhoods

Description

Return the geohashes adjacent to input geohashes

Usage

gh_neighbors(geohashes, self = TRUE)
gh_neighbours(geohashes, self = TRUE)

Arguments

geohashes

character vector of input geohashes. There's no need for all inputs to be of the same precision.

self

Should the input also be returned as a list element? Convenient for one-line usage / piping

Details

North/south-pole adjacent geohashes are missing three of their neighbors; these will be returned as NA_character_.

Value

list with character vector entries in the direction relative to the input geohashes indicated by their name (e.g. value$south gives all of the southern neighbors of the input geohashes).

The order is self (if self = TRUE), southwest, south, southeast, west, east, northwest, north, northeast (reflecting an easterly, then northerly traversal of the neighborhod).

Author(s)

Michael Chirico

References

http://geohash.org/ ( Gustavo Niemeyer's original geohash service )

Examples

gh_neighbors('d7q8u4')

Helpers for interfacing geohashes with sp/sf objects

Description

These functions smooth the gateway between working with geohashes and geospatial information built for the major geospatial packages in R, sp and sf.

Usage

gh_to_sp(geohashes)
gh_to_spdf(...)
gh_to_sf(...)

gh_covering(SP, precision = 6L, minimal = FALSE)

## Default S3 method:
gh_to_spdf(geohashes, ...)

## S3 method for class 'data.frame'
gh_to_spdf(gh_df, gh_col = 'gh', ...)

Arguments

geohashes

character vector of geohashes to be converted to polygons.

...

Arguments for subsequent methods.

SP

A Spatial object (requires bbox and proj4string methods, and over if minimal is TRUE)

precision

integer specifying the precision of geohashes to use, same as gh_encode

minimal

logical; if FALSE, the output will have all geohashes in the bounding box of SP; if TRUE, any geohashes not intersecting SP will be removed.

gh_df

data.frame which 1) contains a column of geohashes to be converted to polygons and 2) will serve as the data slot of the resultant SpatialPolygonsDataFrame object.

gh_col

character column name saying where the geohashes are stored in gh_df.

Details

gh_to_sp relies on the gh_decode function. Note in particular that this function accepts any length of geohash (geohash-6, geohash-4, etc.) and is agnostic to potential overlap, though duplicates will be caught and excluded.

gh_to_spdf.data.frame will use match.ID = FALSE in the call to SpatialPolygonsDataFrame. Please file an issue if you'd like this to be more flexible.

gh_to_sf is just a wrapper of st_as_sf around gh_to_spdf; as such it requires both sp and sf packages to work.

Value

For gh_to_sp, a SpatialPolygons object.

For gh_to_spdf, a SpatialPolygonsDataFrame object.

For gh_to_sf, a sf object.

Examples

  # get the neighborhood of this geohash in downtown Apia as an sp object
  downtown = '2jtc5x'
  apia_nbhd = unlist(gh_neighbors(downtown))
  apia_sp = gh_to_sp(apia_nbhd)

  # all geohashes covering a random sampling within Apia:
  apia_covering = gh_covering(smp <- sp::spsample(apia_sp, 10L, 'random'))

  apia_sf = gh_to_sf(apia_nbhd)

Geohash utilities

Description

Various common functions that arise when working often with geohashes

Usage

gh_delta(precision)

Arguments

precision

integer precision level desired.

Value

Length-2 numeric vector; the first element is the latitude (y-coordinate) half-width at the input precision, the second element is the longitude (x-coordinate).

Note

Caveat coder: not much is done in the way of consistency checking since this is a convenience function. So e.g. real-valued "precision"s will give results.

Author(s)

Michael Chirico

References

http://geohash.org/ ( Gustavo Niemeyer's original geohash service )

Examples

  gh_delta(6)

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.