Google Developers Academy

Using Additional Place Search Features

Learning objectives
  • Use keyword and name to restrict results.
  • Use types to narrow your search.
  • Order results by distance from the specified location.

The Places API accepts search filter parameters. If you know that you're looking for a place with a particular word or string in its name, or if you're only interested in results that are restaurants, you can pass this information to the Places service for more accurate results.

You can also return Places ordered by distance, rather than by prominence in the area.

Including Keywords in Place Searches

You can refine your search request by including search terms in Places Search request URLs.

To match search terms against all of the content that Google has indexed for a Place, include the keyword parameter in your URL. For example, to find places near downtown San Francisco with the keyword coffee in their names, addresses, reviews, or other information that Google associates with Places, use the URL below:

https://maps.googleapis.com/maps/api/place/search/json
  ?keyword=coffee
  &location=37.787930,-122.4074990
  &radius=5000&sensor=false
  &key=YOUR_API_KEY}

You can include multiple keywords by separating each with a plus symbol (+):

?keyword=coffee+internet

Phrases should be enclosed in quotation marks, with + symbols replacing spaces:

?keyword="fair+trade"+coffee

Including Names in Place Searches

You can include a name parameter to match against the names of Places only. The Places API supports partial name matching, so Amo will match Amoeba.

https://maps.googleapis.com/maps/api/place/search/json
  ?name=amoeba
  &location=37.787930,-122.4074990
  &radius=5000
  &sensor=false
  &key=YOUR_API_KEY

As with the keyword parameter, enclose phrases in quotation marks, and replace spaces with + symbols:

?name="amoeba+records"

You can use the keyword and name parameters together to further refine your Places Search requests.

https://maps.googleapis.com/maps/api/place/search/json
  ?keyword=cafe
  &name="pour+over+coffee"
  &location=37.787930,-122.4074990
  &radius=5000
  &sensor=false
  &key=YOUR_API_KEY

You can test out each of these examples to see how the results differ by copying and pasting the URLs into your browser’s address bar and substituting the key with your own.

Searching for Specific Types of Places

To search for specific types of places (such as cafes), you can include the types parameter in your Places Search requests. You must use place types that are recognized by the Places API, as included in the list of supported types; otherwise your searches will be ignored.

https://maps.googleapis.com/maps/api/place/search/json
  ?types=cafe
  &location=37.787930,-122.4074990
  &radius=5000
  &sensor=false
  &key=YOUR_API_KEY

Try specifying multiple place types by modifying the URL below to include other place types separated by a pipe ( | ) character in the URL. The Places Search API will return Places associated with any of the types that you specify. The example below demonstrates how to search for places that are considered a cafe or a bakery or both:

https://maps.googleapis.com/maps/api/place/search/json
  ?types=cafe|bakery
  &location=37.787930,-122.4074990
  &radius=5000
  &sensor=false
  &key=YOUR_API_KEY

As you continue to work with the API and you become more familiar with it, you’ll find that some Places have multiple types. For example, a hotel is of type lodging, as well as being an establishment (which generally denotes a business).

Retrieving Places Ranked by Distance

Instead of retrieving Places ranked by their prominence, you can specify that Places should be ranked by the distance from a specified location, from nearest to furthest.

To retrieve places based by distance:

  1. Remove the radius parameter from your Place Search request.
  2. Add a rankby=distance parameter/value pair.
  3. Include one or more of the keyword, name, or types parameters.

For example, the URL below can be used to specify a search for cafes near downtown San Francisco, with results ordered by distance from the location:

https://maps.googleapis.com/maps/api/place/search/json
  ?types=cafe
  &rankby=distance
  &location=37.787930,-122.4074990
  &sensor=false
  &key=YOUR_API_KEY

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.