Text Search (New)

A Text Search (New) returns information about a set of places based on a string — for example "pizza in New York" or "shoe stores near Ottawa" or "123 Main Street". The service responds with a list of places matching the text string and any location bias that has been set.

The service is especially useful for making ambiguous address queries in an automated system, and non-address components of the string may match businesses as well as addresses. Examples of ambiguous address queries are poorly-formatted addresses or requests that include non-address components such as business names. Requests like the first two examples below may return zero results unless a location - such as region, location restriction, or location bias - is set.

"10 High Street, UK" or "123 Main Street, US" Multiple "High Street"s in the UK; multiple "Main Street"s in the US. Query will not return desirable results unless a location restriction is set.
"ChainRestaurant New York" Multiple "ChainRestaurant" locations in New York; no street address or even street name.
"10 High Street, Escher UK" or "123 Main Street, Pleasanton US" Only one "High Street" in the UK city of Escher; only one "Main Street" in the US city of Pleasanton CA.
"UniqueRestaurantName New York" Only one establishment with this name in New York; no street address needed to differentiate.
"pizza restaurants in New York" This query contains its location restriction, and "pizza restaurants" is a well-defined place type. It returns multiple results.

The search response includes a list of places. You can send a Place Details request for more information about any of the places in the response.

Get started

To use Text Search, you need a project with a billing account, and the Places API (New) enabled. Take these steps to set up your project:

  1. Enable "Places API (New)" in the Google Cloud Console.

    Enable Places API (New)

  2. To make requests to the API, you can either:

    • Create a new API key and add an API restriction to restrict your API key to "Places API (New)".

      We recommend also adding an application restriction, to restrict your API key to the web server IP addresses you are using.

      Go to the Credentials page

    • Update an existing restricted API key to add Places API (New).
    • Create an OAuth 2.0 token for authentication. For more on using OAuth see Use OAuth.

Text Search requests

A Text Search request is an HTTP POST request of the following form:

https://places.googleapis.com/v1/places:searchText

Pass all parameters in the JSON request body or in headers as part of the POST request. For example:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Make a request using Text Search (New)

Places API supports the existing Text Search. If you are familiar with the existing Text Search, the Preview version of Text Search makes the following changes:

  • The new Text Search uses HTTP POST requests. Pass parameters in the request body or in headers as part of an HTTP POST request. In contrast, with the existing Text Search, you pass URL parameters using an HTTP GET request.
  • Field masking is required. You must specify which fields you want returned in the response. There is no default list of returned fields. If you omit this list, the methods return an error. For more information, see FieldMask header.
  • The new Text Search supports both API keys and OAuth tokens as the authentication mechanism.
  • Only JSON is supported as a response format in the new Text Search.

  • The existing Text Search let you specify latitude and longitude coordinates in the query string. For example: query=37.4239,-122.0925. That option is not supported in the new Text Search.

    Use the locationRestriction or locationBias filter in the Text Search (New) to restrict the search to a certain boundary. Or, use Reverse Geocoding to search on coordinates.

  • Each element of photo[] in the response contains the following fields:

    • name — A string used to identify the photo when you perform a Photo request. This field is named photo_reference in the existing Text Search.
    • heightPx — The maximum height of the image. This field is named height in the existing Text Search.
    • widthPx — The maximum width of the image. This field is named width in the existing Text Search.
    • authorAttributions[] — Any required attributions. This field is named html_attributions in the existing Text Search.

The following table lists parameters in the existing Text Search that have been renamed or modified for the new Text Search, or parameters that are no longer supported.

Current parameter New parameter Notes
language languageCode
location locationBias
maxprice/minprice priceLevels
opennow openNow
pagetoken Not supported.
query textQuery Required in all requests.
radius locationBias
region regionCode
type includedType Only takes a single value.

Usage limits

During the Preview release, you are limited to making a maximum of 10 queries per second per project.

