o311_add_endpoint {r311}

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 that can be used for queries. o311_reset_endpoints restores the initial state 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

name

[character]

Name of an endpoint / city. This name can be arbitrary and only serves for identification in [o311_api].

root

[character]

Base URL of the endpoint for sending production-grade requests. The root URL commonly points to "georeport/v2/".

jurisdiction

[character]

Unique identifier of the jurisdiction. The jurisdiction is typically defined as the domain of the respective city website. It is optional as most endpoints only serve one jurisdiction.

key

[logical]

Is an API key mandatory?

pagination

[logical]

Are requests responses paginated?

limit

[integer]

If paginated, how many requests does one page contain?

json

[logical]

Are JSON responses supported? If FALSE, defaults to "XML" responses. See also o311_api.

dialect

[character]

open311 extension that the endpoint is built on. Common dialects include CitySDK, Connected Bits, SeeClickFix and Mark-a-Spot. Currently, this argument does nothing, but it could be used in the future to adjust response handling based on dialect.

...

List of key-value pairs where each pair is a filter. The key represents the column and the value the requested column value. All keys must be present in the column names of o311_endpoints().

Details

o311_endpoints() returns a static list defined in the package installation directory. This list contains a limited number of endpoints that were proven to work at the time of package development. It does not include newer/smaller/less known endpoints or test APIs. These can be manually added using o311_add_endpoint.

Value

For o311_endpoints, a dataframe containing all relevant information on an endpoint. For o311_add_endpoint, the new endpoint, invisibly. o311_reset_endpoints returns NULL invisibly. If the new endpoint is a duplicate, NULL is returned invisibly.

Note

This function uses R_user_dir to persistently store custom endpoints data between sessions. To set a different directory, you may use options("o311_user_dir"). To clean up, run o311_reset_endpoints() which deletes the package-specific user directory and defaults back to system.file("endpoints.json", package = "r311").

See Also

o311_api

Examples

# read default endpoints
o311_endpoints()

# get all endpoints powered by Connected Bits
o311_endpoints(dialect = "Connected Bits")

# add a new endpoint
o311_add_endpoint(name = "test", root = "test.org/georeport/v2")

# read new endpoints
o311_endpoints()

# reset endpoints back to default
o311_reset_endpoints()