Package 'mapirosa'

Title: Access OS OpenData APIs From R
Description: A package to enable accessing basemap tiles from the [OS Maps API](https://osdatahub.os.uk/docs/wmts/overview), initially. Access to other OS (Ordnance Survey) Data Hub APIs may follow. The primary motivation for this project was to find a map tile service that supplies tiles in the British National Grid (27700) CRS, unlike the usual web mapping standard CRS of 3857. The name of the package is an intentional corruption of the Spanish word mariposa 🦋.
Authors: Fran Barton [aut, cre]
Maintainer: Fran Barton <[email protected]>
License: MIT + file LICENSE
Version: 0.1.6
Built: 2024-11-08 05:29:59 UTC
Source: https://github.com/francisbarton/mapirosa

Help Index

Build a basemap from the Ordnance Survey Maps API

Description

Build a basemap from the Ordnance Survey Maps API

Usage

build_basemap(bbox, zoom, crs = c(27700, 3857), ...)

Arguments

bbox

A bbox object (a length 4 vector with names xmin, ymin, xmax, ymax)
zoom

Zoom level, an integer. For crs = 27700, this must be between 0 and 13. For crs = 3857, this must be between 7 and 20. Certain combinations of zoom level and style retrieve tiles from the OS's Premium service, which can generate a financial charge once past a certain level of usage. See the OS Maps API webpages for details.
crs

CRS code (EPSG), an integer, either 27700 (British National Grid) or 3857 (standard web mapping projected coordinate system eg Google Maps, OSM).
...

Other details to pass on to generate_png_data()

Value

A geospatially-referenced raster... hopefully.

Examples

oxf <- create_bbox("Oxford", 27700)
oxford_basemap <- build_basemap(oxf, zoom = 5, style = "road", crs = 27700)

tmap::tm_shape(oxford_basemap, raster.downsample = FALSE) +
  tmap::tm_rgb(max.value = 1)

Internal check for a valid combination of CRS, map style and zoom level

Description

Internal check for a valid combination of CRS, map style and zoom level

Usage

check_zoom(
  zoom,
  style = c("outdoor", "road", "light", "leisure"),
  crs = c(27700, 3857),
  allow_premium = FALSE
)

Arguments

zoom

Zoom level, an integer. For crs = 27700, this must be between 0 and 13. For crs = 3857, this must be between 7 and 20. Certain combinations of zoom level and style retrieve tiles from the OS's Premium service, which can generate a financial charge once past a certain level of usage. See the OS Maps API webpages for details.
crs

CRS code (EPSG), an integer, either 27700 (British National Grid) or 3857 (standard web mapping projected coordinate system eg Google Maps, OSM).

Value

No visible return unless an error is thrown

Use osmdata to easily get a bbox object for a given place name

Description

Only the first search result from osmdata gets used, however

Usage

create_bbox(place, crs)

Arguments

place

string: place name to search for
crs

integer or string: the EPSG code for the desired CRS

Retrieve PNG data (tiles) to cover a bbox, and generate a list of extents for each tile

Description

Retrieve PNG data (tiles) to cover a bbox, and generate a list of extents for each tile

Usage

generate_png_data(
  bbox,
  zoom,
  crs,
  style = c("outdoor", "road", "light", "leisure"),
  squarify = TRUE,
  squarify_to = c("south", "east"),
  cache_tiles = FALSE,
  allow_premium = FALSE,
  debug = FALSE
)

Arguments

bbox

A bbox object (a length 4 vector with names xmin, ymin, xmax, ymax)
zoom

Zoom level, an integer. For crs = 27700, this must be between 0 and 13. For crs = 3857, this must be between 7 and 20. Certain combinations of zoom level and style retrieve tiles from the OS's Premium service, which can generate a financial charge once past a certain level of usage. See the OS Maps API webpages for details.
crs

CRS code (EPSG), an integer, either 27700 (British National Grid) or 3857 (standard web mapping projected coordinate system eg Google Maps, OSM).
style

Map style, a string. One of "road", "outdoor", "light", "leisure". Leisure is only available in the 27700 CRS.
squarify

Whether to add rows/columns to a basemap to make it square. TRUE by default. If a bbox covers a set of basemap tiles that is wider than it is high ("landscape"), squarify will add row(s) of tiles as necessary to make the basemap square. For a portrait basemap (higher than it is wide), squarify retrieves extra columns to make the basemap square.
squarify_to

Where squarify adds an odd number of columns or rows, one more will be added to one side than to the opposite side. In case you have a preference which side should receive more, you can stipulate this here. Needs a character vector. This is set to c("south", "east") by default. If you know that squarify will definitely add columns, say, you can stipulate a single string e.g. "west". If you are not sure whether it will add rows or columns, then enter a vector of length 2, e.g. c("north", "west") depending on your preferences. Note that if 5 rows are added, 3 will be added to your preferred direction, and 2 to the other side; this parameter does not force all 5 rows to be added to your preferred side!
cache_tiles

Instead of converting PNG data from the API into a basemap on the fly, cache data as local PNG files. Not functional yet; hence set to FALSE.
allow_premium

Whether to only access tiles from zoom levels that are within the "OpenData" tier of the OS API. These vary according to map style and CRS. See the API Technical Specification for details. Defaults to FALSE. Set to TRUE if you wish to access zoom levels within the "Premium" service tier (chargeable

debug

Whether to show any errors that were received from the API. This package should handle errors gracefully in general, but if your basemap is not complete then you may wish to turn this on to see what errors there might be.

Value

a list of length 2: a list of PNG data and a list of extents for each tile

Retrieve data from the OS Features API

Description

Function not yet completed and functional. See https://osdatahub.os.uk/docs/wfs/technicalSpecification for details.

Usage

query_features_api(
  x,
  version = c("2.0.0", "1.1.0", "1.0.0"),
  user_agent = NULL
)

Arguments

x

character. The name of a place, or a postcode for example. The API docs say 'A free string text search of OS Names, intended to be an ambiguous/fuzzy search.'
version

character. API version. Most recent (2.0.0) by default.
user_agent

character. NULL by default, which will use the package name.

Value

A raw response from the API endpoint - you will want to process this.

Build and perform a query to the OS Maps API

Description

Build and perform a query to the OS Maps API

Usage

query_maps_api(x, y, zoom, style, crs, user_agent = NULL)

Arguments

x

Tile number (horizontally)
y

Tile number (vertically)
zoom

Zoom level, an integer. For crs = 27700, this must be between 0 and 13. For crs = 3857, this must be between 7 and 20. Certain combinations of zoom level and style retrieve tiles from the OS's Premium service, which can generate a financial charge once past a certain level of usage. See the OS Maps API webpages for details.
crs

CRS code (EPSG), an integer, either 27700 (British National Grid) or 3857 (standard web mapping projected coordinate system eg Google Maps, OSM).
user_agent

A User-Agent string to pass to the API

Value

Raw PNG data

Retrieve data from the OS Names API

Description

Only uses 'find' method currently, not 'nearest' yet. See https://osdatahub.os.uk/docs/names/technicalSpecification for details.

Usage

query_names_api(
  x,
  local_types = NULL,
  bounds = NULL,
  max_results = 1L,
  user_agent = NULL
)

Arguments

x

character. The name of a place, or a postcode for example. The API docs say 'A free string text search of OS Names, intended to be an ambiguous/fuzzy search.'
local_types

character vector. Types of result to return. Examples are: 'City', 'Village'. See API docs for all options. NULL by default (= no filtering by type).
bounds

bbox. The bounding box of an area to limit search to. NULL by default - no filtering by area. Can be supplied as a vector of 4 numerics, in the following XMIN,YMIN,XMAX,YMAX form: c(414000, 114000, 414100, 114100)
max_results

integer. How many results to return. Can be from 1-100. Set to 1 by default.
user_agent

character. NULL by default, which will use the package name.

Value

An sfc geospatial tibble

Examples

query_names_api(c("Stroud", "Gloucester"))