Introduction
As we progress in our overview of the ever-so-powerful Google Maps Platform Web Service APIs, we are further enlightened by how useful they are. We come to the realization of the immense number of use cases they possess and gain insight on how to use them in our own applications. In this article, we’ll be discussing, perhaps, the most widely used API of the Google Maps Platform, the Places API.
In case you have not read our previous blogs on the topic, here are the links:
- Google Maps Web Service APIs Implementation and Mapping Solutions Part 1
- Google Maps Web Service APIs Implementation and Mapping Solutions Part 2
The Google Places API is a useful web service for acquiring all the essential details about any place that you want. The Places API lets users search for various locations and establishments using different parameters such as text, coordinates, area etc. The API fetches a huge quantity of data available on the Google Maps Platform Servers for each place that fulfills your search criteria. Various applications can use this API for their different business requirements. Common implementations include features such as places autocomplete, formatted address input, and nearby searches based on place type and many more like these.
We will focus on some of the basic properties of the Places API and its commonly used features. For the complete documentation of what the Places API provides, navigate to the URL below.
https://developers.google.com/maps/documentation/places/web-service/search
Setup
Google might have made its services public, but not all these services are free. In order to use services from the Google Maps Platform follow the instructions here: Set up Cloud Console and API Keys. These instructions will help you set up your project on Google Cloud Console and your API keys for usage and billing purposes.
Google Places API
Google Places API has several features and uses, including searching for places, getting place details or images, place and query autocomplete, etc. To distinguish between these features and enable the user to specify the exact response they want, the Places API has different endpoints to cater to different response types. As such, the Places API is divided into nested APIs. The Places API makes up the following features and endpoints which we will be discussing in this article.
- Place Search
- Find Place
- Nearby Search
- Text Search
- Place Details
- Place Photos
- Place Autocomplete
- Query Autocomplete
1) Place Search
The Places API’s “Place Search” module consists of 3 different types of endpoints discussed below.
a) Find Place
The Find Place API request takes a text string as a parameter and returns a single place that fits your query best in response. The text data to be entered could be an address, name or phone number of the establishment. The input data must be a string, though. Data sent in number format will return an error.
The Find Place API is mainly used in the following format:
https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters
Find Place API Required Parameters
The URL includes a few optional as well as required parameters that are needed to get the required result from the API. The image below shows the list of required parameters.
The input field must contain a string. The “inputtype” field may contain 2 options: either the value “textquery” or “phonenumber”. If we select the “phonenumber” value then the user must input a phone number in international format (prefixed by a plus sign (“+”), followed by the country code, then the phone number itself). In case of a text query, any string that may represent the location’s address or name should be used.
Find Place API Optional Parameters
The “fields” section would contain the list of values that you want to get in response to the API call. These fields include formatted_address, rating, name, opening_hours, photos etc. For the whole list of supported parameters, visit the official link below.
https://developers.google.com/maps/documentation/places/web-service/search-find-place – optional-parameters
Another useful optional parameter included in the Places API is the “locationbias” field. The user would provide the field with two lat/long pairs that would represent two points of a rectangular region or a single coordinate representing the center of a circle along with the desired radius in meters. The below API format draws a circle of 1000 meters around a specific coordinate to return places from that specified region using the format; circle:radius@lat,lng.
Format
https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Emirates Stadium&inputtype=textquery&fields=formatted_address,name,rating,opening_hours,geometry,price_level,photos&locationbias=locationbias=circle%3A2000%4051.5548885,-0.108438&key=XXXXXXXXXXXXXXXXXXXXXXX
Response
The API Response would return the fields provided by the user, if available for the place returned in the response, in an easily readable and parsable format.
HTML URL Encoding
In the API examples used in this article, various characters are replaced with encoded set of characters. For example, spaces are replaced with the character set “%20” as well as the colon “:” is replaced with “%3A”. URLs need to be properly formatted before being sent over the internet. The internet only accepts URLs containing characters only from the ASCII character-set. URL encoding is used to replace unsafe characters with ASCII friendly ones. Kindy visit the link below for the complete list of ASCII Encoded characters used in URLs.
https://www.w3schools.com/tags/ref_urlencode.ASP
Nearby Search
A Nearby Search API request returns a list of matching places within a specified region. You can either provide the API with a set of keywords to search against or specify the type of places you require as a result.
The Nearby Search API is mainly used in the following format:
https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters
Nearby Search Required Parameters
Similar to other Web Service APIs in the Google Maps Platform, the Nearby Search API has a list of required and optional parameters which can be provided upon making a request to the web service. The following image shows a list of useful parameters which the API supports.
The location field is necessary when calling this API request. The location field would contain two decimal integers, separated by a comma representing the longitude and latitude of a location, respectively. These coordinates would dictate the region around which the API would return matching responses.
Nearby Search Optional Parameters
The optional parameters which can be used include a particular feature of the radius, which dictates the circular region in meters corresponding to the center of the circle as the location. Through this, the user can dictate the circular region from which the API would fetch matching places. The type and keyword fields would represent the fields that specify the sort of places the user should search.
In the above example the field “keyword” has been set to “football” and type to “stadium” This would specify the API to fetch stadiums that would be related to football. If we remove the keyword field, then all stadiums, whether baseball, basketball, soccer etc. would be returned in response. For more information on optional parameters and location types visit the official documentation below.
https://developers.google.com/maps/documentation/places/web-service/search-nearby – optional-parameters
Format
https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=51.5548885,-0.108438&radius=15000&type=stadium&keyword=football&key=XXXXXXXXXXXXXXXXXXXXXXX
Response
The API Response would return a list of all the matching places in the form of JSON objects. The JSON object for each result would contain multiple useful fields such as the rating by users of the place, vicinity of the location, name etc.
Text Search
A Text Search delivers results for a group of locations based on a string, such as “football stadiums in London,” “hotels in Carlsbad,” or “305 Main Street.” The service returns a list of locations that match the text string, as well as any location bias that has been specified. Non-address components of the string may match businesses as well as addresses, making the service particularly helpful for conducting confusing address inquiries in an automated system.
A list of locations will be included in the search response. You can request more information about any place from the answer by sending a “Place Details” request.
The Text Search API is mainly used in the following format:
https://maps.googleapis.com/maps/api/place/textsearch/output?parameters
Text Search Required Parameters
The following image shows a list with examples of useful required and optional parameters for the Text Search API.
The Text Search web service only has “query” as its sole required parameter. As explained above, the user would enter a phrase for the API request containing either a set of keywords or an ambiguous incomplete address. In response to this, the web service would return places matching the provided query.
Text Search Optional Parameters
The optional parameters supported by the Text Search API are pretty much the same as the previously discussed web services. In the above draft endpoint, the “location” and “radius” parameters are being used again to dictate a region to the API request to return places around the specified location around a radius of 3000 meters (3 kilometers).
Format
https://maps.googleapis.com/maps/api/place/textsearch/json?query=football stadiums in london&location=51.5548885,-0.108438&radius=3000&key=XXXXXXXXXXXXXXXXXXXXXX
Response
The response of the Text Search API is similar to the Nearby Place web service, containing the same format of a list of JSON objects, containing the same type of fields as the previously discussed API response. For more information regarding the response fields or any other information regarding this web service, visit the official documentation below.
https://developers.google.com/maps/documentation/places/web-service/search-text
Explore Our Web Services
Conclusion
This article was a further continuation of the vast scope of the Google Maps Platform and their supported Web Service APIs. In this article, we only covered the first topic of the Places API module. As we investigate this domain further, we will continue to discover use cases and implementation options. We will find more ways to implement this platform in our personal and professional applications and services to increase their functionality and user experience many fold.
In future articles, we will further complete the walkthrough of the Google Places API and look at the remaining topics of this popular and frequently used sub domain.
