Skip to contents

Convenience function for looking up latitude/longitude coordinate information for a given location. Returns data as a special "coords" object, which is specifically designed to interact smoothly with other relevant package functions. NOTE: USE OF THIS FUNCTION REQUIRES A VALID GOOGLE MAPS API KEY.


lookup_coords(address, components = NULL, apikey = NULL, ...)



Desired location typically in the form of place name, subregion, e.g., address = "lawrence, KS". Also accepts the name of countries, e.g., address = "usa", address = "brazil" or states, e.g., address = "missouri" or cities, e.g., address = "chicago". In most cases using only address should be sufficient.


Unit of analysis for address e.g., components = "country:US". Potential components include postal_code, country, administrative_area, locality, route.


A valid Google Maps API key. If NULL, lookup_coords() will look for a relevant API key stored as an environment variable (e.g., GOOGLE_MAPS_KEY).


Additional arguments passed as parameters in the HTTP request


Object of class coords.


Since Google Maps implemented stricter API requirements, sending requests to Google's API isn't very convenient. To enable basic uses without requiring a Google Maps API key, a number of the major cities throughout the word and the following two larger locations are baked into this function: 'world' and 'usa'. If 'world' is supplied then a bounding box of maximum latitutde/longitude values, i.e., c(-180, -90, 180, 90), and a center point c(0, 0) are returned. If 'usa' is supplied then estimates of the United States' bounding box and mid-point are returned. To specify a city, provide the city name followed by a space and then the US state abbreviation or country name. To see a list of all included cities, enter rtweet:::citycoords in the R console to see coordinates data.

See also

Other geo: lat_lng()


if (FALSE) {

## get coordinates associated with the following addresses/components
sf <- lookup_coords("san francisco, CA", "country:US")
usa <- lookup_coords("usa")
lnd <- lookup_coords("london")
bz <- lookup_coords("brazil")