README.md
In walshc/GoogleMapsAPI: GoogleMapsAPI

GoogleMapsAPI

An R package to use various features of the Google Maps API:

Return coordinates from an address.
Return coordinates from a place (business/venue) name.
Return an address given coordinates.
Return a driving distance/time matrix from origin and destination coordinates.

The API allows 50 requests per second and 2,500 requests per day for free. To purchase additional requests, see here. To use the geocodePlace() function, an API key must be obtained first. See here. To use the distanceMatrix() function, an API key must also be obtained, and this API needs to be activated. See here for more information. The other functions do not require an API key.

The geocodeAddress() and reverseGeocode() functions are very similar to geocode() and revgeocode() in ggmap. The difference is that the output here returns details from the query which is useful for checking the accuracy of the results. ggmap also does not have the ability to use the Google Places API or the Distance Matrix API.

if (!require(devtools)) install.packages("devtools")
devtools::install_github("walshc/GoogleMapsAPI")

Example usage:

geocodeAddress("Time Square, New York City")

This gives output:

$crd
      lon       lat 
-73.98513  40.75890 

$address
        long_name      short_name                                        type
1       Manhattan       Manhattan political, sublocality, sublocality_level_1
2        New York        New York                         locality, political
3 New York County New York County      administrative_area_level_2, political
4        New York              NY      administrative_area_level_1, political
5   United States              US                          country, political
6           10036           10036                                 postal_code

Example usage:

addresses <- c("Time Square, New York City", "24 Beacon St, Boston, MA")
geocodeAddresses(addresses)

This gives the coordinates and all the possible address components of each location:

        lon      lat subpremise premise street_number         route
1 -73.98513 40.75890         NA      NA          <NA>          <NA>
2 -71.06377 42.35815         NA      NA            24 Beacon Street
  neighborhood, political political, sublocality, sublocality_level_1
1                    <NA>                                   Manhattan
2             Beacon Hill                                        <NA>
  political, sublocality, sublocality_level_2
1                                          NA
2                                          NA
  political, sublocality, sublocality_level_3 locality_political
1                                          NA                 NA
2                                          NA                 NA
  administrative_area_level_3, political administrative_area_level_2, political
1                                     NA                        New York County
2                                     NA                         Suffolk County
  administrative_area_level_1, political country, political postal_code
1                               New York      United States       10036
2                          Massachusetts      United States       02133

If you are geocoding many locations and need to split the searching over several days, the results from a previous search can also be provided so that they can be skipped. For example, you want to geocode 4,000 locations and you only found the first 2,000 before being cut off. The next day you can run:

geocodeAddresses(addresses, prev.results = yesterdays.results)

where yesterdays.results was the output from running the code the previous day. This will skip all the addresses you already found.

Example usage:

geocodePlace("Madison Square Garden",
             rough.crd = geocodeAddress("New York City")$crd,
             key = YOUR.API.KEY)

This gives output:

$crd
      lon       lat
-73.99344  40.75050

$name
[1] "Madison Square Garden"

$types
$types[[1]]
[1] "stadium"

$types[[2]]
[1] "point_of_interest"

$types[[3]]
[1] "establishment"


$vicinity
[1] "4 Pennsylvania Plaza, New York"

Example usage:

reverseGeocode(c(-73.98691, 40.75546))

This gives output:

$address
[1] "Times Square Tower, New York, NY 10036, USA"

$address.components
           long_name         short_name                                        type
1 Times Square Tower Times Square Tower                                     premise
2   Theater District   Theater District                     neighborhood, political
3          Manhattan          Manhattan sublocality_level_1, sublocality, political
4           New York           New York                         locality, political
5    New York County    New York County      administrative_area_level_2, political
6           New York                 NY      administrative_area_level_1, political
7      United States                 US                          country, political
8              10036              10036                                 postal_code

Inputs are matrices or data.frames with two columns (longitude and latitude), for example:

places <- rbind(geocodeAddress("Boston")$crd,
                geocodeAddress("New York")$crd,
                geocodeAddress("Washington DC")$crd)
#             lon      lat
#  [1,] -71.05888 42.36008
#  [2,] -74.00594 40.71278
#  [3,] -77.03687 38.90719

Example usage:

distanceMatrix(origins = places, destinations = places, key = YOUR.API.KEY)

This gives the following output:

$distance
       [,1]   [,2]   [,3]
[1,]      0 346648 707080
[2,] 346500      0 363730
[3,] 704490 361709      0

$duration
      [,1]  [,2]  [,3]
[1,]     0 13355 25668
[2,] 13134     0 13839
[3,] 25595 13695     0

$origin_addresses
[1] "1 Cambridge St, Boston, MA 02114, USA"
[2] "Steve Flanders Square, New York, NY 10038, USA"
[3] "1 Scott Cir NW, Washington, DC 20036, USA"

$destination_addresses
[1] "1 Cambridge St, Boston, MA 02114, USA"
[2] "Steve Flanders Square, New York, NY 10038, USA"
[3] "1 Scott Cir NW, Washington, DC 20036, USA"

distance is the driving distance (in meters)
duration is the driving time (in seconds)
origin_addresses and destination_addresses are the addresses corresponding to the coordinates given.

An API key allows 2,500 requests per day. This means that a single use of the function with 10 origins and 10 destinations will count as 100 requests. Therefore if you want to construct a large distance matrix you might have to wait several days. It should also be noted that the following will use up the same amount of your daily limit: