Repository: googlemaps/google-maps-services-python

Issue:
Add support for Address Descriptors to Geocoding
Thanks for stopping by to let us know something could be better!

---
**PLEASE READ** 

If you have a support contract with Google, please create an issue in the [support console](https://cloud.google.com/support/). This will ensure a timely response. 

Discover additional support services for the Google Maps Platform, including developer communities, technical guidance, and expert support at the Google Maps Platform [support resources page](https://developers.google.com/maps/support/). 

If your bug or feature request is not related to this particular library, please visit the Google Maps Platform [issue trackers](https://developers.google.com/maps/support/#issue_tracker).

Check for answers on StackOverflow with the [google-maps](http://stackoverflow.com/questions/tagged/google-maps) tag.

---

 **Describe the solution you'd like**
Add support for Address Descriptors in the geocoding request.

 **Additional context**
https://mapsplatform.google.com/demos/address-descriptors/

Discussion:

Patch:
diff --git a/README.md b/README.md
index cb5f782..4082379 100644
--- a/README.md
+++ b/README.md
@@ -92,6 +92,10 @@ addressvalidation_result =  gmaps.addressvalidation(['1600 Amphitheatre Pk'],
                                                     regionCode='US',
                                                     locality='Mountain View', 
                                                     enableUspsCass=True)
+
+# Get an Address Descriptor of a location in the reverse geocoding response
+address_descriptor_result = gmaps.reverse_geocode((40.714224, -73.961452), enable_address_descriptor=True)
+
 ```
 
 For more usage examples, check out [the tests](https://github.com/googlemaps/google-maps-services-python/tree/master/tests).
diff --git a/googlemaps/geocoding.py b/googlemaps/geocoding.py
index e409a49..590bb62 100644
--- a/googlemaps/geocoding.py
+++ b/googlemaps/geocoding.py
@@ -49,7 +49,9 @@ def geocode(client, address=None, place_id=None, components=None, bounds=None, r
     :param language: The language in which to return results.
     :type language: string
 
-    :rtype: list of geocoding results.
+    :rtype: result dict with the following keys:
+            status: status code
+            results: list of geocoding results
     """
 
     params = {}
@@ -72,11 +74,11 @@ def geocode(client, address=None, place_id=None, components=None, bounds=None, r
     if language:
         params["language"] = language
 
-    return client._request("/maps/api/geocode/json", params).get("results", [])
+    return client._request("/maps/api/geocode/json", params)
 
 
 def reverse_geocode(client, latlng, result_type=None, location_type=None,
-                    language=None):
+                    language=None, enable_address_descriptor=False):
     """
     Reverse geocoding is the process of converting geographic coordinates into a
     human-readable address.
@@ -94,7 +96,10 @@ def reverse_geocode(client, latlng, result_type=None, location_type=None,
     :param language: The language in which to return results.
     :type language: string
 
-    :rtype: list of reverse geocoding results.
+    :rtype: result dict with the following keys:
+            status: status code
+            results: list of reverse geocoding results
+            address_descriptor: address descriptor for the target
     """
 
     # Check if latlng param is a place_id string.
@@ -113,4 +118,7 @@ def reverse_geocode(client, latlng, result_type=None, location_type=None,
     if language:
         params["language"] = language
 
-    return client._request("/maps/api/geocode/json", params).get("results", [])
+    if enable_address_descriptor:
+        params["enable_address_descriptor"] = "true"
+
+    return client._request("/maps/api/geocode/json", params)


Test patch:
diff --git a/tests/test_geocoding.py b/tests/test_geocoding.py
index 813241f..8734c8b 100644
--- a/tests/test_geocoding.py
+++ b/tests/test_geocoding.py
@@ -41,7 +41,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.geocode("Sydney")
+        results = self.client.geocode("Sydney").get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -60,7 +60,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.reverse_geocode((-33.8674869, 151.2069902))
+        results = self.client.reverse_geocode((-33.8674869, 151.2069902)).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -79,7 +79,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.geocode("1600 Amphitheatre Parkway, " "Mountain View, CA")
+        results = self.client.geocode("1600 Amphitheatre Parkway, " "Mountain View, CA").get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -105,7 +105,7 @@ class GeocodingTest(TestCase):
                 "southwest": (34.172684, -118.604794),
                 "northeast": (34.236144, -118.500938),
             },
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -125,7 +125,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.geocode("Toledo", region="es")
+        results = self.client.geocode("Toledo", region="es").get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -144,7 +144,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.geocode("santa cruz", components={"country": "ES"})
+        results = self.client.geocode("santa cruz", components={"country": "ES"}).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -165,7 +165,7 @@ class GeocodingTest(TestCase):
 
         results = self.client.geocode(
             "Torun", components={"administrative_area": "TX", "country": "US"}
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -191,7 +191,7 @@ class GeocodingTest(TestCase):
                 "administrative_area": "Helsinki",
                 "country": "Finland",
             }
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -211,7 +211,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.geocode(place_id="ChIJeRpOeF67j4AR9ydy_PIzPuM")
+        results = self.client.geocode(place_id="ChIJeRpOeF67j4AR9ydy_PIzPuM").get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -230,7 +230,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.reverse_geocode((40.714224, -73.961452))
+        results = self.client.reverse_geocode((40.714224, -73.961452)).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -253,7 +253,7 @@ class GeocodingTest(TestCase):
             (40.714224, -73.961452),
             location_type="ROOFTOP",
             result_type="street_address",
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -277,7 +277,7 @@ class GeocodingTest(TestCase):
             (40.714224, -73.961452),
             location_type=["ROOFTOP", "RANGE_INTERPOLATED"],
             result_type="street_address",
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -301,7 +301,7 @@ class GeocodingTest(TestCase):
             (40.714224, -73.961452),
             location_type="ROOFTOP",
             result_type=["street_address", "route"],
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -311,6 +311,28 @@ class GeocodingTest(TestCase):
             responses.calls[0].request.url,
         )
 
+    @responses.activate
+    def test_reverse_geocode_with_address_descriptors(self):
+        responses.add(
+            responses.GET,
+            "https://maps.googleapis.com/maps/api/geocode/json",
+            body='{"status":"OK","results":[], "address_descriptor":{ "landmarks": [ { "placeId": "id" } ] } }',
+            status=200,
+            content_type="application/json",
+        )
+
+        response = self.client.reverse_geocode((-33.8674869, 151.2069902), enable_address_descriptor=True)
+
+        address_descriptor = response.get("address_descriptor", [])
+
+        self.assertEqual(1, len(address_descriptor["landmarks"]))
+        self.assertEqual(1, len(responses.calls))
+        self.assertURLEqual(
+            "https://maps.googleapis.com/maps/api/geocode/json?"
+            "latlng=-33.8674869,151.2069902&enable_address_descriptor=true&key=%s" % self.key,
+            responses.calls[0].request.url,
+        )
+
     @responses.activate
     def test_partial_match(self):
         responses.add(
@@ -321,7 +343,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.geocode("Pirrama Pyrmont")
+        results = self.client.geocode("Pirrama Pyrmont").get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -340,7 +362,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        results = self.client.geocode(components={"postal_code": "96766"})
+        results = self.client.geocode(components={"postal_code": "96766"}).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -359,7 +381,7 @@ class GeocodingTest(TestCase):
             content_type="application/json",
         )
 
-        self.client.geocode(self.u("\\u4e2d\\u56fd"))  # China
+        self.client.geocode(self.u("\\u4e2d\\u56fd")).get("results", [])  # China
         self.assertURLEqual(
             "https://maps.googleapis.com/maps/api/geocode/json?"
             "key=%s&address=%s" % (self.key, "%E4%B8%AD%E5%9B%BD"),