Support options for Preview releases

Although Google has no obligation to provide support for Preview versions, features, or functionality of the Services, we'll consider requests at these development stages on a case-by-case basis.

  • Pre-release versions are not covered by the Google Maps Platform SLA.

  • Use of fallback mechanisms is recommended, especially if you are using a pre-release version in a production environment. Some example of fallback situations are: quota exceeded, unexpected responses codes and latency, or unexpected responses when compared to the existing Text Search.

You can use the issue tracker to request new features or suggest modifications to existing features. Please describe the specific functionality you would like to see added, as well as reasons you think it's important. If possible, include specific details about your use case and the new opportunities the feature would allow for:

For any other question on features, please send an email to newplacesapi@google.com.

Required parameters

  • FieldMask

    There is no default list of returned fields. If you omit this field mask, the methods return an error. Specify the field list by creating a response field mask. You then pass the response field mask to each method by using the URL parameter $fields or fields, or by using the HTTP header X-Goog-FieldMask.

    Field masking is a good design practice to ensure that you don't request unnecessary data, which helps to avoid unnecessary processing time and billing charges.

    Specify a comma-separated list of place data types to return. For example, to retrieve the display name and the address of the place.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Use * to retrieve all fields.

    X-Goog-FieldMask: *

    Specify one or more of the following place data types:

    places.id,places.name, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.location, places.photos, places.plusCode, places.types, places.utcOffsetMinutes, places.viewport, places.wheelchairAccessibleEntrance, places.internationalPhoneNumber, places.nationalPhoneNumber, places.openingHours, places.currentOpeningHours, places.secondaryOpeningHours, places.currentSecondaryOpeningHours, places.websiteUri places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.priceLevel, places.rating, places.reservable, places.reviews, places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout, places.userRatingCount

  • textQuery

    The text string on which to search, for example: "restaurant" or "123 Main Street". This must include a place name, address, or category of establishments. Any other types of input can generate errors and are not guaranteed to return valid results. The API returns candidate matches based on this string and orders the results based on their perceived relevance.

