Select platform: [Android](https://developers.google.com/maps/documentation/places/android-sdk/text-search.md.txt "View this page for the Android platform docs.") [iOS](https://developers.google.com/maps/documentation/places/ios-sdk/text-search.md.txt "View this page for the iOS platform docs.") [JavaScript](https://developers.google.com/maps/documentation/javascript/place-search.md.txt "View this page for the JavaScript platform docs.") [Web Service](https://developers.google.com/maps/documentation/places/web-service/text-search.md.txt "View this page for the Web Service platform docs.")
**European Economic Area (EEA) developers** > [!NOTE] > If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](https://developers.google.com/maps/comms/eea/faq.md.txt). 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. In addition to [required parameters](https://developers.google.com/maps/documentation/places/android-sdk/text-search.md.txt#required-parameters), Text Search (New) supports refining queries using [optional parameters](https://developers.google.com/maps/documentation/places/android-sdk/text-search#optional-parameters) for better results. Text Search (New) is similar to [Nearby Search (New)](https://developers.google.com/maps/documentation/places/android-sdk/nearby-search). The main difference between the two is that Text Search (New) lets you specify an arbitrary search string while Nearby Search (New) requires a specific area in which to search. > [!NOTE] > **Note:** Text Search (New) is available in Places SDK for Android version 3.3.0 and later. For more information, see [Choose your SDK > version](https://developers.google.com/maps/documentation/places/android-sdk/choose-sdk). For more information about using the Kotlin APIs added in version 4.0.0, see the [Reference > Overview](https://developers.google.com/maps/documentation/places/android-sdk/reference). ## Text Search requests > [!NOTE] > **Note:** Text Search is part of **Places SDK for Android (New)** and is not available in **Places SDK for Android**. A Text Search request is in the form: ```java // Specify the list of fields to return. final List placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME); // Define latitude and longitude coordinates of the search area. LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874); LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572); // Use the builder to create a SearchByTextRequest object. final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields) .setMaxResultCount(10) .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build(); // Call PlacesClient.searchByText() to perform the search. // Define a response handler to process the returned List of Place objects. placesClient.searchByText(searchByTextRequest) .addOnSuccessListener(response -> { List places = response.getPlaces(); }); ``` In this example, you: - Set the field list to include only `Place.Field.ID` and `Place.Field.DISPLAY_NAME`. That means the `Place` objects in the response that represent each matching place only contain those two fields. - Use [`SearchByTextRequest.Builder`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt) to create a [`SearchByTextRequest`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.md.txt) object that defines the search. - Set the text query string to "Spicy Vegetarian Food". - Set the maximum number of result places to 10. The default and the maximum is 20. - Restrict the search area to the rectangle defined by latitude and longitude coordinates. No matches outside of this area are returned. - Add an `OnSuccessListener` and get the matching places from the [`SearchByTextResponse`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextResponse.md.txt) object. > [!NOTE] > **Note:** For more information on initializing `PlacesClient`, see [Initialize the Places API client](https://developers.google.com/maps/documentation/places/android-sdk/config.md.txt#connect-client). > [!NOTE] > You can use a [CancellationToken](https://developers.google.com/android/reference/com/google/android/gms/tasks/CancellationToken.md.txt) > to attempt to cancel a request to any of the request classes (for example, > `FetchPlaceRequest`). Cancellation is done on a best-effort basis. > Once a cancellation request is issued, no response will be returned. > **Issuing a cancellation token does NOT guarantee that a particular request > will be cancelled, and you may still be charged for the request even if no > response is returned**. ## Text Search responses The [`SearchByTextResponse`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextResponse.md.txt) class represents the response from a search request. A `SearchByTextResponse` object contains: - A list of `Place` objects that represent all matching places, with one `Place` object per matching place. - Each `Place` object only contains the fields defined by the field list passed in the request. For example, in the request you defined a field list as: ```java // Specify the list of fields to return. final List placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME); ``` This field list means that each `Place` object in the response contains only the place ID and name of each matching place. You can then use the `Place.getId()` and `Place.getName()` methods to access these fields in each `Place` object. For more examples of accessing data in a `Place` object, see [Access Place object data fields](https://developers.google.com/maps/documentation/places/android-sdk/place-details#access-place-object-data-fields) ### Pagination Text Search's [`SearchByTextResponse`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextResponse.md.txt) class provides access to text search result pagination through its [`getPagination()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextResponse.md.txt#getPagination()) method, which returns a Pagination object. Use the Pagination object's [`hasNextPage()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/Pagination.md.txt#hasNextPage()) method to determine if additional pages of results are available. This method returns a boolean value (true or false). While `hasNextPage()` returns true, call the [`fetchNextPage()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/Pagination.md.txt#fetchNextPage()) method to retrieve the next page of results. The following example shows how to check if a next page is available, and then load the page. ### Kotlin ```kotlin val searchByTextRequest = searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) { maxResultCount = 10 } // using pagination object (Preferred) placesClient.searchByText(searchByTextRequest) .addOnSuccessListener {response: SearchByTextResponse -> val places = response.places val pagination = response.pagination if (pagination.hasNextPage()) { pagination.setPageSize(20) pagination.fetchNextPage() .addOnSuccessListener { nextPageResponse -> val nextPagePlaces = nextPageResponse.getPlaces() } .addOnFailureListener {// Handle error with given status code} } } .addOnFailureListener { // TODO: Handle error with given status code. exception -> { exception.printStackTrace(); } } ``` ### Java ```java SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build(); // using pagination object (Preferred) placesClient.searchByText(searchByTextRequest) .addOnSuccessListener((response) -> { List places = response.getPlaces(); Log.i(TAG, "Places result: " + places); Pagination pagination = response.getPagination(); if (pagination.hasNextPage()) { pagination.setPageSize(20); // change the page size from 10 to 20 pagination.fetchNextPage() .addOnSuccessListener((nextPageResponse) -> { List nextPagePlaces = nextPageResponse.getPlaces(); Log.i(TAG, "Next page places result: " + nextPagePlaces); }); } }) .addOnFailureListener((exception) -> { if (exception instanceof ApiException) { // Handle error with given status code } }); ``` ## Required parameters The required parameters for [`SearchByTextRequest`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.md.txt) are: - ### Field list Specify which place data fields to return. Pass a list of [`Place.Field`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/model/Place.Field.md.txt) values specifying the data fields to return. There is no default list of returned fields in the response. Field lists are a good design practice to ensure that you don't request unnecessary data, which helps to avoid unnecessary processing time and billing charges. Specify one or more of the following fields: - The following fields trigger the [Text Search Essentials ID Only SKU](https://developers.google.com/maps/documentation/places/android-sdk/usage-and-billing.md.txt#text-search-id-only-ess-sku): `Place.Field.DISPLAY_NAME`\* \* Use instead of `Place.Field.NAME` (deprecated in version 4.0). `Place.Field.ID` `Place.Field.RESOURCE_NAME`\* \* Contains the place resource name in the form: `places/PLACE_ID`. Use `DISPLAY_NAME` to access the text name of the place. For a complete list of fields and their associated SKUs, see [Place Data Fields (New)](https://developers.google.com/maps/documentation/places/android-sdk/data-fields.md.txt). - The following fields trigger the [Text Search Pro SKU](https://developers.google.com/maps/documentation/places/android-sdk/usage-and-billing.md.txt#text-search-pro-sku): `Place.Field.ACCESSIBILITY_OPTIONS`\* Use instead of `Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE` (deprecated). `Place.Field.ADDRESS_COMPONENTS` `Place.Field.ADR_FORMAT_ADDRESS` `Place.Field.BUSINESS_STATUS` `Place.Field.FORMATTED_ADDRESS`\* Use instead of `Place.Field.ADDRESS` (deprecated). `Place.Field.GOOGLE_MAPS_URI` `Place.Field.ICON_BACKGROUND_COLOR` `Place.Field.ICON_MASK_URL` \* Use instead of `Place.Field.ICON_URL` (deprecated). `Place.Field.LOCATION`\* Use instead of `Place.Field.LAT_LNG` (deprecated). `Place.Field.PHOTO_METADATAS` `Place.Field.PLUS_CODE` `Place.Field.PRIMARY_TYPE` `Place.Field.PRIMARY_TYPE_DISPLAY_NAME` `Place.Field.SHORT_FORMATTED_ADDRESS` `Place.Field.SUB_DESTINATIONS` `Place.Field.TYPES` `Place.Field.UTC_OFFSET` `Place.Field.VIEWPORT` For a complete list of fields and their associated SKUs, see [Place Data Fields (New)](https://developers.google.com/maps/documentation/places/android-sdk/data-fields.md.txt). - The following fields trigger the [Text Search Enterprise SKU](https://developers.google.com/maps/documentation/places/android-sdk/usage-and-billing.md.txt#text-search-ent-sku): `Place.Field.CURRENT_OPENING_HOURS` `Place.Field.CURRENT_SECONDARY_OPENING_HOURS` `Place.Field.INTERNATIONAL_PHONE_NUMBER`\* \* Use instead of `Place.Field.PHONE_NUMBER`, which is deprecated. `Place.Field.NATIONAL_PHONE_NUMBER` `Place.Field.OPENING_HOURS` `Place.Field.PRICE_LEVEL` `Place.Field.RATING` `Place.Field.SECONDARY_OPENING_HOURS` `Place.Field.USER_RATING_COUNT`\* \* Use instead of `Place.Field.USER_RATINGS_TOTAL`, which is deprecated. `Place.Field.WEBSITE_URI` For a complete list of fields and their associated SKUs, see [Place Data Fields (New)](https://developers.google.com/maps/documentation/places/android-sdk/data-fields.md.txt). - The following fields trigger the [Text Search Enterprise Plus SKU](https://developers.google.com/maps/documentation/places/android-sdk/usage-and-billing.md.txt#text-search-ent-plus-sku): `Place.Field.ALLOWS_DOGS` `Place.Field.CURBSIDE_PICKUP` `Place.Field.DELIVERY` `Place.Field.DINE_IN` `Place.Field.EDITORIAL_SUMMARY` `Place.Field.EV_CHARGE_OPTIONS` `Place.Field.FUEL_OPTIONS` `Place.Field.GOOD_FOR_CHILDREN` `Place.Field.GOOD_FOR_GROUPS` `Place.Field.GOOD_FOR_WATCHING_SPORTS` `Place.Field.LIVE_MUSIC` `Place.Field.MENU_FOR_CHILDREN` `Place.Field.OUTDOOR_SEATING` `Place.Field.PARKING_OPTIONS` `Place.Field.PAYMENT_OPTIONS` `Place.Field.RESERVABLE` `Place.Field.RESTROOM` `Place.Field.REVIEWS` `Place.Field.SERVES_BEER` `Place.Field.SERVES_BREAKFAST` `Place.Field.SERVES_BRUNCH` `Place.Field.SERVES_COCKTAILS` `Place.Field.SERVES_COFFEE` `Place.Field.SERVES_DESSERT` `Place.Field.SERVES_DINNER` `Place.Field.SERVES_LUNCH` `Place.Field.SERVES_VEGETARIAN_FOOD` `Place.Field.SERVES_WINE` `Place.Field.TAKEOUT` For a complete list of fields and their associated SKUs, see [Place Data Fields (New)](https://developers.google.com/maps/documentation/places/android-sdk/data-fields.md.txt).
To set the field list parameter, call the [`setPlaceFields()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setplacefields-listplace.field-placefields) method when building the `SearchByTextRequest` object. - ### Text query The text string on which to search, for example: "restaurant", "123 Main Street", or "best place to visit in San Francisco". The API returns candidate matches based on this string and orders the results based on their perceived relevance. To set the text query parameter, call the [`setTextQuery()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-settextquery-string-textquery) method when building the `SearchByTextRequest` object. > [!NOTE] > **Note:** For best results when searching on a phone number, include the country code followed by a space, and set the [`regionCode`](https://developers.google.com/maps/documentation/places/android-sdk/text-search.md.txt#regioncode) parameter to correspond to the country code. Phone number formats vary by country and the API attempts to return a result for these different formats. For valid phone numbers, Places API (New) supports the [E.164 format](https://en.wikipedia.org/wiki/E.164). Alphabet characters are converted based on the [E.161 keypad > mapping](https://en.wikipedia.org/wiki/E.161).
## Optional parameters Use the [`SearchByTextRequest`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.md.txt) object to specify the optional parameters for your request. - ### Included type Restricts the results to places matching the specified type defined by [Table A](https://developers.google.com/maps/documentation/places/android-sdk/place-types.md.txt#table-a). Only one type may be specified. For example: - `setIncludedType("bar")` - `setIncludedType("pharmacy")` > [!NOTE] > **Note:** The values in [Table B](https://developers.google.com/maps/documentation/places/android-sdk/place-types.md.txt#table-b) are only returned in the response. You cannot use values in [Table B](https://developers.google.com/maps/documentation/places/android-sdk/place-types.md.txt#table-b) as a filter. To set the included type parameter, call the [`setIncludedType()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setincludedtype-string-includedtype) method when building the `SearchByTextRequest` object. - ### Location bias 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 location restriction or location bias, but not both. Think of location restriction as specifying the region which the results must be within, and location bias as specifying the region that the results will likely be within or near --- keeping in mind that when using location bias, results can still be outside of the specified area. > [!NOTE] > **Note:**If you omit both location bias and location restriction, then the API uses IP biasing by default. With IP biasing, the API uses the IP address of the device to bias the results. > [!NOTE] > **Note:** The `locationBias` parameter can be overridden if the `textQuery` contains an explicit location such as `Market in Barcelona`. In this case, `locationBias` is ignored. 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: ```javascript // Define latitude and longitude coordinates of the center of the search area. LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874); // Use the builder to create a SearchByTextRequest object. // Set the radius of the search area to 500.0 meters. final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields) .setMaxResultCount(10) .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build(); ``` - A rectangle is a latitude-longitude viewport, represented as two diagonally opposite low and high points. The low point marks the southwest corner of the rectangle, and the high point represents the northeast corner of the rectangle. 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. - If `low.latitude` \> `high.latitude`, the latitude 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, of a rectangular viewport see [Text Search requests](https://developers.google.com/maps/documentation/places/android-sdk/text-search.md.txt#about_request). To set the location bias parameter, call the [`setLocationBias()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setlocationbias-locationbias-locationbias) method when building the `SearchByTextRequest` object. - ### Location restriction Specifies an area to search. Results outside the specified area are not returned. Specify the region as a rectangular Viewport. See the description of [Location bias](https://developers.google.com/maps/documentation/places/android-sdk/text-search.md.txt#location-bias) for information on defining the Viewport. You can specify location restriction or location bias, but not both. Think of location restriction as specifying the region which the results must be within, and location bias as specifying the region that the results must be near but can be outside the area. > [!NOTE] > **Note:**If you omit both location bias and location restriction, then the API uses IP biasing by default. With IP biasing, the API uses the IP address of the device to bias the results. To set the location restriction parameter, call the [`setLocationRestriction()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setlocationrestriction-locationrestriction-locationrestriction) method when building the `SearchByTextRequest` object. - ### Maximum result count Specifies the maximum number of place results to return. Must be between 1 and 20 (default) inclusive. To set the maximum result count parameter, call the [`setMaxResultCount()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setmaxresultcount-integer-maxresultcount) method when building the `SearchByTextRequest` object. - ### Minimum rating Restricts results to only those whose average user rating is greater than or equal to 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. To set the minimum rating parameter, call the [`setMinRating()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setminrating-double-minrating) method when building the `SearchByTextRequest` object. - ### Open now If `true`, return only those places that are open for business at the time the query is sent. If `false`, return all businesses regardless of open status. Places that don't specify opening hours in the Google Places database are returned if you set this parameter to `false`. To set the open now parameter, call the [`setOpenNow()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setopennow-boolean-opennow) method when building the `SearchByTextRequest` object. - ### Price levels By default, results include places that provide services at all price levels. To restrict results to only include places at particular price levels, you can pass a list of integer values that correspond to the price levels for the places that you want to return: - `1` - Place provides inexpensive services. - `2` - Place provides moderately priced services. - `3` - Place provides expensive services. - `4` - Place provides very expensive services. > [!NOTE] > **Note:** The integer value of `0`, which indicates that the place provides free services, may be included in a response, but cannot be used as a filter value in a request. To set the price levels parameter, call the [`setPriceLevels()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setpricelevels-listinteger-pricelevels) method when building the `SearchByTextRequest` object. - ### Rank preference Specifies how the results are ranked in the response based on the type of query: - For a categorical query such as "Restaurants in New York City", `SearchByTextRequest.RankPreference.RELEVANCE` (rank results by search relevance) is the default. You can set rank preference to `SearchByTextRequest.RankPreference.RELEVANCE` or `SearchByTextRequest.RankPreference.DISTANCE` (rank results by distance). - For a non-categorical query such as "Mountain View, CA", we recommend that you leave the rank preference parameter unset. To set the rank preference parameter, call the [`setRankPreference()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setrankpreference-searchbytextrequest.rankpreference-rankpreference) method when building the `SearchByTextRequest` object. - ### Region code The region code used to format the response, specified as a [two-character CLDR code](https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html) value. This parameter can also have a bias effect on the search results. There is no default value. If the country name of the address field in the response matches the region code, the country code is omitted from address. Most CLDR 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. To set the region code parameter, call the [`setRegionCode()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setregioncode-string-regioncode) method when building the `SearchByTextRequest` object. - ### Strict type filtering Used with the include type parameter. When set to `true`, only places that match the specified types specified by include type are returned. When `false`, the default, the response can contain places that don't match the specified types. To set the strict type filtering parameter, call the [`setStrictTypeFiltering()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/net/SearchByTextRequest.Builder.md.txt#public-abstract-searchbytextrequest.builder-setstricttypefiltering-boolean-stricttypefiltering) method when building the `SearchByTextRequest` object.