docs: specify support for place ID parameter in distance_matrix.py (#400)

Updated param comments to specify support for place ID via 'place_id:'

Per API documentation: "using place IDs is preferred over using addresses or latitude/longitude coordinates"

Created test_place_id_param() to test case when origin/destination
consist solely of place IDs. Updated test_mixed_params() to include
a place ID in the origin.

Author: ajgomez529

googlemaps/distance_matrix.py

@@ -26,17 +26,19 @@ def distance_matrix(client, origins, destinations,
                     transit_routing_preference=None, traffic_model=None, region=None):
     """ Gets travel distance and time for a matrix of origins and destinations.
 
-    :param origins: One or more locations and/or latitude/longitude values,
-        from which to calculate distance and time. If you pass an address as
-        a string, the service will geocode the string and convert it to a
+    :param origins: One or more addresses, Place IDs, and/or latitude/longitude
+        values, from which to calculate distance and time. Each Place ID string
+        must be prepended with 'place_id:'. If you pass an address as a string,
+        the service will geocode the string and convert it to a
         latitude/longitude coordinate to calculate directions.
     :type origins: a single location, or a list of locations, where a
         location is a string, dict, list, or tuple
 
-    :param destinations: One or more addresses and/or lat/lng values, to
-        which to calculate distance and time. If you pass an address as a
-        string, the service will geocode the string and convert it to a
-        latitude/longitude coordinate to calculate directions.
+    :param destinations: One or more addresses, Place IDs, and/or lat/lng values
+        , to which to calculate distance and time. Each Place ID string must be
+        prepended with 'place_id:'. If you pass an address as a string, the
+        service will geocode the string and convert it to a latitude/longitude
+        coordinate to calculate directions.
     :type destinations: a single location, or a list of locations, where a
         location is a string, dict, list, or tuple
 

tests/test_distance_matrix.py

@@ -84,7 +84,10 @@ def test_mixed_params(self):
             content_type="application/json",
         )
 
-        origins = ["Bobcaygeon ON", [41.43206, -81.38992]]
+        origins = [
+            "Bobcaygeon ON", [41.43206, -81.38992],
+            "place_id:ChIJ7cv00DwsDogRAMDACa2m4K8"
+        ]
         destinations = [
             (43.012486, -83.6964149),
             {"lat": 42.8863855, "lng": -78.8781627},
@@ -95,7 +98,8 @@ def test_mixed_params(self):
         self.assertEqual(1, len(responses.calls))
         self.assertURLEqual(
             "https://maps.googleapis.com/maps/api/distancematrix/json?"
-            "key=%s&origins=Bobcaygeon+ON%%7C41.43206%%2C-81.38992&"
+            "key=%s&origins=Bobcaygeon+ON%%7C41.43206%%2C-81.38992%%7C"
+            "place_id%%3AChIJ7cv00DwsDogRAMDACa2m4K8&"
             "destinations=43.012486%%2C-83.6964149%%7C42.8863855%%2C"
             "-78.8781627" % self.key,
             responses.calls[0].request.url,
@@ -181,3 +185,34 @@ def test_lang_param(self):
             "destinations=San+Francisco%%7CVictoria+BC" % self.key,
             responses.calls[0].request.url,
         )
+    @responses.activate
+    def test_place_id_param(self):
+        responses.add(
+            responses.GET,
+            "https://maps.googleapis.com/maps/api/distancematrix/json",
+            body='{"status":"OK","rows":[]}',
+            status=200,
+            content_type="application/json",
+        )
+
+        origins = [
+            'place_id:ChIJ7cv00DwsDogRAMDACa2m4K8',
+            'place_id:ChIJzxcfI6qAa4cR1jaKJ_j0jhE',
+        ]
+        destinations = [
+            'place_id:ChIJPZDrEzLsZIgRoNrpodC5P30',
+            'place_id:ChIJjQmTaV0E9YgRC2MLmS_e_mY',
+        ]
+
+        matrix = self.client.distance_matrix(origins, destinations)
+
+        self.assertEqual(1, len(responses.calls))
+        self.assertURLEqual(
+            "https://maps.googleapis.com/maps/api/distancematrix/json?"
+            "key=%s&"
+            "origins=place_id%%3AChIJ7cv00DwsDogRAMDACa2m4K8%%7C"
+            "place_id%%3AChIJzxcfI6qAa4cR1jaKJ_j0jhE&"
+            "destinations=place_id%%3AChIJPZDrEzLsZIgRoNrpodC5P30%%7C"
+            "place_id%%3AChIJjQmTaV0E9YgRC2MLmS_e_mY" % self.key,
+            responses.calls[0].request.url,
+        )