Movatterモバイル変換

Endpoints

Description

Modify and examine defined open311 endpoints.o311_endpoints()retrieves a list of endpoints including additional information.o311_add_endpoint adds to this list to define a new endpoint thatcan be used for queries.o311_reset_endpoints restores the initialstate of the endpoints list.

Usage

o311_add_endpoint(  name,  root,  jurisdiction = NULL,  key = FALSE,  pagination = FALSE,  limit = NULL,  json = TRUE,  dialect = NULL)o311_reset_endpoints()o311_endpoints(...)

Arguments

Details

o311_endpoints() returns a static list defined in the packageinstallation directory. This list contains a limited number of endpointsthat were proven to work at the time of package development. It does notinclude newer/smaller/less known endpoints or test APIs. These can bemanually added usingo311_add_endpoint.

Value

Foro311_endpoints, a dataframe containing all relevantinformation on an endpoint. Foro311_add_endpoint, the new endpoint,invisibly.o311_reset_endpoints returnsNULL invisibly.If the new endpoint is a duplicate,NULL is returned invisibly.

Note

This function usesR_user_dir to persistently storecustom endpoints data between sessions. To set a different directory, youmay useoptions("o311_user_dir"). To clean up, runo311_reset_endpoints() which deletes the package-specific userdirectory and defaults back tosystem.file("endpoints.json", package = "r311").

See Also

o311_api

Examples

# read default endpointso311_endpoints()# get all endpoints powered by Connected Bitso311_endpoints(dialect = "Connected Bits")# add a new endpointo311_add_endpoint(name = "test", root = "test.org/georeport/v2")# read new endpointso311_endpoints()# reset endpoints back to defaulto311_reset_endpoints()

Select an open311 API

Description

Select an open311 API and attach it to the active session. An open311 API isan implementation of the open311 standard. It consists of an endpoint name(e.g. a city), a root URL, and a jurisdiction ID. To unambiguously identifyan API, you can provide an endpoint, a jurisdiction ID, or both. The inputis matched witho311_endpoints to select an API. Theselected API is available to othero311_* functions until thesession is terminated or until it is overwritten.

Usage

o311_api(  endpoint = NULL,  jurisdiction = NULL,  key = NULL,  format = c("json", "xml"))

Arguments

Details

In theory, several jurisdictions can exist for a single endpoints, e.g.if a region serves multiple jurisdictions. Similarly, multiple endpointscan exist for a single jurisdiction, e.g. if a provider has set up bothproduction and test endpoints for a jurisdictions. Providing bothendpoint and jurisdiction is thus the most safe way to identify an API.

By default, only a handful of endpoints are supported. For a list ofcurrently supported endpoints, runo311_endpoints. You canadd non-default endpoints usingo311_add_endpoint.

Value

A list containing the most important information on a givenjurisdiction, invisibly. This list is attached to the session and canbe retrieved by callingo311_api() without arguments. Passing noarguments returns the currently attached API object.

See Also

o311_requests,o311_request,o311_services

Examples

# cities are matched using regexo311_api("Cologne")# passing a jurisdiction is more explicito311_api(jurisdiction = "stadt-koeln.de")# calls without arguments return the current APIo311_api()

API discovery

Description

Retrieve discovery information about the mounted endpoint.

Usage

o311_discovery()

Value

A list containing details on the given open311 API.

Examples

o311_api("zurich")if (o311_ok()) {  o311_discovery()}

Is open311 API ok?

Description

Checks whether an open311 API mounted byo311_api is reachableand returns a valid requests response.

Usage

o311_ok(error = FALSE)

Arguments

Value

A logical describing whether the API is reachable or not.Iferror = TRUE, returns the corresponding error object if oneoccurs.

Examples

# check if Bonn API is reachableo311_api("Bonn")o311_ok()# check if Helsinki API is reachable - failso311_add_endpoint(  name = "Helsinki",  root = "asiointi.hel.fi/palautews/rest/v1/")o311_api("Helsinki")o311_ok()# return error messagetry(o311_ok(error = TRUE))# reset endpoints databaseo311_reset_endpoints()

