| Title: | Call the Bus Open Data Service ('BODS') API Through R |
|---|---|
| Description: | A wrapper to allow users to download Bus Open Data Service 'BODS' transport information from the API (<https://www.bus-data.dft.gov.uk/>). This includes timetable and fare metadata (including links for full datasets), timetable data at line level, and real-time location data. |
| Authors: | Francesca Bryden [aut, cre] |
| Maintainer: | Francesca Bryden <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2025-02-14 05:12:10 UTC |
| Source: | https://github.com/cran/bodsr |
Search an xml file for a specific named node and count the number of instances
count_nodes(x, xpath)count_nodes(x, xpath)
x |
An xml object |
xpath |
string. The node name to search for within the xpath. |
Returns a numeric count value
Open data from a single line metadata table where it's zip or xml format
extract_line_level_data(file)extract_line_level_data(file)
file |
A single row of table metadata extracted using get_timetable_metadata() |
returns a dataframe of information extracted from the given xml or zip url
Search an xml file for a specific named mode and return the value(s) stored in it
find_node_value(x, xpath)find_node_value(x, xpath)
x |
An xml object |
xpath |
string. The node name to search for within the xpath. |
Returns a single string of values from the specified node
Return fares metadata from the 'BODS' API
get_fares_metadata( api_key = Sys.getenv("BODS_KEY"), limit = 25, noc = NULL, status = NULL, bounding_box = NULL )get_fares_metadata( api_key = Sys.getenv("BODS_KEY"), limit = 25, noc = NULL, status = NULL, bounding_box = NULL )
api_key |
API key for the 'BODS' dataset passed as a string. Can be obtained from the 'BODS' API login |
limit |
integer. Maximum number of records to return for a query. Defaults to 25 |
noc |
string or vector of strings. Limit results to fares data sets for specified National Operator Codes. A full lookup of NOC to bus operator names can be seen using noc_lookup(). Defaults to NULL. |
status |
string. Limit results to fares data sets for specified status, accepted values are "published" or "inactive". Defaults to NULL. |
bounding_box |
vector of four numerics. Limit results to fares data sets that contain information for the area within the rectangular boundingBox you set using co-ordinates [minLatitude, maxLatitude, minLongitude, maxLongitude]. Defaults to NULL. |
Returns a data frame of fares metadata including links to data from the 'BODS' API.
## Not run: #Before running these examples, ensure you have an API key saved #Return the first 25 results of fares metadata with no filters get_fares_metadata() #Return fares metadata for National Express get_fares_metadata(noc = "NATX") #Return only published fares metadata for Go Ahead get_fares_metadata(noc = "BHBC", status = "published") #Return fares metadata for the specified bounding box get_fares_metadata(bounding_box = c(51.401, 51.509, 0.01, 0.201)) ## End(Not run)## Not run: #Before running these examples, ensure you have an API key saved #Return the first 25 results of fares metadata with no filters get_fares_metadata() #Return fares metadata for National Express get_fares_metadata(noc = "NATX") #Return only published fares metadata for Go Ahead get_fares_metadata(noc = "BHBC", status = "published") #Return fares metadata for the specified bounding box get_fares_metadata(bounding_box = c(51.401, 51.509, 0.01, 0.201)) ## End(Not run)
Return GTFS-RT location data from the 'BODS' API
get_location_gtfs( api_key = Sys.getenv("BODS_KEY"), bounding_box = NULL, route_id = NULL, start_time_after = NULL, start_time_before = NULL )get_location_gtfs( api_key = Sys.getenv("BODS_KEY"), bounding_box = NULL, route_id = NULL, start_time_after = NULL, start_time_before = NULL )
api_key |
API key for the 'BODS' dataset passed as a string. Can be obtained from the 'BODS' API login |
bounding_box |
vector of four numerics. Limit results to location data for vehicles within the rectangular boundingBox you set using co-ordinates [minLatitude, maxLatitude, minLongitude, maxLongitude]. Defaults to NULL. |
route_id |
string or vector of strings. Limit results to bus location data with the specified routeId. Defaults to NULL. |
start_time_after |
integer. Limit results to bus location data with a start time after the specified Unix timestamp. Defaults to NULL. |
start_time_before |
integer. Limit results to bus location data with a start time before the specified Unix timestamp. Defaults to NULL. |
Returns bus location data in GTFS-RT format. More detail on this format can be found the 'BODS' data formats documentation
## Not run: #Before running these examples, ensure you have an API key saved #Return data for specified route ID get_location_gtfs(route_id = "45") #Return data within a specified bounding box get_location_gtfs(bounding_box = c(51.401, 51.509, 0.01, 0.201)) ## End(Not run)## Not run: #Before running these examples, ensure you have an API key saved #Return data for specified route ID get_location_gtfs(route_id = "45") #Return data within a specified bounding box get_location_gtfs(bounding_box = c(51.401, 51.509, 0.01, 0.201)) ## End(Not run)
Return XML vehicle location data from the 'BODS' API
get_location_xml( api_key = Sys.getenv("BODS_KEY"), bounding_box = NULL, noc = NULL, vehicle_ref = NULL, line_ref = NULL, producer_ref = NULL, origin_ref = NULL, destination_ref = NULL )get_location_xml( api_key = Sys.getenv("BODS_KEY"), bounding_box = NULL, noc = NULL, vehicle_ref = NULL, line_ref = NULL, producer_ref = NULL, origin_ref = NULL, destination_ref = NULL )
api_key |
API key for the 'BODS' dataset passed as a string. Can be obtained from the 'BODS' API login |
bounding_box |
vector of four numerics. Limit results to location data for vehicles within the rectangular boundingBox you set using co-ordinates [minLatitude, maxLatitude, minLongitude, maxLongitude]. Defaults to NULL. |
noc |
string or vector of strings. Limit results to fares data sets for specified National Operator Codes. A full lookup of NOC to bus operator names can be seen using noc_lookup(). Defaults to NULL. |
vehicle_ref |
string. Limit results to bus location data with the specified vehicle_ref. This is a unique reference for the vehicle that is consistent and is generated by the vehicle equipment. Defaults to NULL. |
line_ref |
string. Limit results to bus location data with the specified line_ref. Defaults to NULL. |
producer_ref |
string. Limit results to bus location data with the specified producer_ref. Defaults to NULL. |
origin_ref |
string. Limit results to bus location data with the specified origin reference. Accepts any National Public Transport Access Nodes (NaPTAN) value, which can be found the NaPTAN access nodes dataset. Defaults to NULL. |
destination_ref |
string. Limit results to bus location data with the specified destination reference. Accepts any National Public Transport Access Nodes (NaPTAN) value, which can be found the NaPTAN access nodes dataset. Defaults to NULL. |
Returns bus location data in XML SIRI-VM format. More detail on this format can be found the 'BODS' data formats documentation
## Not run: #Before running these examples, ensure you have an API key saved ##Return unfiltered data from XML API get_location_xml() #Return data for vehicle reference "BUSC" only get_location_xml(vehicle_ref = "BUSC") #Return data for specified origin get_location_xml(origin_ref = "21024515") ## End(Not run)## Not run: #Before running these examples, ensure you have an API key saved ##Return unfiltered data from XML API get_location_xml() #Return data for vehicle reference "BUSC" only get_location_xml(vehicle_ref = "BUSC") #Return data for specified origin get_location_xml(origin_ref = "21024515") ## End(Not run)
Extract line-level timetable data from all rows of the provided metadata table
get_timetable_data(timetable_metadata)get_timetable_data(timetable_metadata)
timetable_metadata |
A single row of table metadata extracted using get_timetable_metadata() |
returns list of timetable dataframes, with each dataframe corresponding to a row on the provided timetable metadata
## Not run: #Before running these examples, ensure you have an API key saved #Return the first 5 results of timetable metadata with no filters metadata <- get_timetable_metadata(limit = 5) ## End(Not run)## Not run: #Before running these examples, ensure you have an API key saved #Return the first 5 results of timetable metadata with no filters metadata <- get_timetable_metadata(limit = 5) ## End(Not run)
Return timetable metadata from the 'BODS' API
get_timetable_metadata( api_key = Sys.getenv("BODS_KEY"), limit = 25, search = NULL, noc = NULL, admin_area = NULL, status = NULL, end_date_start = NULL, end_date_end = NULL, modified_date = NULL, start_date_start = NULL, start_date_end = NULL, dq_rag = NULL, bods_compliance = NULL )get_timetable_metadata( api_key = Sys.getenv("BODS_KEY"), limit = 25, search = NULL, noc = NULL, admin_area = NULL, status = NULL, end_date_start = NULL, end_date_end = NULL, modified_date = NULL, start_date_start = NULL, start_date_end = NULL, dq_rag = NULL, bods_compliance = NULL )
api_key |
API key for the 'BODS' dataset passed as a string. Can be obtained from the BODS API login |
limit |
integer. Maximum number of records to return for a query. Defaults to 25 |
search |
string to search records on; can be a value or partial value to match the data set name, data set description, organisation name, or admin area name. Defaults to NULL. |
noc |
string or vector of strings. Limit results to fares data sets for specified National Operator Codes. A full lookup of NOC to bus operator names can be seen using noc_lookup(). Defaults to NULL. |
admin_area |
string or vector of strings. Limit results to datasets with services that stop within the specified area(s). 'ATCO' Area Codes are as specified in the NPTG area codes Defaults to NULL. |
status |
string. Limit results to data sets with the specified status, accepted values are "published" or "inactive". Defaults to NULL. |
end_date_start |
datetime. Limit results to data sets with services with end dates after this date. Defaults to NULL. |
end_date_end |
datetime. Limit results to data sets with services with end dates before this date. Defaults to NULL. |
modified_date |
datetime. Limit results to data sets that have been created or updated since the specified date. Defaults to NULL. |
start_date_start |
datetime. Limit results to data sets with services with start dates after this date. Defaults to NULL. |
start_date_end |
datetime. Limit results to data sets with services with start dates before this date. Defaults to NULL. |
dq_rag |
string. Limit results to data sets with the specified RAG status. Accepted options are "red", "amber" and "green". Defaults to NULL. |
bods_compliance |
logical. Limit results to datasets with the specified BODS compliance status. Defaults to NULL. |
Returns a data frame of timetable metadata including links to data from the 'BODS' API.
## Not run: #Before running these examples, ensure you have an API key saved #Return the first 25 results of timetable metadata with no filters get_timetable_metadata() #Return timetable metadata for National Express get_timetable_metadata(noc = "NATX") #Return only published timetable metadata for Go Ahead with a green RAG status get_timetable_metadata(noc = "BHBC", status = "published", dq_rag = "green") #Return timetable metadata for the Devon admin area and search string get_timetable_metadata(admin_area = "110", search = "Plymouth Citybus") ## End(Not run)## Not run: #Before running these examples, ensure you have an API key saved #Return the first 25 results of timetable metadata with no filters get_timetable_metadata() #Return timetable metadata for National Express get_timetable_metadata(noc = "NATX") #Return only published timetable metadata for Go Ahead with a green RAG status get_timetable_metadata(noc = "BHBC", status = "published", dq_rag = "green") #Return timetable metadata for the Devon admin area and search string get_timetable_metadata(admin_area = "110", search = "Plymouth Citybus") ## End(Not run)
Pull a table of relevant values from specified nodes in the xml
line_level_xml(x, count = 1, total_count = 1)line_level_xml(x, count = 1, total_count = 1)
x |
An xml object |
count |
numeric. Where the xml file is taken from a zip collection, the number file it is. Defaults to 1. |
total_count |
numeric. Where the xml file is taken from a zip collection, the total number of files in the zip. Defaults to 1. |
Returns a table of values extracted from specified nodes of an xml document
Lookup between operator names and national operator code ('NOC') lookup
noc_lookup()noc_lookup()
Returns a data frame of operator names and their corresponding national operator code from the 'BODS' API.
##Check operator name lookup ## Not run: noc_lookup() ## End(Not run)##Check operator name lookup ## Not run: noc_lookup() ## End(Not run)
Join together a value and an associated API string if the value is not NULL
not_null(obj, string)not_null(obj, string)
obj |
R object to check whether it is NULL or not |
string |
API string to append to R object |
Join together a date value and an associated API string if the value is not NULL
not_null_date(date, string)not_null_date(date, string)
date |
R object to check whether it is NULL or not |
string |
API string to append to R object |
Open every xml file within a zip object and extract data of interest from it using a given function
open_all_xml(url, fun)open_all_xml(url, fun)
url |
A url pointing towards a zip object |
fun |
name of a data extracting function to apply to the zip folder |
returns a dataframe of information extracted from xml documents
Try to read an xml file using read_xml; where this fails, quietly return a NULL value
poss_xml(...)poss_xml(...)
... |
arguments to pass to the read_xml function |
Count the number of xml files included within a provided metadata dataframe, whether the provided file links are xml or zip
xml_file_counter(timetable_metadata)xml_file_counter(timetable_metadata)
timetable_metadata |
A table of metadata extracted using get_timetable_metadata() |
returns a numeric vector of number of xml files by row of the provided metadata