Installation

Install the package with:

install.packages("opencage")

Or install the development version using devtools with:

library("devtools")
install_github("ropensci/opencage")

This package is an interface to the OpenCage API that allows forward and reverse geocoding. To use the package, you will need an API key. To get an API key for OpenCage geocoding, register at https://geocoder.opencagedata.com/pricing. The free API key provides up to 2,500 calls a day. For ease of use, save your API key as an environment variable as described at https://happygitwithr.com/github-pat.html#step-by-step.

Both functions of the package will conveniently look for your API key using Sys.getenv("OPENCAGE_KEY") so if your API key is an environment variable called “OPENCAGE_KEY” you don’t need to input it manually.

Geocoding

The OpenCage API supports forward and reverse geocoding. Sources of OpenCage are open geospatial data including OpenStreetMap, Yahoo! GeoPlanet, Natural Earth Data, Thematic Mapping, Ordnance Survey OpenSpace, Statistics New Zealand, Zillow, MaxMind, GeoNames, the US Census Bureau and Flickr’s shapefiles plus a whole lot more besides. See this page for the full list of credits.

Both forward and reverse geocoding typically return multiple results. Regarding these multiple results, the API doc states, “In cases where the geocoder is able to find multiple matches, the geocoder will return multiple results. The confidence or coordinates for each result should be examined to determine whether each result from an ambiguous query is sufficiently high to warrant using a result or not. A good strategy to reduce ambiguity is to use the optional bounds parameter described below to limit the area searched.” Multiple results might mean you get a result for the airport and a road when querying a city name, or results for cities with the same name in different countries.

Below are two simple examples.

Forward geocoding

Forward geocoding is from placename to latitude and longitude tuplet(s).

library("opencage")
output <- opencage_forward(placename = "Sarzeau")
print(output$time_stamp)
annotations.DMS.lat annotations.DMS.lng annotations.MGRS annotations.Maidenhead annotations.Mercator.x annotations.Mercator.y annotations.OSM.edit_url annotations.OSM.url annotations.callingcode annotations.currency.decimal_mark annotations.currency.html_entity annotations.currency.iso_code annotations.currency.iso_numeric annotations.currency.name annotations.currency.smallest_denomination annotations.currency.subunit annotations.currency.subunit_to_unit annotations.currency.symbol annotations.currency.symbol_first annotations.currency.thousands_separator annotations.flag annotations.geohash annotations.qibla annotations.sun.rise.apparent annotations.sun.rise.astronomical annotations.sun.rise.civil annotations.sun.rise.nautical annotations.sun.set.apparent annotations.sun.set.astronomical annotations.sun.set.civil annotations.sun.set.nautical annotations.timezone.name annotations.timezone.now_in_dst annotations.timezone.offset_sec annotations.timezone.offset_string annotations.timezone.short_name annotations.what3words.words annotations.wikidata bounds.northeast.lat bounds.northeast.lng bounds.southwest.lat bounds.southwest.lng components.ISO_3166-1_alpha-2 components.ISO_3166-1_alpha-3 components._type components.city components.country components.country_code components.county components.political_union components.postcode components.state confidence formatted geometry.lat geometry.lng components.post_office components.road components.suburb components.village query
47° 31’ 43.56984’’ N 2° 45’ 51.11892’’ W 30TWT1774963954 IN87om86hv -307709.303 5997281.031 https://www.openstreetmap.org/edit?relation=959447#map=17/47.52877/-2.76420 https://www.openstreetmap.org/?mlat=47.52877&mlon=-2.76420#map=17/47.52877/-2.76420 33 , EUR 978 Euro 1 Cent 100 1 . 🇫🇷 gbqn3h75jkz3413tdw1f 112.34 1549351920 1549345620 1549349940 1549347780 1549387140 1549393440 1549389060 1549391280 Europe/Paris 0 3600 100 CET gasp.jiggle.creamier Q128716 47.5666788 -2.6631197 47.4840815 -2.853616 FR FRA city Sarzeau France fr Vannes European Union 56370 Brittany 6 56370 Sarzeau, France 47.52877 -2.764200 NA NA NA NA Sarzeau
47° 31’ 40.75680’’ N 2° 46’ 7.87116’’ W 30TWT1739963866 IN87om76rr -308227.317 5997152.602 https://www.openstreetmap.org/edit?node=846574100#map=17/47.52799/-2.76885 https://www.openstreetmap.org/?mlat=47.52799&mlon=-2.76885#map=17/47.52799/-2.76885 33 , EUR 978 Euro 1 Cent 100 1 . 🇫🇷 gbqn2upy9517z9gpwc3y 112.34 1549351920 1549345620 1549349940 1549347780 1549387140 1549393440 1549389060 1549391280 Europe/Paris 0 3600 100 CET classics.catacomb.shop NA 47.528038 -2.7688031 47.527938 -2.7689031 FR FRA post_office NA France fr Vannes European Union 56370 Brittany 9 Sarzeau, Rue de la Poste, 56370 Sarzeau, France 47.52799 -2.768853 Sarzeau Rue de la Poste Kerjolis Sarzeau Sarzeau

