feat!: Added Address Descriptors to Geocoding response. Refactored Ge…

…o… (#516) * feat! Added Address Descriptors to Geocoding response. Refactored Geocoding response to allow fields outside the geocoding result to be exposed through the client. --------- Co-authored-by: Tom Clifford <[email protected]>
googlemaps · Jul 16, 2024 · 9ec69cb · 9ec69cb
1 parent 645e07d
commit 9ec69cb
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 21 deletions.
diff --git 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
@@ -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)
diff --git a/tests/test_geocoding.py b/tests/test_geocoding.py
@@ -41,7 +41,7 @@ def test_simple_geocode(self):
             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 @@ def test_reverse_geocode(self):
             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 @@ def test_geocoding_the_googleplex(self):
             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 @@ def test_geocode_with_bounds(self):
                 "southwest": (34.172684, -118.604794),
                 "northeast": (34.236144, -118.500938),
             },
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -125,7 +125,7 @@ def test_geocode_with_region_biasing(self):
             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 @@ def test_geocode_with_component_filter(self):
             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 @@ def test_geocode_with_multiple_component_filters(self):
 
         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 @@ def test_geocode_with_just_components(self):
                 "administrative_area": "Helsinki",
                 "country": "Finland",
             }
-        )
+        ).get("results", [])
 
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
@@ -211,7 +211,7 @@ def test_geocode_place_id(self):
             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 @@ def test_simple_reverse_geocode(self):
             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 @@ def test_reverse_geocode_restricted_by_type(self):
             (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 @@ def test_reverse_geocode_multiple_location_types(self):
             (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 @@ def test_reverse_geocode_multiple_result_types(self):
             (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 @@ def test_reverse_geocode_multiple_result_types(self):
             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 @@ def test_partial_match(self):
             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 @@ def test_utf_results(self):
             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 @@ def test_utf8_request(self):
             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"),