---
title: "Output options"
subtitle: "Get different kinds of output from OpenCage"
author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon"
date: "2024-12-31"
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: 1 × 15
#>   oc_confidence oc_formatted    oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_iso_3166_1_alpha_2
#>           <int> <chr>                      <dbl>            <dbl>            <dbl>            <dbl> <chr>                
#> 1             7 Casey Station,…            -66.3             111.            -66.3             111. AQ                   
#> # ℹ 8 more variables: oc_category <chr>, oc_normalized_city <chr>, oc_type <chr>, oc_continent <chr>,
#> #   oc_country_code <chr>, oc_hamlet <chr>, oc_lat <dbl>, oc_lng <dbl>
#> 
#> [[2]]
#> # A tibble: 1 × 15
#>   oc_confidence oc_formatted    oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_iso_3166_1_alpha_2
#>           <int> <chr>                      <dbl>            <dbl>            <dbl>            <dbl> <chr>                
#> 1             7 McMurdo Statio…            -77.8             167.            -77.9             167. AQ                   
#> # ℹ 8 more variables: oc_category <chr>, oc_normalized_city <chr>, oc_type <chr>, oc_continent <chr>,
#> #   oc_country_code <chr>, oc_town <chr>, oc_lat <dbl>, oc_lng <dbl>
```

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 × 2
#>   place           oc_result        
#>   <chr>           <list>           
#> 1 Casey Station   <tibble [1 × 15]>
#> 2 McMurdo Station <tibble [1 × 15]>
```

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: 2 × 17
#>   place           oc_confidence oc_formatted          oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng
#>   <chr>                   <int> <chr>                            <dbl>            <dbl>            <dbl>            <dbl>
#> 1 Casey Station               7 Casey Station, Antar…            -66.3             111.            -66.3             111.
#> 2 McMurdo Station             7 McMurdo Station, Ant…            -77.8             167.            -77.9             167.
#> # ℹ 10 more variables: oc_iso_3166_1_alpha_2 <chr>, oc_category <chr>, oc_normalized_city <chr>, oc_type <chr>,
#> #   oc_continent <chr>, oc_country_code <chr>, oc_hamlet <chr>, oc_lat <dbl>, oc_lng <dbl>, oc_town <chr>
```

## `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.26209
#> 
#> [[1]]$results[[1]]$bounds$northeast$lng
#> [1] 110.5441
#> 
#> 
#> [[1]]$results[[1]]$bounds$southwest
#> [[1]]$results[[1]]$bounds$southwest$lat
#> [1] -66.30209
#> 
#> [[1]]$results[[1]]$bounds$southwest$lng
#> [1] 110.5041
#> 
#> 
#> 
#> [[1]]$results[[1]]$components
#> [[1]]$results[[1]]$components$`ISO_3166-1_alpha-2`
#> [1] "AQ"
#> 
#> [[1]]$results[[1]]$components$`_category`
#> [1] "place"
#> 
#> [[1]]$results[[1]]$components$`_normalized_city`
#> [1] "Casey Station"
#> 
#> [[1]]$results[[1]]$components$`_type`
#> [1] "hamlet"
#> 
#> [[1]]$results[[1]]$components$continent
#> [1] "Antarctica"
#> 
#> [[1]]$results[[1]]$components$country_code
#> [1] "aq"
#> 
#> [[1]]$results[[1]]$components$hamlet
#> [1] "Casey Station"
#> 
#> 
#> [[1]]$results[[1]]$confidence
#> [1] 7
#> 
#> [[1]]$results[[1]]$formatted
#> [1] "Casey Station, Antarctica"
#> 
#> [[1]]$results[[1]]$geometry
#> [[1]]$results[[1]]$geometry$lat
#> [1] -66.28209
#> 
#> [[1]]$results[[1]]$geometry$lng
#> [1] 110.5241
#> 
#> 
#> 
#> 
#> [[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$mastodon
#> [1] "https://en.osm.town/@opencage"
#> 
#> 
#> [[1]]$thanks
#> [1] "For using an OpenCage API"
#> 
#> [[1]]$timestamp
#> [[1]]$timestamp$created_http
#> [1] "Tue, 31 Dec 2024 10:46:25 GMT"
#> 
#> [[1]]$timestamp$created_unix
#> [1] 1735641985
#> 
#> 
#> [[1]]$total_results
#> [1] 1
```

## `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.5241
#> 
#> $features[[1]]$geometry$coordinates[[2]]
#> [1] -66.28209
#> 
#> 
#> $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.26209
#> 
#> $features[[1]]$properties$bounds$northeast$lng
#> [1] 110.5441
#> 
#> 
#> $features[[1]]$properties$bounds$southwest
#> $features[[1]]$properties$bounds$southwest$lat
#> [1] -66.30209
#> 
#> $features[[1]]$properties$bounds$southwest$lng
#> [1] 110.5041
#> 
#> 
#> 
#> $features[[1]]$properties$components
#> $features[[1]]$properties$components$`ISO_3166-1_alpha-2`
#> [1] "AQ"
#> 
#> $features[[1]]$properties$components$`_category`
#> [1] "place"
#> 
#> $features[[1]]$properties$components$`_normalized_city`
#> [1] "Casey Station"
#> 
#> $features[[1]]$properties$components$`_type`
#> [1] "hamlet"
#> 
#> $features[[1]]$properties$components$continent
#> [1] "Antarctica"
#> 
#> $features[[1]]$properties$components$country_code
#> [1] "aq"
#> 
#> $features[[1]]$properties$components$hamlet
#> [1] "Casey Station"
#> 
#> 
#> $features[[1]]$properties$confidence
#> [1] 7
#> 
#> $features[[1]]$properties$formatted
#> [1] "Casey Station, Antarctica"
#> 
#> 
#> $features[[1]]$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$mastodon
#> [1] "https://en.osm.town/@opencage"
#> 
#> 
#> $thanks
#> [1] "For using an OpenCage API"
#> 
#> $timestamp
#> $timestamp$created_http
#> [1] "Tue, 31 Dec 2024 10:46:28 GMT"
#> 
#> $timestamp$created_unix
#> [1] 1735641988
#> 
#> 
#> $total_results
#> [1] 1
#> 
#> $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&address_only=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.