Output options

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Output options

Get different kinds of output from OpenCage

{opencage} contains two main types of main functions distinguished by the manner in which the results are returned:

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.

stations <- c("Casey Station", "McMurdo Station")
oc_forward(stations, return = "df_list")
#> [[1]]
#> # A tibble: 1 × 17
#>   oc_confidence oc_formatted              oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_iso_3166_1_alpha_2 oc_iso_3166_1_alpha_3 oc_category oc_normalized_city oc_type oc_continent oc_country_code oc_hamlet     oc_postcode oc_lat oc_lng
#>           <int> <chr>                                <dbl>            <dbl>            <dbl>            <dbl> <chr>                 <chr>                 <chr>       <chr>              <chr>   <chr>        <chr>           <chr>         <chr>        <dbl>  <dbl>
#> 1             7 Casey Station, Antarctica            -66.3             111.            -66.3             111. AQ                    ATA                   place       Casey Station      hamlet  Antarctica   aq              Casey Station 7151         -66.3   111.
#> 
#> [[2]]
#> # A tibble: 1 × 16
#>   oc_confidence oc_formatted                oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_iso_3166_1_alpha_2 oc_iso_3166_1_alpha_3 oc_category oc_normalized_city oc_type oc_continent oc_country_code oc_town         oc_lat oc_lng
#>           <int> <chr>                                  <dbl>            <dbl>            <dbl>            <dbl> <chr>                 <chr>                 <chr>       <chr>              <chr>   <chr>        <chr>           <chr>            <dbl>  <dbl>
#> 1             7 McMurdo Station, Antarctica            -77.8             167.            -77.9             167. AQ                    ATA                   place       McMurdo Station    city    Antarctica   aq              McMurdo Station  -77.8   167.

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

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 × 17]>
#> 2 McMurdo Station <tibble [1 × 16]>

This creates a list column oc_result, which can be easily unnested with tidyr::unnest():

library(tidyr, warn.conflicts = FALSE)

oc_data %>% unnest(oc_result)
#> # A tibble: 2 × 19
#>   place           oc_confidence oc_formatted             oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_iso_3166_1_alpha_2 oc_iso_3166_1_alpha_3 oc_category oc_normalized_city oc_type oc_continent oc_country_code oc_hamlet oc_postcode oc_lat oc_lng oc_town
#>   <chr>                   <int> <chr>                               <dbl>            <dbl>            <dbl>            <dbl> <chr>                 <chr>                 <chr>       <chr>              <chr>   <chr>        <chr>           <chr>     <chr>        <dbl>  <dbl> <chr>  
#> 1 Casey Station               7 Casey Station, Antarcti…            -66.3             111.            -66.3             111. AQ                    ATA                   place       Casey Station      hamlet  Antarctica   aq              Casey St… 7151         -66.3   111. <NA>   
#> 2 McMurdo Station             7 McMurdo Station, Antarc…            -77.8             167.            -77.9             167. AQ                    ATA                   place       McMurdo Station    city    Antarctica   aq              <NA>      <NA>         -77.8   167. McMurd…

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

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$`ISO_3166-1_alpha-3`
#> [1] "ATA"
#> 
#> [[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]]$components$postcode
#> [1] "7151"
#> 
#> 
#> [[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] "Wed, 07 Oct 2026 21:01:07 GMT"
#> 
#> [[1]]$timestamp$created_unix
#> [1] 1791406867
#> 
#> 
#> [[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().

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$`ISO_3166-1_alpha-3`
#> [1] "ATA"
#> 
#> $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$components$postcode
#> [1] "7151"
#> 
#> 
#> $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] "Wed, 07 Oct 2026 21:01:10 GMT"
#> 
#> $timestamp$created_unix
#> [1] 1791406870
#> 
#> 
#> $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} package.

class(gjsn_lst[[1]])
#> [1] "geo_list"

`url_only`

url_only returns the OpenCage URL for debugging purposes.

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.

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 or a pull-request 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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.