Endpoints — o311_add_endpoint • r311

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().

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.

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.

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").

Examples

# read default endpoints
o311_endpoints()
#> # A tibble: 69 × 12
#>    name            root  docs  jurisdiction key   pagination limit json  dialect
#>    <chr>           <chr> <chr> <chr>        <lgl> <lgl>      <int> <lgl> <chr>  
#>  1 Annaberg-Buchh… http… http… annberg-buc… FALSE TRUE          50 TRUE  Mark-a…
#>  2 Bloomington, IN http… NA    bloomington… FALSE TRUE        1000 TRUE  uReport
#>  3 Bonn, DE        http… http… bonn.de      FALSE TRUE         100 TRUE  Mark-a…
#>  4 Boston, MA      http… http… NA           FALSE TRUE          50 TRUE  Connec…
#>  5 Brookline, MA   http… http… brooklinema… FALSE TRUE          50 TRUE  Connec…
#>  6 Austin, TX      http… http… NA           FALSE TRUE          50 TRUE  Connec…
#>  7 Chicago, IL     311a… 311a… cityofchica… FALSE TRUE          50 TRUE  Connec…
#>  8 Newport News, … http… http… cityofnewpo… FALSE TRUE          50 TRUE  Connec…
#>  9 San Diego, CA   http… http… sandiego.gov FALSE TRUE          50 TRUE  Connec…
#> 10 Köln / Cologne… http… NA    stadt-koeln… FALSE TRUE          50 TRUE  Mark-a…
#> # ℹ 59 more rows
#> # ℹ 3 more variables: deprecated <lgl>, deprecated_reason <chr>,
#> #   deprecated_url <chr>

# get all endpoints powered by Connected Bits
o311_endpoints(dialect = "Connected Bits")
#> # A tibble: 7 × 12
#>   name  root  docs  jurisdiction key   pagination limit json  dialect deprecated
#>   <chr> <chr> <chr> <chr>        <lgl> <lgl>      <int> <lgl> <chr>   <lgl>     
#> 1 Bost… http… http… NA           FALSE TRUE          50 TRUE  Connec… FALSE     
#> 2 Broo… http… http… brooklinema… FALSE TRUE          50 TRUE  Connec… FALSE     
#> 3 Aust… http… http… NA           FALSE TRUE          50 TRUE  Connec… FALSE     
#> 4 Chic… 311a… 311a… cityofchica… FALSE TRUE          50 TRUE  Connec… FALSE     
#> 5 Newp… http… http… cityofnewpo… FALSE TRUE          50 TRUE  Connec… FALSE     
#> 6 San … http… http… sandiego.gov FALSE TRUE          50 TRUE  Connec… FALSE     
#> 7 San … http… http… NA           FALSE TRUE          50 TRUE  Connec… FALSE     
#> # ℹ 2 more variables: deprecated_reason <chr>, deprecated_url <chr>

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

# read new endpoints
o311_endpoints()
#> # A tibble: 70 × 12
#>    name            root  docs  jurisdiction key   pagination limit json  dialect
#>    <chr>           <chr> <chr> <chr>        <lgl> <lgl>      <int> <lgl> <chr>  
#>  1 Annaberg-Buchh… http… http… annberg-buc… FALSE TRUE          50 TRUE  Mark-a…
#>  2 Bloomington, IN http… NA    bloomington… FALSE TRUE        1000 TRUE  uReport
#>  3 Bonn, DE        http… http… bonn.de      FALSE TRUE         100 TRUE  Mark-a…
#>  4 Boston, MA      http… http… NA           FALSE TRUE          50 TRUE  Connec…
#>  5 Brookline, MA   http… http… brooklinema… FALSE TRUE          50 TRUE  Connec…
#>  6 Austin, TX      http… http… NA           FALSE TRUE          50 TRUE  Connec…
#>  7 Chicago, IL     311a… 311a… cityofchica… FALSE TRUE          50 TRUE  Connec…
#>  8 Newport News, … http… http… cityofnewpo… FALSE TRUE          50 TRUE  Connec…
#>  9 San Diego, CA   http… http… sandiego.gov FALSE TRUE          50 TRUE  Connec…
#> 10 Köln / Cologne… http… NA    stadt-koeln… FALSE TRUE          50 TRUE  Mark-a…
#> # ℹ 60 more rows
#> # ℹ 3 more variables: deprecated <lgl>, deprecated_reason <chr>,
#> #   deprecated_url <chr>

# reset endpoints back to default
o311_reset_endpoints()