Query an open311 endpoint

Description

Low-level function to perform a generic request to the API currentlyattached byo311_api. Some open311 implementations supportunique operations that are not included in the official documentation.This function can be used to access these URL paths.

Usage

o311_query(path, ..., simplify = TRUE)

Arguments

Details

You can setoptions(r311_echo = TRUE) to display all requests sentusingo311_query.

Value

The parsed query output, either as a list or dataframe.

Examples

o311_api("rostock")# manually query discoveryo311_query(path = "discovery", simplify = FALSE)# query a custom path defined by the Klarschiff APIo311_query(path = "areas")

Get civic service request data

Description

Get civic service request data from a registered open311 endpoint.o311_request queries a single service request by ID.o311_requests queries a single page of service requests.o311_request_all tries to iterate through all pages of an endpointto return a complete dataset of service requests.

Usage

o311_requests(  service_code = NULL,  start_date = NULL,  end_date = NULL,  status = NULL,  page = NULL,  ...)o311_request(service_request_id, ...)o311_request_all(  service_code = NULL,  start_date = NULL,  end_date = NULL,  status = NULL,  ...,  max_pages = Inf,  progress = TRUE)

Arguments

Details

o311_request_all applies a number of checks to determine when tostop searching. First, many endpoints return an error if the last pageis exceeded. Thus, if the last page request failed, break.Second, if exceeding the pagination limit does not return an error, theresponse is compared with the previous response. If identical, theresponse is discarded and all previous responses returned. Finally,if the page exceedsmax_pages, the responses up to this point arereturned.

open311 leaves space for endpoints to implement their own requestparameters. These parameters can be provided using dot arguments.These arguments are not validated or pre-processed. Date-time objectsmust be formatted according to thew3c standard.Some more common parameters include:

• q: Perform a text search across all requests.

• update_after/updated_before: Limit request accordingto request update dates.

• per_page: Specifiy the maximum number of requests per page.

• extensions: Adds a nested attribute"extended_attributes" to the response.

• long/lat/radius: Searches for requests in a fixed radiusaround a coordinate.

As dot arguments deviate from the open311 standard, they are not guaranteedto be available for every endpoint and might be removed without furthernotice. Refer to the endpoint docs to learn more about custom parameters(o311_endpoints()$docs).

Value

A dataframe containing data on civic service requests. Thedataframe can contain varying columns depending on the open311implementation.

See Also

o311_api

Examples

o311_api("zurich")if (o311_ok()) {  # retrieve requests from the last two days  now <- Sys.time()  two_days <- 60 * 60 * 24 * 2  o311_requests(end_date = now, start_date = now - two_days)  # retrieve only open tickets  tickets <- o311_requests(status = "open")  # request the first ticket of the previous response  rid <- as.character(tickets$service_request_id[1])  o311_request(rid)  if (interactive()) {    # request all data    o311_request_all()  }  # request data of the first 5 pages  o311_request_all(max_pages = 5)}

Get service list

Description

Get a list of available services. Services are unique to the endpoint / cityand thus require an attached jurisdiction usingo311_api.

Usage

o311_services(...)o311_service(service_code, ...)

Arguments

Value

A dataframe or list containing information about each service.

Examples

# set up a jurisdictiono311_api("san francisco")if (o311_ok()) {  # get a list of all services  services <- o311_services()  # inspect a service code  o311_service(services$service_code[1])}

Validate endpoints

Description

Checks whether and which endpoints are correctly defined, reachable,and/or valid. Iterates through all endpoints defined ino311_endpoints and returns their status along with areason, if applicable.

Usage

validate_endpoints(  idx = NULL,  checks = c("discovery", "services", "requests"),  methods = c("formal", "down", "valid"))

Arguments

Value

A dataframe containing the name of the endpoint, one to threecolumns on check results, and one to three columns on reasons if a checkturned out to be negative.

Examples

# check the first three endpoints in o311_endpoints()validate_endpoints(1:3)# check only requestsvalidate_endpoints(1:3, checks = "requests")# check only whether an endpoint is downvalidate_endpoints(1:3, methods = "down")