Reverse geocoding

Reverse geocoding is from latitude and longitude to placename(s).

output2 <- opencage_reverse(latitude = 51.5034070, 
                            longitude = -0.1275920)
print(output2$time_stamp)
annotations.DMS.lat annotations.DMS.lng annotations.MGRS annotations.Maidenhead annotations.Mercator.x annotations.Mercator.y annotations.OSGB.easting annotations.OSGB.gridref annotations.OSGB.northing annotations.OSM.edit_url annotations.OSM.url annotations.callingcode annotations.currency.decimal_mark annotations.currency.html_entity annotations.currency.iso_code annotations.currency.iso_numeric annotations.currency.name annotations.currency.smallest_denomination annotations.currency.subunit annotations.currency.subunit_to_unit annotations.currency.symbol annotations.currency.symbol_first annotations.currency.thousands_separator annotations.flag annotations.geohash annotations.qibla annotations.sun.rise.apparent annotations.sun.rise.astronomical annotations.sun.rise.civil annotations.sun.rise.nautical annotations.sun.set.apparent annotations.sun.set.astronomical annotations.sun.set.civil annotations.sun.set.nautical annotations.timezone.name annotations.timezone.now_in_dst annotations.timezone.offset_sec annotations.timezone.offset_string annotations.timezone.short_name annotations.what3words.words annotations.wikidata bounds.northeast.lat bounds.northeast.lng bounds.southwest.lat bounds.southwest.lng components.ISO_3166-1_alpha-2 components.ISO_3166-1_alpha-3 components._type components.attraction components.city components.country components.country_code components.house_number components.neighbourhood components.political_union components.postcode components.road components.state components.state_district components.suburb confidence formatted geometry.lat geometry.lng query
51° 30’ 12.38472’’ N 0° 7’ 39.74952’’ E 30UXC9933909723 IO91wm40qt -14216.413 6677371.368 530044.646 TQ 300 799 179939.728 https://www.openstreetmap.org/edit?relation=1879842#map=17/51.50344/-0.12771 https://www.openstreetmap.org/?mlat=51.50344&mlon=-0.12771#map=17/51.50344/-0.12771 44 . £ GBP 826 British Pound 1 Penny 100 £ 1 , 🇬🇧 gcpuvpgj21ju5qmwdd59 118.98 1549351920 1549345080 1549349760 1549347420 1549385880 1549392720 1549387980 1549390380 Europe/London 0 0 0 GMT onions.toned.active Q169101 51.5036483 -0.1273038 51.5032573 -0.1278356 GB GBR attraction Prime Minister’s Office London United Kingdom gb 10 St. James’s European Union SW1A 2AA Downing Street England Greater London Covent Garden 9 Prime Minister’s Office, 10 Downing Street, London SW1A 2AA, United Kingdom 51.50344 -0.1277082 51.503407,-0.127592

Output

For both opencage_forward and opencage_reverse functions, the package returns a list with a time stamp for the query, the total number of results, a data.frame (dplyr tbl_df) with information about the remaining calls to the API unless you have an unlimited account, and a data.frame (dplyr tbl_df) with the results corresponding to your query. You can find longitude and latitude for each results as geometry.lat and geometry.lng. Other information includes country and country information, time of sunset and sunrise, geohash (a geocoding system identifying a point with a single string, as explained in many more details here and here; for pure conversion between longitude/latitude and geohashes, see this package). Depending on the data available in the API for the results one gets different columns; there can be a lot to explore!

Parameters

Optional parameters of both opencage_forward and opencage_reverse can make the query more precise:

  • bounds: Provides the geocoder with a hint to the region that the query resides in. This value will restrict the possible results to the supplied region. The bounds parameter should be specified as 4 coordinate points forming the south-west and north-east corners of a bounding box. For example, bounds = c(-0.563160, 51.280430, 0.278970, 51.683979) (min long, min lat, max long, max lat).

