--- title: "Output options" subtitle: "Get different kinds of output from OpenCage" author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon" date: "2021-02-18" description: > "`oc_forward()`/`oc_reverse()` return lists of various type, namely data frames, JSON, GeoJSON or URLs, depending on the `return` value you specify. The possible `return` values are `df_list`, `json_list`, `geojson_list` and `url_only`." output: rmarkdown::html_vignette: df_print: kable vignette: > %\VignetteIndexEntry{Output options} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- {opencage} contains two main types of main functions distinguished by the manner in which the results are returned: 1. The `oc_forward_df()`/`oc_reverse_df()` functions always return a single tibble. 2. The `oc_forward()`/`oc_reverse()` functions return a list of various types, depending on the `return` value you specify. The possible `return` values are `df_list`, `json_list`, `geojson_list` and `url_only`. Use of the `oc_forward_df()`/`oc_reverse_df()` functions is demonstrated in the "Introduction to opencage" and the "Customise your query" vignettes (`vignette("opencage")` and `vignette("customise_query")`, respectively) . The function arguments mentioned in these other vignettes are also generally available with `oc_forward()`/`oc_reverse()`. Here we will show the different return values available with `oc_forward()`/`oc_reverse()`. ## `df_list` The default return value is `df_list`. It returns a list of tibbles. ```r stations <- c("Casey Station", "McMurdo Station") oc_forward(stations, return = "df_list") #> [[1]] #> # A tibble: 2 x 18 #> oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_category oc_type oc_continent oc_hamlet #> #> 1 9 Casey Stati~ -66.3 111. -66.3 111. commerce office Antarctica Casey St~ #> 2 9 Casey Stati~ NA NA NA NA travel/tou~ point_~ Antarctica #> # ... with 8 more variables: oc_office , oc_iso_3166_1_alpha_2 , oc_iso_3166_1_alpha_3 , oc_country , #> # oc_country_code , oc_point_of_interest , oc_lat , oc_lng #> #> [[2]] #> # A tibble: 1 x 12 #> oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_category oc_type oc_continent oc_town #> #> 1 7 McMurdo Sta~ -77.8 167. -77.9 167. place city Antarctica McMurd~ #> # ... with 2 more variables: oc_lat , oc_lng ``` The `df_list` type drives the `oc_forward_df()`/`oc_reverse_df()` functions. You can use the `df_list` output in a `dplyr::mutate()` chain to replicate the functionality of `oc_forward_df()`: ```r library(dplyr, warn.conflicts = FALSE) oc_data <- tibble(place = stations) %>% mutate(oc_result = oc_forward(place)) oc_data #> # A tibble: 2 x 2 #> place oc_result #> #> 1 Casey Station #> 2 McMurdo Station ``` This creates a list column `oc_result`, which can be easily unnested with `tidyr::unnest()`: ```r library(tidyr, warn.conflicts = FALSE) oc_data %>% unnest(oc_result) #> # A tibble: 3 x 20 #> place oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_category oc_type oc_continent #> #> 1 Case~ 9 Casey Stati~ -66.3 111. -66.3 111. commerce office Antarctica #> 2 Case~ 9 Casey Stati~ NA NA NA NA travel/tou~ point_~ Antarctica #> 3 McMu~ 7 McMurdo Sta~ -77.8 167. -77.9 167. place city Antarctica #> # ... with 10 more variables: oc_hamlet , oc_office , oc_iso_3166_1_alpha_2 , oc_iso_3166_1_alpha_3 , #> # oc_country , oc_country_code , oc_point_of_interest , oc_lat , oc_lng , oc_town ``` ## `json_list` OpenCage's main output format is JSON. When you specify `json_list` as the return type, you get the JSON as an R `list()`. ```r oc_forward("Casey Station", return = "json_list") #> [[1]] #> [[1]]$documentation #> [1] "https://opencagedata.com/api" #> #> [[1]]$licenses #> [[1]]$licenses[[1]] #> [[1]]$licenses[[1]]$name #> [1] "see attribution guide" #> #> [[1]]$licenses[[1]]$url #> [1] "https://opencagedata.com/credits" #> #> #> #> [[1]]$results #> [[1]]$results[[1]] #> [[1]]$results[[1]]$bounds #> [[1]]$results[[1]]$bounds$northeast #> [[1]]$results[[1]]$bounds$northeast$lat #> [1] -66.28255 #> #> [[1]]$results[[1]]$bounds$northeast$lng #> [1] 110.5267 #> #> #> [[1]]$results[[1]]$bounds$southwest #> [[1]]$results[[1]]$bounds$southwest$lat #> [1] -66.28265 #> #> [[1]]$results[[1]]$bounds$southwest$lng #> [1] 110.5266 #> #> #> #> [[1]]$results[[1]]$components #> [[1]]$results[[1]]$components$`_category` #> [1] "commerce" #> #> [[1]]$results[[1]]$components$`_type` #> [1] "office" #> #> [[1]]$results[[1]]$components$continent #> [1] "Antarctica" #> #> [[1]]$results[[1]]$components$hamlet #> [1] "Casey Station" #> #> [[1]]$results[[1]]$components$office #> [1] "Casey Station" #> #> #> [[1]]$results[[1]]$confidence #> [1] 9 #> #> [[1]]$results[[1]]$formatted #> [1] "Casey Station" #> #> [[1]]$results[[1]]$geometry #> [[1]]$results[[1]]$geometry$lat #> [1] -66.2826 #> #> [[1]]$results[[1]]$geometry$lng #> [1] 110.5266 #> #> #> #> [[1]]$results[[2]] #> [[1]]$results[[2]]$components #> [[1]]$results[[2]]$components$`ISO_3166-1_alpha-2` #> [1] "AQ" #> #> [[1]]$results[[2]]$components$`ISO_3166-1_alpha-3` #> [1] "ATA" #> #> [[1]]$results[[2]]$components$`_category` #> [1] "travel/tourism" #> #> [[1]]$results[[2]]$components$`_type` #> [1] "point_of_interest" #> #> [[1]]$results[[2]]$components$continent #> [1] "Antarctica" #> #> [[1]]$results[[2]]$components$country #> [1] "Antarctica" #> #> [[1]]$results[[2]]$components$country_code #> [1] "aq" #> #> [[1]]$results[[2]]$components$point_of_interest #> [1] "Casey Station" #> #> #> [[1]]$results[[2]]$confidence #> [1] 9 #> #> [[1]]$results[[2]]$formatted #> [1] "Casey Station, Antarctica" #> #> [[1]]$results[[2]]$geometry #> [[1]]$results[[2]]$geometry$lat #> [1] -66.28225 #> #> [[1]]$results[[2]]$geometry$lng #> [1] 110.5278 #> #> #> #> #> [[1]]$status #> [[1]]$status$code #> [1] 200 #> #> [[1]]$status$message #> [1] "OK" #> #> #> [[1]]$stay_informed #> [[1]]$stay_informed$blog #> [1] "https://blog.opencagedata.com" #> #> [[1]]$stay_informed$twitter #> [1] "https://twitter.com/OpenCage" #> #> #> [[1]]$thanks #> [1] "For using an OpenCage API" #> #> [[1]]$timestamp #> [[1]]$timestamp$created_http #> [1] "Thu, 18 Feb 2021 19:02:13 GMT" #> #> [[1]]$timestamp$created_unix #> [1] 1613674933 #> #> #> [[1]]$total_results #> [1] 2 ``` ## `geojson_list` When you choose `geojson_list` as the return type, the geocoder response will be returned as GeoJSON specified as an R `list()`. ```r gjsn_lst <- oc_forward("Casey Station", return = "geojson_list") gjsn_lst #> [[1]] #> $documentation #> [1] "https://opencagedata.com/api" #> #> $features #> $features[[1]] #> $features[[1]]$geometry #> $features[[1]]$geometry$coordinates #> $features[[1]]$geometry$coordinates[[1]] #> [1] 110.5266 #> #> $features[[1]]$geometry$coordinates[[2]] #> [1] -66.2826 #> #> #> $features[[1]]$geometry$type #> [1] "Point" #> #> #> $features[[1]]$properties #> $features[[1]]$properties$bounds #> $features[[1]]$properties$bounds$northeast #> $features[[1]]$properties$bounds$northeast$lat #> [1] -66.28255 #> #> $features[[1]]$properties$bounds$northeast$lng #> [1] 110.5267 #> #> #> $features[[1]]$properties$bounds$southwest #> $features[[1]]$properties$bounds$southwest$lat #> [1] -66.28265 #> #> $features[[1]]$properties$bounds$southwest$lng #> [1] 110.5266 #> #> #> #> $features[[1]]$properties$components #> $features[[1]]$properties$components$`_category` #> [1] "commerce" #> #> $features[[1]]$properties$components$`_type` #> [1] "office" #> #> $features[[1]]$properties$components$continent #> [1] "Antarctica" #> #> $features[[1]]$properties$components$hamlet #> [1] "Casey Station" #> #> $features[[1]]$properties$components$office #> [1] "Casey Station" #> #> #> $features[[1]]$properties$confidence #> [1] 9 #> #> $features[[1]]$properties$formatted #> [1] "Casey Station" #> #> #> $features[[1]]$type #> [1] "Feature" #> #> #> $features[[2]] #> $features[[2]]$geometry #> $features[[2]]$geometry$coordinates #> $features[[2]]$geometry$coordinates[[1]] #> [1] 110.5278 #> #> $features[[2]]$geometry$coordinates[[2]] #> [1] -66.28225 #> #> #> $features[[2]]$geometry$type #> [1] "Point" #> #> #> $features[[2]]$properties #> $features[[2]]$properties$components #> $features[[2]]$properties$components$`ISO_3166-1_alpha-2` #> [1] "AQ" #> #> $features[[2]]$properties$components$`ISO_3166-1_alpha-3` #> [1] "ATA" #> #> $features[[2]]$properties$components$`_category` #> [1] "travel/tourism" #> #> $features[[2]]$properties$components$`_type` #> [1] "point_of_interest" #> #> $features[[2]]$properties$components$continent #> [1] "Antarctica" #> #> $features[[2]]$properties$components$country #> [1] "Antarctica" #> #> $features[[2]]$properties$components$country_code #> [1] "aq" #> #> $features[[2]]$properties$components$point_of_interest #> [1] "Casey Station" #> #> #> $features[[2]]$properties$confidence #> [1] 9 #> #> $features[[2]]$properties$formatted #> [1] "Casey Station, Antarctica" #> #> #> $features[[2]]$type #> [1] "Feature" #> #> #> #> $licenses #> $licenses[[1]] #> $licenses[[1]]$name #> [1] "see attribution guide" #> #> $licenses[[1]]$url #> [1] "https://opencagedata.com/credits" #> #> #> #> $rate #> named list() #> #> $status #> $status$code #> [1] 200 #> #> $status$message #> [1] "OK" #> #> #> $stay_informed #> $stay_informed$blog #> [1] "https://blog.opencagedata.com" #> #> $stay_informed$twitter #> [1] "https://twitter.com/OpenCage" #> #> #> $thanks #> [1] "For using an OpenCage API" #> #> $timestamp #> $timestamp$created_http #> [1] "Thu, 18 Feb 2021 19:02:15 GMT" #> #> $timestamp$created_unix #> [1] 1613674935 #> #> #> $total_results #> [1] 2 #> #> $type #> [1] "FeatureCollection" #> #> attr(,"class") #> [1] "geo_list" ``` In fact, {opencage} returns a list of results in `geo_list` format, which should be compatible with the {[geojsonio](https://docs.ropensci.org/geojsonio/)} package. ```r class(gjsn_lst[[1]]) #> [1] "geo_list" ``` ## `url_only` `url_only` returns the OpenCage URL for debugging purposes. ```r oc_forward("Casey Station", return = "url_only") #> [[1]] #> [1] "https://api.opencagedata.com/geocode/v1/json?q=Casey%20Station&limit=10&no_annotations=1&roadinfo=0&no_dedupe=0&no_record=1&abbrv=0&add_request=0&key=OPENCAGE_KEY" ``` Your OpenCage API key is masked with the `OPENCAGE_KEY` string, by default. If you really want {opencage} to display your API key with the URL, set the `show_key` argument in `oc_config()` to `TRUE`. ```r oc_config(show_key = TRUE) ``` Note that the API key will only be returned with the URL in `base::interactive()` mode. ## `xml` {opencage} does not support the XML response type at the moment. Please file an [issue](https://github.com/ropensci/opencage/issues) or a [pull-request](https://github.com/ropensci/opencage/pulls) if you have a use-case that requires this. ## Return query text `oc_forward()` and `oc_reverse()` have an `add_request` argument, indicating whether the request is returned again with the results. If the `return` value is a `df_list`, the `placename` or `latitude,longitude` is added as a column to the results without a roundtrip to the API. `json_list` results will contain all request parameters as returned by the API. This would normally include your OpenCage API key, but {opencage} masks the key and replaces it with the `OPENCAGE_KEY` string in the output. `add_request` is currently ignored by OpenCage for GeoJSON results.