DOC: Add minimal geocoding example for docs (#614)

Shows the location of borough centers accessed through Google geocoding
API, along with the boundaries in the shapefile included in geopandas.

doc/source/geocoding.rst

@@ -1,17 +1,43 @@
+.. currentmodule:: geopandas
+
+.. ipython:: python
+   :suppress:
+
+   import geopandas as gpd
+
 
 Geocoding
 ==========
 
-[TO BE COMPLETED]
+``geopandas`` supports geocoding (i.e., converting place names to
+location on Earth) through `geopy`_, an optional dependency of ``geopandas``.
+The following example shows how to use the `Google geocoding API
+<https://developers.google.com/maps/documentation/geocoding/start>`_ to get the
+locations of boroughs in New York City, and plots those locations along
+with the detailed borough boundary file included within ``geopandas``.
+
+.. _geopy: http://geopy.readthedocs.io/
+
+.. ipython:: python
+
+    boros = gpd.read_file(gpd.datasets.get_path("nybb"))
+    boros.BoroName
+    boro_locations = gpd.tools.geocode(boros.BoroName, provider="google")
+    boro_locations
+
+    import matplotlib.pyplot as plt
+    fig, ax = plt.subplots()
+
+    boros.to_crs({"init": "epsg:4326"}).plot(ax=ax, color="white", edgecolor="black");
+    @savefig boro_centers_over_bounds.png
+    boro_locations.plot(ax=ax, color="red");
 
 
-.. function:: geopandas.tools.geocode(strings, provider='googlev3', **kwargs)
+The argument to ``provider`` can either be a string referencing geocoding
+services, such as ``'google'``, ``'bing'``, ``'yahoo'``, and
+``'openmapquest'``, or an instance of a ``Geocoder`` from ``geopy``. See
+``geopy.geocoders.SERVICE_TO_GEOCODER`` for the full list.
+For many providers, parameters such as API keys need to be passed as
+``**kwargs`` in the ``geocode`` call.
 
-  Geocode a list of strings and return a GeoDataFrame containing the
-  resulting points in its ``geometry`` column.  Available
-  ``provider``s include ``googlev3``, ``bing``, ``google``, ``yahoo``,
-  ``mapquest``, and ``openmapquest``.  ``**kwargs`` will be passed as
-  parameters to the appropriate geocoder.
-
-  Requires `geopy`_.  Please consult the Terms of Service for the
-  chosen provider.
+Please consult the Terms of Service for the chosen provider.