Below is an example of the use of bounds where the rectangle given in the second call does not include Europe so that we don’t get results for Berlin in Germany.

annotations.DMS.lat annotations.DMS.lng annotations.MGRS annotations.Maidenhead annotations.Mercator.x annotations.Mercator.y annotations.OSM.edit_url annotations.OSM.url annotations.callingcode annotations.currency.decimal_mark annotations.currency.html_entity annotations.currency.iso_code annotations.currency.iso_numeric annotations.currency.name annotations.currency.smallest_denomination annotations.currency.subunit annotations.currency.subunit_to_unit annotations.currency.symbol annotations.currency.symbol_first annotations.currency.thousands_separator annotations.flag annotations.geohash annotations.qibla annotations.sun.rise.apparent annotations.sun.rise.astronomical annotations.sun.rise.civil annotations.sun.rise.nautical annotations.sun.set.apparent annotations.sun.set.astronomical annotations.sun.set.civil annotations.sun.set.nautical annotations.timezone.name annotations.timezone.now_in_dst annotations.timezone.offset_sec annotations.timezone.offset_string annotations.timezone.short_name annotations.what3words.words annotations.wikidata bounds.northeast.lat bounds.northeast.lng bounds.southwest.lat bounds.southwest.lng components.ISO_3166-1_alpha-2 components.ISO_3166-1_alpha-3 components._type components.city components.country components.country_code components.political_union components.postcode components.state components.state_code confidence formatted geometry.lat geometry.lng annotations.FIPS.state annotations.currency.alternate_symbols annotations.currency.disambiguate_symbol components.county annotations.FIPS.county components.town query
52° 31’ 1.33140’’ N 13° 23’ 19.89564’’ E 33UUU9067619766 JO62qm64pc 1490441.066 6860227.862 https://www.openstreetmap.org/edit?node=240109189#map=17/52.51704/13.38886 https://www.openstreetmap.org/?mlat=52.51704&mlon=13.38886#map=17/52.51704/13.38886 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33db8mmzj1t355u0c0j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET third.gurgled.such Q64 52.6770365 13.5488599 52.3570365 13.2288599 DE DEU city Berlin Germany de European Union 10117 Berlin BE 4 10117 Berlin, Germany 52.51704 13.38886 NA NA NA NA NA NA Berlin
52° 30’ 24.96528’’ N 13° 23’ 50.93772’’ E 33UUU9123618630 JO62qm71qp 1491400.95 6858384.739 https://www.openstreetmap.org/edit?relation=62422#map=17/52.50693/13.39748 https://www.openstreetmap.org/?mlat=52.50693&mlon=13.39748#map=17/52.50693/13.39748 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33d8yeepfp4kew2es9j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET skews.moats.minus Q64 52.6755087 13.7611609 52.3382448 13.088345 DE DEU city Berlin Germany de European Union NA Berlin BE 2 Berlin, Germany 52.50693 13.39748 NA NA NA NA NA NA Berlin
44° 28’ 8.65560’’ N 71° 11’ 6.81360’’ W 19TCK2618626296 FN44jl72sn -7924303.11 5508377.717 https://www.openstreetmap.org/edit?relation=170184#map=17/44.46907/-71.18523 https://www.openstreetmap.org/?mlat=44.46907&mlon=-71.18523#map=17/44.46907/-71.18523 1 . $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 drvkupke058m4sb6360c 60.36 1549367820 1549361880 1549365960 1549363920 1549403940 1549409940 1549405800 1549407900 America/New_York 0 -18000 -500 EST strong.clean.crib Q821244 44.528436 -71.123642 44.445057 -71.397858 US USA city Berlin USA us NA 03570 New Hampshire NH 5 Berlin, NH 03570, United States of America 44.46907 -71.18523 33 US$ US$ Coös County NA NA Berlin
44° 12’ 36.27324’’ N 72° 36’ 12.25764’’ W 18TXP9146797998 FN34qf70ok -8082174.068 5468204.6 https://www.openstreetmap.org/edit?relation=8898132#map=17/44.21008/-72.60340 https://www.openstreetmap.org/?mlat=44.21008&mlon=-72.60340#map=17/44.21008/-72.60340 1 . $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dru7eb5y653rny3vp3ww 59.37 1549368120 1549362240 1549366320 1549364220 1549404360 1549410240 1549406160 1549408260 America/New_York 0 -18000 -500 EST grooves.fearfully.classic NA 44.2719667 -72.5197921 44.1547824 -72.6836842 US USA city Berlin USA us NA NA Vermont VT 6 Berlin, VT, United States of America 44.21008 -72.60340 50 US$ US$ Washington County 50023 NA Berlin
41° 37’ 17.35680’’ N 72° 44’ 44.34684’’ W 18TXM8780710206 FN31po09md -8098008.927 5076059.694 https://www.openstreetmap.org/edit?node=158845944#map=17/41.62149/-72.74565 https://www.openstreetmap.org/?mlat=41.62149&mlon=-72.74565#map=17/41.62149/-72.74565 1 . $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 drkkb8unxrwqyhztwm4q 59.3 1549367820 1549362180 1549366080 1549364100 1549404720 1549410360 1549406460 1549408440 America/New_York 0 -18000 -500 EST frosts.crowds.reef Q821199 41.661488 -72.7056519 41.581488 -72.7856519 US USA city NA USA us NA 06037 Connecticut CT 7 Berlin, CT 06037, United States of America 41.62149 -72.74565 09 US$ US$ Hartford County 09003 Berlin Berlin
39° 47’ 28.41432’’ N 74° 55’ 44.59296’’ W 18SWK0607404588 FM29ms89mv -8341064.092 4808298.871 https://www.openstreetmap.org/edit?relation=170680#map=17/39.79123/-74.92905 https://www.openstreetmap.org/?mlat=39.79123&mlon=-74.92905#map=17/39.79123/-74.92905 1 . $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dr4dqgy2dw0juru53e8c 57.91 1549368120 1549362660 1549366440 1549364520 1549405440 1549410960 1549407120 1549409040 America/New_York 0 -18000 -500 EST verdict.rushes.upgrading Q1086827 39.8091498 -74.907959 39.77601 -74.966113 US USA city Berlin USA us NA NA New Jersey NJ 7 Berlin, NJ, United States of America 39.79123 -74.92905 34 US$ US$ Camden County 34007 NA Berlin
42° 22’ 52.33440’’ N 71° 38’ 13.24356’’ W 19TBG8291095470 FN42ej31nl -7974595.709 5189444.074 https://www.openstreetmap.org/edit?relation=1844156#map=17/42.38120/-71.63701 https://www.openstreetmap.org/?mlat=42.38120&mlon=-71.63701#map=17/42.38120/-71.63701 1 . $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 drt11g782th1q7b3j34w 60.04 1549367640 1549361940 1549365900 1549363920 1549404360 1549410060 1549406100 1549408080 America/New_York 0 -18000 -500 EST astonished.rightfully.pythons Q524646 42.4182811 -71.580231 42.3505932 -71.6787958 US USA city Berlin USA us NA 01503 Massachusetts MA 7 Berlin, MA 01503, United States of America 42.38120 -71.63701 25 US$ US$ NA NA NA Berlin
38° 19’ 21.41544’’ N 75° 13’ 3.68112’’ W 18SVH8097141633 FM28jh37vk -8373194.86 4598602.233 https://www.openstreetmap.org/edit?relation=133689#map=17/38.32262/-75.21769 https://www.openstreetmap.org/?mlat=38.32262&mlon=-75.21769#map=17/38.32262/-75.21769 1 . $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dqfd02kjkv3c6dwm8g5s 57.81 1549368060 1549362660 1549366380 1549364520 1549405680 1549411080 1549407300 1549409220 America/New_York 0 -18000 -500 EST floral.evenly.shortwave Q614184 38.355184 -75.188018 38.308406 -75.234794 US USA city Berlin USA us NA NA Maryland MD 7 Berlin, MD, United States of America 38.32262 -75.21769 24 US$ US$ Worcester County 24047 NA Berlin
43° 58’ 4.93140’’ N 88° 56’ 36.41172’’ W 16TCP4410170158 EN53mx62sh -9901139.307 5430821.988 https://www.openstreetmap.org/edit?relation=251729#map=17/43.96804/-88.94345 https://www.openstreetmap.org/?mlat=43.96804&mlon=-88.94345#map=17/43.96804/-88.94345 1 . $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dpbf0h1k7kn3zy5d9g7r 47.39 1549372020 1549366140 1549370160 1549368120 1549408320 1549327800 1549410120 1549325760 America/Chicago 0 -21600 -600 CST admits.indecision.skins Q1569850 43.997968 -88.920726 43.947614 -88.980852 US USA city City of Berlin USA us NA NA Wisconsin WI 7 City of Berlin, WI, United States of America 43.96804 -88.94345 55 US$ US$ Green Lake County 55047 NA Berlin
annotations.DMS.lat annotations.DMS.lng annotations.FIPS.state annotations.MGRS annotations.Maidenhead annotations.Mercator.x annotations.Mercator.y annotations.OSM.edit_url annotations.OSM.url annotations.callingcode annotations.currency.alternate_symbols annotations.currency.decimal_mark annotations.currency.disambiguate_symbol annotations.currency.html_entity annotations.currency.iso_code annotations.currency.iso_numeric annotations.currency.name annotations.currency.smallest_denomination annotations.currency.subunit annotations.currency.subunit_to_unit annotations.currency.symbol annotations.currency.symbol_first annotations.currency.thousands_separator annotations.flag annotations.geohash annotations.qibla annotations.sun.rise.apparent annotations.sun.rise.astronomical annotations.sun.rise.civil annotations.sun.rise.nautical annotations.sun.set.apparent annotations.sun.set.astronomical annotations.sun.set.civil annotations.sun.set.nautical annotations.timezone.name annotations.timezone.now_in_dst annotations.timezone.offset_sec annotations.timezone.offset_string annotations.timezone.short_name annotations.what3words.words annotations.wikidata bounds.northeast.lat bounds.northeast.lng bounds.southwest.lat bounds.southwest.lng components.ISO_3166-1_alpha-2 components.ISO_3166-1_alpha-3 components._type components.city components.country components.country_code components.county components.postcode components.state components.state_code confidence formatted geometry.lat geometry.lng annotations.FIPS.county components.town query
44° 28’ 8.65560’’ N 71° 11’ 6.81360’’ W 33 19TCK2618626296 FN44jl72sn -7924303.11 5508377.717 https://www.openstreetmap.org/edit?relation=170184#map=17/44.46907/-71.18523 https://www.openstreetmap.org/?mlat=44.46907&mlon=-71.18523#map=17/44.46907/-71.18523 1 US$ . US$ $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 drvkupke058m4sb6360c 60.36 1549367820 1549361880 1549365960 1549363920 1549403940 1549409940 1549405800 1549407900 America/New_York 0 -18000 -500 EST strong.clean.crib Q821244 44.528436 -71.123642 44.445057 -71.397858 US USA city Berlin USA us Coös County 03570 New Hampshire NH 5 Berlin, NH 03570, United States of America 44.46907 -71.18523 NA NA Berlin
44° 12’ 36.27324’’ N 72° 36’ 12.25764’’ W 50 18TXP9146797998 FN34qf70ok -8082174.068 5468204.6 https://www.openstreetmap.org/edit?relation=8898132#map=17/44.21008/-72.60340 https://www.openstreetmap.org/?mlat=44.21008&mlon=-72.60340#map=17/44.21008/-72.60340 1 US$ . US$ $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dru7eb5y653rny3vp3ww 59.37 1549368120 1549362240 1549366320 1549364220 1549404360 1549410240 1549406160 1549408260 America/New_York 0 -18000 -500 EST grooves.fearfully.classic NA 44.2719667 -72.5197921 44.1547824 -72.6836842 US USA city Berlin USA us Washington County NA Vermont VT 6 Berlin, VT, United States of America 44.21008 -72.60340 50023 NA Berlin
41° 37’ 17.35680’’ N 72° 44’ 44.34684’’ W 09 18TXM8780710206 FN31po09md -8098008.927 5076059.694 https://www.openstreetmap.org/edit?node=158845944#map=17/41.62149/-72.74565 https://www.openstreetmap.org/?mlat=41.62149&mlon=-72.74565#map=17/41.62149/-72.74565 1 US$ . US$ $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 drkkb8unxrwqyhztwm4q 59.3 1549367820 1549362180 1549366080 1549364100 1549404720 1549410360 1549406460 1549408440 America/New_York 0 -18000 -500 EST frosts.crowds.reef Q821199 41.661488 -72.7056519 41.581488 -72.7856519 US USA city NA USA us Hartford County 06037 Connecticut CT 7 Berlin, CT 06037, United States of America 41.62149 -72.74565 09003 Berlin Berlin
39° 47’ 28.41432’’ N 74° 55’ 44.59296’’ W 34 18SWK0607404588 FM29ms89mv -8341064.092 4808298.871 https://www.openstreetmap.org/edit?relation=170680#map=17/39.79123/-74.92905 https://www.openstreetmap.org/?mlat=39.79123&mlon=-74.92905#map=17/39.79123/-74.92905 1 US$ . US$ $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dr4dqgy2dw0juru53e8c 57.91 1549368120 1549362660 1549366440 1549364520 1549405440 1549410960 1549407120 1549409040 America/New_York 0 -18000 -500 EST verdict.rushes.upgrading Q1086827 39.8091498 -74.907959 39.77601 -74.966113 US USA city Berlin USA us Camden County NA New Jersey NJ 7 Berlin, NJ, United States of America 39.79123 -74.92905 34007 NA Berlin
42° 22’ 52.33440’’ N 71° 38’ 13.24356’’ W 25 19TBG8291095470 FN42ej31nl -7974595.709 5189444.074 https://www.openstreetmap.org/edit?relation=1844156#map=17/42.38120/-71.63701 https://www.openstreetmap.org/?mlat=42.38120&mlon=-71.63701#map=17/42.38120/-71.63701 1 US$ . US$ $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 drt11g782th1q7b3j34w 60.04 1549367640 1549361940 1549365900 1549363920 1549404360 1549410060 1549406100 1549408080 America/New_York 0 -18000 -500 EST astonished.rightfully.pythons Q524646 42.4182811 -71.580231 42.3505932 -71.6787958 US USA city Berlin USA us NA 01503 Massachusetts MA 7 Berlin, MA 01503, United States of America 42.38120 -71.63701 NA NA Berlin
38° 19’ 21.41544’’ N 75° 13’ 3.68112’’ W 24 18SVH8097141633 FM28jh37vk -8373194.86 4598602.233 https://www.openstreetmap.org/edit?relation=133689#map=17/38.32262/-75.21769 https://www.openstreetmap.org/?mlat=38.32262&mlon=-75.21769#map=17/38.32262/-75.21769 1 US$ . US$ $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dqfd02kjkv3c6dwm8g5s 57.81 1549368060 1549362660 1549366380 1549364520 1549405680 1549411080 1549407300 1549409220 America/New_York 0 -18000 -500 EST floral.evenly.shortwave Q614184 38.355184 -75.188018 38.308406 -75.234794 US USA city Berlin USA us Worcester County NA Maryland MD 7 Berlin, MD, United States of America 38.32262 -75.21769 24047 NA Berlin
43° 58’ 4.93140’’ N 88° 56’ 36.41172’’ W 55 16TCP4410170158 EN53mx62sh -9901139.307 5430821.988 https://www.openstreetmap.org/edit?relation=251729#map=17/43.96804/-88.94345 https://www.openstreetmap.org/?mlat=43.96804&mlon=-88.94345#map=17/43.96804/-88.94345 1 US$ . US$ $ USD 840 United States Dollar 1 Cent 100 $ 1 , 🇺🇸 dpbf0h1k7kn3zy5d9g7r 47.39 1549372020 1549366140 1549370160 1549368120 1549408320 1549327800 1549410120 1549325760 America/Chicago 0 -21600 -600 CST admits.indecision.skins Q1569850 43.997968 -88.920726 43.947614 -88.980852 US USA city City of Berlin USA us Green Lake County NA Wisconsin WI 7 City of Berlin, WI, United States of America 43.96804 -88.94345 55047 NA Berlin
  • countrycode: Restricts the results to the given country. The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. “GB” for the United Kingdom, “FR” for France, “US” for United States. See example below.
results3 <- opencage_forward(placename = "Berlin", country = "DE")
results3$results %>% knitr::kable()
annotations.DMS.lat annotations.DMS.lng annotations.MGRS annotations.Maidenhead annotations.Mercator.x annotations.Mercator.y annotations.OSM.edit_url annotations.OSM.url annotations.callingcode annotations.currency.decimal_mark annotations.currency.html_entity annotations.currency.iso_code annotations.currency.iso_numeric annotations.currency.name annotations.currency.smallest_denomination annotations.currency.subunit annotations.currency.subunit_to_unit annotations.currency.symbol annotations.currency.symbol_first annotations.currency.thousands_separator annotations.flag annotations.geohash annotations.qibla annotations.sun.rise.apparent annotations.sun.rise.astronomical annotations.sun.rise.civil annotations.sun.rise.nautical annotations.sun.set.apparent annotations.sun.set.astronomical annotations.sun.set.civil annotations.sun.set.nautical annotations.timezone.name annotations.timezone.now_in_dst annotations.timezone.offset_sec annotations.timezone.offset_string annotations.timezone.short_name annotations.what3words.words annotations.wikidata bounds.northeast.lat bounds.northeast.lng bounds.southwest.lat bounds.southwest.lng components.ISO_3166-1_alpha-2 components.ISO_3166-1_alpha-3 components._type components.city components.country components.country_code components.political_union components.postcode components.state components.state_code confidence formatted geometry.lat geometry.lng query
52° 31’ 1.33140’’ N 13° 23’ 19.89564’’ E 33UUU9067619766 JO62qm64pc 1490441.066 6860227.862 https://www.openstreetmap.org/edit?node=240109189#map=17/52.51704/13.38886 https://www.openstreetmap.org/?mlat=52.51704&mlon=13.38886#map=17/52.51704/13.38886 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33db8mmzj1t355u0c0j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET third.gurgled.such Q64 52.6770365 13.5488599 52.3570365 13.2288599 DE DEU city Berlin Germany de European Union 10117 Berlin BE 4 10117 Berlin, Germany 52.51704 13.38886 Berlin
52° 30’ 24.96528’’ N 13° 23’ 50.93772’’ E 33UUU9123618630 JO62qm71qp 1491400.95 6858384.739 https://www.openstreetmap.org/edit?relation=62422#map=17/52.50693/13.39748 https://www.openstreetmap.org/?mlat=52.50693&mlon=13.39748#map=17/52.50693/13.39748 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33d8yeepfp4kew2es9j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET skews.moats.minus Q64 52.6755087 13.7611609 52.3382448 13.088345 DE DEU city Berlin Germany de European Union NA Berlin BE 2 Berlin, Germany 52.50693 13.39748 Berlin
  • language: an IETF format language code (such as “es” for Spanish or “pt-BR” for Brazilian Portuguese). If no language is explicitly specified, we will look for an HTTP Accept-Language header like those sent by a brower and use the first language specified and if none are specified “en” (English) will be assumed. See example below.
