This document is a refresh to an older article that used previous versions of the GMP APIs. This content is updated to the new version of the Places API launched in 2023-24 and Routes API launched in 2023.
Typically when the user is driving to a point-of-interest (POI) they would actually require navigation to a nearby location such as a parking lot or an access point. Picture a driver that needs to go to an airport or a shopping mall. When going to an airport the driver is trying to reach a terminal or a drop-off point rather than the center of the airport compound. Likewise a parking lot next to the shopping center might be a much better option for a user with a car. In this case, when developing an app or a service to guide the driver, first find the location they are going to and then offer the driver optional destinations near that location. This approach lets you to provide better service to your customers and demonstrate that you value their time, with a small but smart development effort that leverages location data provided by Google Maps Platform.
We will show how you can use the new Places API and Routes API in sequence or combination to identify the right location to park next to your destination. This solution aims to remove uncertainty and multiple interactions to find a spot to park while driving once closer to the end destination. Have a look at two examples of how these cases could be implemented in detail.
Example 1 - a tourist attraction with no parking lot
Pick a location that is not directly connected to the roadside so that a route must be retrieved separately, the destination is Notre Dame in Paris and as a starting point we will use the Gare de l'Est railway station (48.87697775149635, 2.3592247806755564).
The driver leaves the station about 16 minutes north of Notre Dame. Notre Dame is a famous tourist attraction on an island with bridge access, some one-way streets and no large parking lot available nearby, so this should be an interesting challenge.
- Places API request
This example Places API request is using text search to find Notre Dame. See the developer documentation for details. The "$APIKEY" in these examples is the API key you have for the Google Maps Platform Places and Routes APIs enabled in the Google Cloud Console. For a more detailed explanation see the documentation for getting started with Google Maps Platform.
The new Places API requests have a new format. The response fields are no longer fixed and as a developer you must define a fieldmask in the header. Use of the fieldmask is defined in the documentation.
curl -X POST --data @notre_dame.json \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,places.location' \
'https://places.googleapis.com/v1/places:searchText'
With "notre_date.json" content for search parameters:
{
"textQuery": "Notre Dame, Paris",
"languageCode": "en"
}
The response to the above request gives the following latitude & longitude coordinates:
{
"places": [
{
"id": "ChIJATr1n-Fx5kcRjQb6q6cdQDY",
"formattedAddress": "6 Parvis Notre-Dame - Pl. Jean-Paul II, 75004 Paris, France",
"location": {
"latitude": 48.852968200000007,
"longitude": 2.3499021
},
"displayName": {
"text": "Cathédrale Notre-Dame de Paris",
"languageCode": "en"
}
}
]
}
As you can see, the coordinates indeed pinpoint Notre Dame.
|
|
As a developer or a service provider, it's a good idea to automatically prompt the driver "Looking for parking near Notre Dame?" or if the driver has an electric vehicle then you might want to search for a charging station. The user experience will be different depending on the device and screen, but a subtle dialog text that disappears after a short time could be worth considering in this case. To find parking near Notre Dame, do a Places API nearby search with types "parking" and "electric_vehicle_charging_station" with a radius of 500 meters. The following example will bias the results to parking areas within 500 meters of Notre Dame.
curl -X POST -d '{
"includedTypes": ["parking", "electric_vehicle_charging_station"],
"maxResultCount": 10,
"rankPreference": "DISTANCE",
"locationRestriction": {
"circle": {
"center": {
"latitude": 48.852968200000007,
"longitude": 2.3499021},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H "X-Goog-FieldMask: places.displayName,places.location" \
https://places.googleapis.com/v1/places:searchNearby
The first result is a charging station at 48.854981, 2.350629, though by the time you run this example, your results may vary. Use this location in the next part where we are doing a Routes API request.
- **Routes API request **
To find the route from the station to a charging station close to Notre Dame, you need to do a Routes API request. Just set the origin and destination parameters. See developer documentation for more options.
curl -X POST -d '{
"origin":{
"location":{
"latLng":{
"latitude": 48.87697775149635,
"longitude": 2.3592247806755564
}
}
},
"destination":{
"location":{
"latLng":{
"latitude": 48.854981,
"longitude": 2.350629
}
}
},
"travelMode": "DRIVE",
"routingPreference": "TRAFFIC_AWARE",
"departureTime": "2024-05-16T15:01:23.045123456Z",
"computeAlternativeRoutes": false,
"routeModifiers": {
"avoidTolls": false,
"avoidHighways": false,
"avoidFerries": false
},
"languageCode": "en-US",
"units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'
Routes API response typically contains multiple route suggestions. To include the route data in the response, define "routes.legs" in the fieldmask. Each route consists of multiple "legs" and those contain multiple "steps" showing traveling distance and coordinates. To find the final coordinates reachable with a car, use the "endLocation" field of the last step of a last leg in a route you selected. "latitude": 48.854937299999996, "longitude": 2.3505841999999997
This location may seem like not the first choice, but when you look at the map or Google Street View, you will find that this location is within a very short walking distance, about 6-7 minutes, from Notre Dame.
Walking route from charging station parking spot to Notre Dame
Summary for example 1
As you can see, finding a parking area for a car requires only a few API calls and displaying the suggestion to the driver. This saves time for your users as they are not driving around on one-way streets or trying to find a place to leave the car in a crowded tourist attraction. As a summary we did the following API requests:
- A Places API text search request to find Notre Dame coordinates
- A Places API nearby search to find a parking area with an electric car charging station within 500 meters of those coordinates
- A Routes API request to find a route to the charging station
Example 2 - Guiding to a terminal in a large airport
Consider another example where the driver is trying to reach a large area that has multiple locations, POIs or potential drop-off points. The driver is leaving from Wembley stadium, UK (51.557263604707224, -0.2794575145680608) and trying to get to London Heathrow airport terminal 5.
What is great about the new Places API autocomplete is the ability to define a primary type as search criteria in combination with API predicting sub premises as potential search results. In this case it means that searching for an airport will also return terminals. You can find the complete list of types to include or exclude in the documentation.
curl -X POST -d '{
"input": "Heathrow",
"includedPrimaryTypes": ["airport"]
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
https://places.googleapis.com/v1/places:autocomplete
The query above gives us a list of the terminals and individual drop-off points at those terminals. From the list of results we can find "London Heathrow Airport Terminal 5" and its place ID:
"place_id" : "ChIJo21hnPxxdkgRksRL0KQRWII",
Using the "placeId" parameter we can tell the Routes API that we are trying to reach a place rather than some arbitrary coordinates.
curl -X POST -d '{
"origin":{
"location":{
"latLng":{
"latitude": 51.557263604707224,
"longitude": -0.2794575145680608
}
}
},
"destination":{
"placeId": "ChIJo21hnPxxdkgRksRL0KQRWII"
},
"travelMode": "DRIVE",
"routingPreference": "TRAFFIC_AWARE",
"departureTime": "2024-05-16T15:01:23.045123456Z",
"computeAlternativeRoutes": false,
"languageCode": "en-US",
"units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'
Again, like in the previous example, by reading all the steps in the JSON response you will find the last part of the journey and the end locations lat & long coordinates (51.4714348, "longitude": -0.48967890000000003).
Summary for example 2
Like in the previous example, the development effort to provide improved guidance to the driver is very small and the benefits in time saved to the driver can be measured. We did the following requests:
- A Places API autocomplete (new) request to find Heathrow airport terminal 5
- A Routes API request to get a route from Wembley to terminal 5
This example just scratches the surface of new Places API features. Take a look at some of the new place types such as airstrip and international airport.
Conclusion
As you can see, the development effort required to provide a premium service to your customers traveling by car is rather small and you can demonstrate how you are thinking about your customers' needs.
For development purposes you can use many of the libraries and tools available to help you build the services for your customers. Have a look at our publicly available GitHub repository for Google Maps Platform.
Next Actions
Getting started with GMP : https://developers.google.com/maps/get-started
Suggested further reading
Places API autocomplete (new) documentation : https://developers.google.com/maps/documentation/places/web-service/place-autocomplete
Routes API documentation : https://developers.google.com/maps/documentation/routes
Contributors
Principal author: Mikko Toivanen | Google Maps Platform Solutions Engineer