Optional parameters

  • includedType

    Restricts the results to places matching the specified type defined by Table 1. Only one type may be specified. For example

    • "includedType":"bar"
    • "includedType":"pharmacy"

  • languageCode

    The language in which to return results.

    • See the list of supported languages. Google often updates the supported languages, so this list may not be exhaustive.
    • If languageCode is not supplied, the API attempts to use the preferred language as specified in the Accept-Language header.
    • The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
    • If a name is not available in the preferred language, the API uses the closest match.
    • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.

  • locationBias

    Specifies an area to search. This location serves as a bias which means results around the specified location can be returned, including results outside the specified area.

    You can specify locationRestriction or locationBias, but not both. Think of locationRestriction as specifying the region which the results must be within, and locationBias as specifying the region that the results must be near but can be outside of the area.

    Specify the region as a rectangular Viewport or as a circle.

    • A circle is defined by center point and radius in meters. The radius must be between 0.0 and 50000.0, inclusive. For example:

      "locationBias": {
"circle": {
  "center": {
    "latitude": 37.7937,
    "longitude": -122.3965
  },
  "radius": 500.0
 }
}

    • A rectangle is a latitude-longitude viewport, represented as two diagonally opposite low and high points. A viewport is considered a closed region, meaning it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive:

      • If low = high, the viewport consists of that single point.
      • If low.longitude > high.longitude, the longitude range is inverted (the viewport crosses the 180 degree longitude line).
      • If low.longitude = -180 degrees and high.longitude = 180 degrees, the viewport includes all longitudes.
      • If low.longitude = 180 degrees and high.longitude = -180 degrees, the longitude range is empty.

      Both low and high must be populated, and the represented box cannot be empty. An empty viewport results in an error.

      For example, this viewport fully encloses New York City:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    Specifies an area to search. Results outside the specified area are not returned. Specify the region as a rectangular Viewport. See the description of locationBias for information on defining the Viewport.

    You can specify locationRestriction or locationBias, but not both. Think of locationRestriction as specifying the region which the results must be within, and locationBias as specifying the region that the results must be near but can be outside of the area.

  • minRating

    Restricts results to only those whose average user rating is strictly less than this limit. Values must be between 0.0 and 5.0 (inclusive) in increments of 0.5. For example: 0, 0.5, 1.0, ... , 5.0 inclusive. Values are rounded up to the nearest 0.5. For example, a value of 0.6 eliminates all results with a rating less than 1.0.

  • maxResultCount

    Specifies the maximum number of place results to return. Must be between 1 and 20 (default) inclusive.

  • priceLevels

    Restrict the search to places that are marked at certain price levels. The default is to select all price levels.

    Specify an array of one or more of the following values:

    • PRICE_LEVEL_UNSPECIFIED: Place price level is unspecified or unknown.
    • PRICE_LEVEL_INEXPENSIVE
    • PRICE_LEVEL_MODERATE
    • PRICE_LEVEL_EXPENSIVE
    • PRICE_LEVEL_VERY_EXPENSIVE

    For example:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • openNow

    Return only those places that are open for business at the time the query is sent, true, or return all businesses, false. Places that do not specify opening hours in the Google Places database will not be returned if you include this parameter in your query.

  • rankPreference

    Specifies how the results are ranked in the response. The API uses RELEVANCE by default when applicable. For example, for a query such as "Restaurants in New York City" then RELEVANCE is the default. For geographical queries, such as "Mountain View, CA", or other type of queries then no default is applied and the results appear in the order that they are returned by the back end.

    Values include:

    • DISTANCE: Rank results by distance.
    • RELEVANCE: Rank results by relevance.

  • regionCode

    The region code, specified as a ccTLD ("top-level domain") two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland"). The parameter can affect results based on applicable law.

Text Search examples

Find a place by query string

The following example shows a simple Text Search request for "Spicy Vegetarian Food in Sydney, Australia":

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Note that the X-Goog-FieldMask header specifies that the response contains the following data fields: places.displayName,places.formattedAddress. The response is then in the form:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St\nSydney NSW 2000\nAustralia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave\nFive Dock NSW 2046\nAustralia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St\nSydney NSW 2000\nAustralia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Add more data types to the field mask to return additional information. For example, add places.types,places.websiteUri to include the restaurant type and Web address in the response:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

The response is now in the form:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St\nSydney NSW 2000\nAustralia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave\nFive Dock NSW 2046\nAustralia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Filter places by price level

Use the priceLevel option to filter the results to restaurants defined as inexpensive or moderately expensive:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

This example also uses the X-Goog-FieldMask header to add the places.priceLevel data field to the response so it is in the form:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St\nSydney NSW 2000\nAustralia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St\nNewtown NSW 2042\nAustralia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Add additional options to refine your search, such as includedType, minRating, rankPreference, openNow, and other parameters described in Optional parameters.

Search for all places in an area

Use locationRestriction or locationBias, but not both, to restrict a search to an area. Think of locationRestriction as specifying the region which the results must be within, and locationBias as specifying the region that the results must be near but can be outside of the area.

The following example shows a Text Search request for "Spicy Vegetarian Food" biased to being within 500 meters of a point in downtown San Francisco. This request only return the first 10 results for places that are open.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food",
  "openNow": true,
  "maxResultCount": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Supported types tables

Table 1 lists the types that are supported for Text Search. These are used in the following ways:

  • As part of a Text Search request, use as the value of the includedType parameter.
  • As part of a Text Search response. The request must specify the places.typesdata field.

Table 2 lists additional place type values which may also be returned as part of a Text Search response. The request must specify the places.types data field. Values from Table 2 may NOT be used as includedType.

Table 1

Automotive
car_dealer
car_rental
car_repair
car_wash
 electric_vehicle_charging_station