annotations.DMS.lat annotations.DMS.lng annotations.MGRS annotations.Maidenhead annotations.Mercator.x annotations.Mercator.y annotations.OSM.edit_url annotations.OSM.url annotations.callingcode annotations.currency.decimal_mark annotations.currency.html_entity annotations.currency.iso_code annotations.currency.iso_numeric annotations.currency.name annotations.currency.smallest_denomination annotations.currency.subunit annotations.currency.subunit_to_unit annotations.currency.symbol annotations.currency.symbol_first annotations.currency.thousands_separator annotations.flag annotations.geohash annotations.qibla annotations.sun.rise.apparent annotations.sun.rise.astronomical annotations.sun.rise.civil annotations.sun.rise.nautical annotations.sun.set.apparent annotations.sun.set.astronomical annotations.sun.set.civil annotations.sun.set.nautical annotations.timezone.name annotations.timezone.now_in_dst annotations.timezone.offset_sec annotations.timezone.offset_string annotations.timezone.short_name annotations.what3words.words annotations.wikidata bounds.northeast.lat bounds.northeast.lng bounds.southwest.lat bounds.southwest.lng components.ISO_3166-1_alpha-2 components.ISO_3166-1_alpha-3 components._type components.city components.country components.country_code components.political_union components.postcode components.state components.state_code confidence formatted geometry.lat geometry.lng query
52° 31’ 1.33140’’ N 13° 23’ 19.89564’’ E 33UUU9067619766 JO62qm64pc 1490441.066 6860227.862 https://www.openstreetmap.org/edit?node=240109189#map=17/52.51704/13.38886 https://www.openstreetmap.org/?mlat=52.51704&mlon=13.38886#map=17/52.51704/13.38886 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33db8mmzj1t355u0c0j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET third.gurgled.such Q64 52.6770365 13.5488599 52.3570365 13.2288599 DE DEU city Berlin Germany de European Union 10117 Berlin BE 4 10117 Berlin, Germany 52.51704 13.38886 Berlin
52° 30’ 24.96528’’ N 13° 23’ 50.93772’’ E 33UUU9123618630 JO62qm71qp 1491400.95 6858384.739 https://www.openstreetmap.org/edit?relation=62422#map=17/52.50693/13.39748 https://www.openstreetmap.org/?mlat=52.50693&mlon=13.39748#map=17/52.50693/13.39748 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33d8yeepfp4kew2es9j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET skews.moats.minus Q64 52.6755087 13.7611609 52.3382448 13.088345 DE DEU city Berlin Germany de European Union NA Berlin BE 2 Berlin, Germany 52.50693 13.39748 Berlin
results4 <- opencage_forward(placename = "Berlin", country = "DE", language = "de")
results4$results %>% knitr::kable()
annotations.DMS.lat annotations.DMS.lng annotations.MGRS annotations.Maidenhead annotations.Mercator.x annotations.Mercator.y annotations.OSM.edit_url annotations.OSM.url annotations.callingcode annotations.currency.decimal_mark annotations.currency.html_entity annotations.currency.iso_code annotations.currency.iso_numeric annotations.currency.name annotations.currency.smallest_denomination annotations.currency.subunit annotations.currency.subunit_to_unit annotations.currency.symbol annotations.currency.symbol_first annotations.currency.thousands_separator annotations.flag annotations.geohash annotations.qibla annotations.sun.rise.apparent annotations.sun.rise.astronomical annotations.sun.rise.civil annotations.sun.rise.nautical annotations.sun.set.apparent annotations.sun.set.astronomical annotations.sun.set.civil annotations.sun.set.nautical annotations.timezone.name annotations.timezone.now_in_dst annotations.timezone.offset_sec annotations.timezone.offset_string annotations.timezone.short_name annotations.what3words.words annotations.wikidata bounds.northeast.lat bounds.northeast.lng bounds.southwest.lat bounds.southwest.lng components.ISO_3166-1_alpha-2 components.ISO_3166-1_alpha-3 components._type components.city components.country components.country_code components.political_union components.postcode components.state components.state_code confidence formatted geometry.lat geometry.lng query
52° 31’ 1.33140’’ N 13° 23’ 19.89564’’ E 33UUU9067619766 JO62qm64pc 1490441.066 6860227.862 https://www.openstreetmap.org/edit?node=240109189#map=17/52.51704/13.38886 https://www.openstreetmap.org/?mlat=52.51704&mlon=13.38886#map=17/52.51704/13.38886 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33db8mmzj1t355u0c0j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET nirgends.digitalen.landkarte Q64 52.6770365 13.5488599 52.3570365 13.2288599 DE DEU city Berlin Deutschland de European Union 10117 Berlin BE 4 10117 Berlin, Deutschland 52.51704 13.38886 Berlin
52° 30’ 24.96528’’ N 13° 23’ 50.93772’’ E 33UUU9123618630 JO62qm71qp 1491400.95 6858384.739 https://www.openstreetmap.org/edit?relation=62422#map=17/52.50693/13.39748 https://www.openstreetmap.org/?mlat=52.50693&mlon=13.39748#map=17/52.50693/13.39748 49 , EUR 978 Euro 1 Cent 100 1 . 🇩🇪 u33d8yeepfp4kew2es9j 136.66 1549348860 1549341840 1549346700 1549344240 1549382400 1549389480 1549384620 1549387080 Europe/Berlin 0 3600 100 CET vorbei.fanclub.unklaren Q64 52.6755087 13.7611609 52.3382448 13.088345 DE DEU city Berlin Deutschland de European Union NA Berlin BE 2 Berlin, Deutschland 52.50693 13.39748 Berlin
  • limit: How many results should be returned (1-100). Default is 10.

  • min_confidence: an integer from 1-10. Only results with at least this confidence will be returned.

  • no_annotations: Logical (default FALSE), when TRUE the output will not contain annotations.

  • no_dedupe: Logical (default FALSE), when TRUE the output will not be deduplicated.

For more information about the output and the query parameters, see the package documentation, the API doc and OpenCage FAQ.

Caching

The underlying data at OpenCage is updated about once a day. Note that the package uses memoise with no timeout argument so that results are cached inside an active R session.

system.time(opencage_reverse(latitude = 10, longitude = 10))
system.time(opencage_reverse(latitude = 10, longitude = 10))
memoise::forget(opencage_reverse)
system.time(opencage_reverse(latitude = 10, longitude = 10))

Privacy

Both functions have a parameter no_record. It is FALSE by default.

  • When no_record is FALSE a log of the query is made by OpenCage. The company uses them to better generally understand how people are using its service (forward or reverse geocoding, what parts of the world are people most interested in, etc) and for debugging. The overwhelming majority (99.9999+% of queries) are never specifically looked at (sheer volume prevents that) and are automatically deleted after a few days. More information about privacy can be found here.

  • When no_record is TRUE the actual query is replaced with FILTERED in OpenCage logs, so that the company has no chance to see what your request was.

Addresses

They also have an abbr parameter, FALSE by default. When it is TRUE the addresses are abbreviated in the results, see more details in this blog post.

Meta

ropensci_footer