The OneMapSGAPI package provides useful wrappers for the OneMapSG API client. It allows users to easily query spatial data from the API in a tidy format and provides additional functionalities to allow easy data manipulation.
library(onemapsgapi)
library(dplyr)
#>
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#>
#> filter, lag
#> The following objects are masked from 'package:base':
#>
#> intersect, setdiff, setequal, unionThis function is a wrapper for the Search API. It
allows input of a dataframe of place names and output of the original
dataframe with additional columns, including spatial coordinates and
address information. Users can also optionally return the output an
sf dataframe. If an error occurs, the result for that row
will be empty and a warning message with the API error and status code
will be printed.
Please note that only the top result returned by the API will be included.
This function is a wrapper for the Authentication
API endpoint In order to query data, most API endpoints in the
OneMapSG API require a token. First-time users can register themselves
using the OneMapSG
registration form. Subsequently, they can retrieve their tokens
using the get_token() function with their email and
password, for example:
The function will also print a message informing users of the token’s expiry date and time.
These functions are wrappers for the Themes API endpoints. Themes in the OneMap SG API refer to types of locations, such as kindergartens, parks, hawker centres etc.
The get_theme_status() function allows users to check if
data associated with a theme has been updated after a certain time. It
returns a named logical.
# returns named logical
get_theme_status(token, "kindergartens")
get_theme_status(token, "hotels", "2020-01-01", "12:00:00")The get_theme_info() function allows users to get
information related to a specific theme. It returns a named character
vector with Theme Name and Query Name.
If an error occurs, the function throws an error, along with the API error message and status code.
The search_themes() function allows users to find
details of themes of interest. It returns a tibble of themes matching
user’s search terms. Alternatively, if no search terms are added, a
tibble of all themes available through the API is returned. The variable
THEMENAME in the output tibble serves as the input for
getting theme data.
If an error occurs, the function throws an error, along with the API error message and status code.
The function get_theme() returns data related to a
particular theme, often location coordinates and other information. It
returns the output as a tibble, or prints a warning message when an
error is encountered. All tibbles will contain the variables:
NAME, DESCRIPTION,
ADDRESSPOSTALCODE, ADDRESSSTREETNAME,
Lat, Lng, ICON_NAME,
and some provide additional information; for example, query hawker
centres gives additional information about the completion date of each
hawker centre. Option to return a spatial dataframe available.
# return all monuments data within a bounding area
get_theme(token, "monuments", extents = "1.291789,%20103.7796402,1.3290461,%20103.8726032")# returns a list of status tibble and output tibble
get_theme(token, "funeralparlours", return_info = TRUE) |>
str()# error: throws an error, along with the API error message and status code
get_theme("invalid_token", "hotels")
# error: throws an error, along with the API error message and status code
get_theme(token, "non-existent-theme")
# error: output is query_info, warning message query did not return any records
get_theme(token, "ura_parking_lot", "1.291789,%20103.7796402,1.3290461,%20103.8726032")These functions are a wrapper for the Planning Area API. Planning Area API endpoints allow users to get spatial data and data related to the planning areas in Singapore. This package provides users with the ability to query the data and optionally handles necessary spatial data wrangling on behalf of the user.
The function get_planning_areas() allows users to query
all the spatial polygons associated with Singapore’s planning areas, for
certain years. The function also optionally helps users transform raw
geojson strings into sf objects.
If the parameter return_spatial = FALSE, the function
returns a raw JSON object with planning names and geojson string
vectors.
If the parameter return_spatial = TRUE, any missing
geojson objects will be dropped (this affects the “Others” planning area
returned by the API). The returned outputs are NOT projected.
Note that if the user specifies to return_spatial but does not have the sf package installed, the function will return the raw JSON and print a warning message.
If an error occurs, the function throws an error, along with the API error message and status code.
The function get_planning_names() allows users to query
all planning area names for certain years. The function returns a tibble
with planning area code and planning area name.
If an error occurs, the function throws an error, along with the API error message and status code.
The function get_planning_polygon() allows users to
query a particular planning area polygon containing the specified
location point. The function also optionally helps users transform raw
geojson string output into an sf object.
If the parameter return_spatial = FALSE, the function
returns a raw JSON object with planning names and geojson string
vectors.
# returns raw JSON object
get_planning_polygon(token, lat = 1.429443081, lon = 103.835005)
get_planning_polygon(token, lat = 1.429443081, lon = 103.835005, year = 2008)If the parameter return_spatial = TRUE, any missing
geojson objects will be dropped (this affects the “Others” planning area
returned by the API). The returned outputs are NOT projected.
# returns dataframe of class "sf"
get_planning_polygon(token, lat = 1.429443081, lon = 103.835005, return_spatial = TRUE)Note that if the user specifies a read method but does not have the corresponding package installed, the function will return the raw JSON and print a warning message.
If an error occurs, the function throws an error, along with the API error message and status code.
These functions are a wrapper for the Population
Query API. Population Query API endpoints allow users to pull
socio-economic datasets by planning area, which each endpoint
representing a dataset (e.g. getPopulationAgeGroup provides
age group summary statistics by planning area). This package combines
querying different Popquery API endpoints into single functions.
The function get_pop_queries() allows users to query
multiple datasets for multiple towns, years and genders.
The gender parameter is only valid for the
getEconomicStatus, getEthnicGroup,
getMaritalStatus and
getPopulationAgeGroup endpoints. If specified for other
endpoints, the parameter will be dropped.
If gender is not specified for endpoints which accept a gender parameter, records for total, male and female will be returned.
The function returns a tibble with each row representing a town in a particular year for a particular gender, and columns representing the variables returned by the API endpoint. If any API call returns no data, the values will be NA but the row will be returned. However, if all data_types do not return data for that town and year, no row will be returned for it.
# example: returns output with no NA
get_pop_queries(token, c("getReligion", "getLanguageLiterate"),
c("Bedok", "Yishun"), "2010")
# example: returns output with no NA and gender field
get_pop_queries(token, c("getEconomicStatus", "getEthnicGroup"),
"Yishun", "2010", "female")If the data types request contains a mix of those that accept gender
parameters and those that do not, only gender = "Total"
rows will display all records. The data types that do not accept gender
params will return results under gender = Total.
# example: gender not specified
get_pop_queries(token, c("getEconomicStatus", "getOccupation", "getLanguageLiterate"),
"Bedok", "2010")# example: gender specified
get_pop_queries(token, c("getEconomicStatus", "getOccupation", "getLanguageLiterate"),
"Bedok", "2010", gender = "female")If all data_types do not return data for that town and year, no row will be returned. A warning message will show data_type/town/year/gender for which an error occurred.
# example: no records for 2012
get_pop_queries(token, c("getEconomicStatus", "getOccupation"),
"Bedok", c("2010", "2012"))Finally, to allow for faster computation, API calls can be called in
parallel using parallel = TRUE. This is recommended for
large requests.
These functions are a wrapper for the Route Service API. The Route Service API provides users a way to query the route taken from one point to another. It provides information about the total time and distance taken for the route, route instructions and other infomation e.g. elevation, for a variety of routes (public transport, drive, walk, cycle). This package provides two different functions associated with this API, each serving different purposes.
The function get_summ_route() returns the total time,
distance and optionally the route geometry between two points. Users
input a vector of start coordinates and a vector of end coordinates. The
function returns a tibble with total_time,
total_dist and optionally route_geometry.
# example: return driving distance and time between two points
get_summ_route(token, c(1.320981, 103.844150), c(1.326762, 103.8559), "drive")# example: return public transport distance and time between two points, with route geometry
get_summ_route(token, c(1.320981, 103.844150), c(1.326762, 103.8559),
"drive", route_geom = TRUE)If an error occurs, the function returns NULL, along
with the API error message and status code.
The function get_travel() allows the calculation of
total travel time and distance for a tibble of start and end points.
Users input a tibble of start and end points (and potentially other
variables) and the function returns the tibble with additional columns,
total_time and total_dist. Recognising that
this API is most valuable for calculating total time travelled (as a
improved measure of spatial distance compared to Euclidean distance),
this function produces a cleaner output containing only the main
variables of interest.
The function also accepts multiple arguments for route
and pt_mode, allowing users to compare various route
options.
Note that if as_wide = TRUE is selected, any columns
with identical names as the additional output columns will be
overwritten.
# example: create sample df with start and end coordinates
sample <- data.frame(start_lat = c(1.3746617, 1.3567797, 1.3361976, 500),
start_lon = c(103.8366159, 103.9347695, 103.6957732, 501),
end_lat = c(1.429443081, 1.380298287, 1.337586882, 601),
end_lon = c(103.835005, 103.7452918, 103.6973215, 600),
add_info = c("a", "b", "c", "d"))# example: multiple routes
get_travel(token, sample[1:3, ],
"start_lat", "start_lon", "end_lat", "end_lon",
routes = c("cycle", "walk"))# example: multiple routes + multiple pt modes
get_travel(token, sample[1:3, ],
"start_lat", "start_lon", "end_lat", "end_lon",
routes = c("drive", "pt"), pt_mode = c("bus", "transit"))By default, the data appears in a wide format, but users can specify for the output to be in long format.
# example: long format
get_travel(token, sample[1:3, ],
"start_lat", "start_lon", "end_lat", "end_lon",
routes = c("walk", "pt"), pt_mode = c("bus", "transit"),
as_wide = FALSE)There is also the option to return a sf dataframe in long format by
specifying route_geom = TRUE. This allows, for example,
mapping of different route options.
get_travel(token, sample[1:3, ],
"start_lat", "start_lon", "end_lat", "end_lon",
routes = c("drive", "pt"), pt_mode = c("bus", "transit"),
as_wide = FALSE, route_geom = TRUE)If an error occurs, the output row will be have NAs for the additional variables, along with a warning message. The warning message will show start/end/route/pt_mode for which an error occurred.
# example: with error
get_travel(token, sample,
"start_lat", "start_lon", "end_lat", "end_lon",
routes = c("cycle", "walk"))Lastly, it recommended for users working with large matrices to set
parallel = TRUE for more efficient computation.