gas_station
parking
rest_stop
Business
farm
Culture
art_gallery
museum
performing_arts_theater
Education
library
preschool
primary_school 		school
secondary_school
university
Entertainment and Recreation
amusement_center
amusement_park
aquarium
banquet_hall
bowling_alley
casino
community_center
convention_center
cultural_center
dog_park
event_venue
hiking_area
 historical_landmark
marina
movie_rental
movie_theater
national_park
night_club
park
tourist_attraction
visitor_center
wedding_venue
zoo
Finance
accounting
atm
bank
Food and Drink
american_restaurant
bakery
bar
barbecue_restaurant
brazilian_restaurant
breakfast_restaurant
brunch_restaurant
cafe
chinese_restaurant
coffee_shop
fast_food_restaurant
french_restaurant
greek_restaurant
hamburger_restaurant
ice_cream_shop
indian_restaurant
indonesian_restaurant
italian_restaurant
japanese_restaurant
korean_restaurant 		lebanese_restaurant
meal_delivery
meal_takeaway
mediterranean_restaurant
mexican_restaurant
middle_eastern_restaurant
pizza_restaurant
ramen_restaurant
restaurant
sandwich_shop
seafood_restaurant
spanish_restaurant
steak_house
sushi_restaurant
thai_restaurant
turkish_restaurant
vegan_restaurant
vegetarian_restaurant
vietnamese_restaurant
Geographical Areas
administrative_area_level_1
administrative_area_level_2
country 		locality
postal_code
school_district
Government
city_hall
courthouse
embassy
fire_station 		local_government_office
police
post_office
Health and Wellness
dental_clinic
dentist
doctor
drugstore
hospital 		medical_lab
pharmacy
physiotherapist
spa
Lodging
bed_and_breakfast
campground
camping_cabin
cottage
extended_stay_hotel
farmstay
guest_house 		hostel
hotel
lodging
motel
private_guest_room
resort_hotel
rv_park
Places of Worship
church
hindu_temple
mosque
synagogue
Services
barber_shop
beauty_salon
cemetery
child_care_agency
consultant
courier_service
electrician
florist
funeral_home
hair_care
hair_salon
insurance_agency 		laundry
lawyer
locksmith
moving_company
painter
plumber
real_estate_agency
roofing_contractor
storage
tailor
telecommunications_service_provider
travel_agency
veterinary_care
Shopping
auto_parts_store
bicycle_store
book_store
cell_phone_store
clothing_store
convenience_store
department_store
discount_store
electronics_store
furniture_store
gift_shop
grocery_store
hardware_store
home_goods_store 		home_improvement_store
jewelry_store
liquor_store
market
pet_store
shoe_store
shopping_mall
sporting_goods_store
store
supermarket
wholesaler
Sports
athletic_field
fitness_center
golf_course
gym
playground
 ski_resort
sports_club
sports_complex
stadium
swimming_pool
Transportation
airport
bus_station
bus_stop
ferry_terminal
heliport
light_rail_station
park_and_ride 		subway_station
taxi_stand
train_station
transit_depot
transit_station
truck_stop

Table 2

The Place type values in Table 2 may be returned as part of a Text Search response. The request must specify the places.types data field. These types are NOT supported as includedType for Text Search requests.

Additional Place type values
administrative_area_level_3
administrative_area_level_4
administrative_area_level_5
administrative_area_level_6
administrative_area_level_7
archipelago
colloquial_area
continent
establishment
floor
food
general_contractor
geocode
health
intersection
landmark
natural_feature
neighborhood
place_of_worship
plus_code 		point_of_interest
political
post_box
postal_code_prefix
postal_code_suffix
postal_town
premise
room
route
street_address
street_number
sublocality
sublocality_level_1
sublocality_level_2
sublocality_level_3
sublocality_level_4
sublocality_level_5
subpremise
town_square