Text Search (New)

AI-generated Key Takeaways

outlined_flag

• Google Maps Platform's Text Search functionality enables finding places using text queries, like "pizza in New York", and is useful for ambiguous addresses and business searches.

• Text Search uses the Places API (New) and requires a text query, with optional location bias and filters, returning an array of GMSPlace objects.

• iOS implementation involves creating a GMSPlaceSearchByTextRequest and executing the search using GMSPlacesClient searchByTextWithRequest:callback:.

• You can determine if a place is open using the GMSPlacesClient isOpenWithRequest:callback: method with a GMSPlaceIsOpenWithRequest object.

• When displaying information from GMSPlacesClient, ensure your app displays necessary attributions as outlined in the documentation.

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, Text Search (New) supports refining queries using optional parameters for better results.

Get a list of places by text search

Make a Text Search request by calling GMSPlacesClient searchByTextWithRequest:, passing a GMSPlaceSearchByTextRequest object that defines the request parameters and a callback method, of type GMSPlaceSearchByTextResultCallback, to handle the response.

The GMSPlaceSearchByTextRequest object specifies all of the required and optional parameters for the request. The required parameters include:

• The list of fields to return in the GMSPlace object, also called the field mask, as defined by GMSPlaceProperty. If you don't specify at least one field in the field list, or if you omit the field list, then the call returns an error.
• The text query.

This example text search request specifies that the response GMSPlace objects contain the place name and place ID for each GMSPlace object in the search results. It also filters the response to only return places of type "restaurant".

let restriction = GMSPlaceRectangularLocationOption(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

Text Search responses

The Text Search API returns an array of matches in the form of GMSPlace objects, with one GMSPlace object per matching place.

Get open status

The GMSPlacesClient object contains a member function called isOpenWithRequest (isOpenRequest in Swift and isPlaceOpenRequest in GooglePlacesSwift) that returns a response indicating whether the place is currently open, based on the time specified in the call.

This method takes a single argument of type GMSPlaceIsOpenWithRequest that contains:

• A GMSPlace object, or a string specifying a place ID. For more information on creating the Place object with the necessary fields, see Place details.
  
• An optional NSDate (Obj-C) or Date (Swift) object specifying the time you would like to check. If no time is specified, the default is now.
• A GMSPlaceOpenStatusResponseCallback method to handle the response.
>

The GMSPlaceIsOpenWithRequest method requires the following fields to be set in the GMSPlace object:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

If these fields are not provided in the Place object, or if you pass a place ID, the method uses GMSPlacesClient GMSFetchPlaceRequest: to fetch them.

isOpenWithRequest response

isOpenWithRequest returns a GMSPlaceIsOpenResponse object containing a boolean value named status that indicates whether the business is open, closed, or if the status is unknown.

Billing for isOpenWithRequest

• The GMSPlacePropertyUTCOffsetMinutes and GMSPlacePropertyBusinessStatus fields are charged under the Basic Data SKU. The rest of the Opening Hours are charged under the Place Details Enterprise SKU.
• If your GMSPlace object already has these fields from a previous request, you won't be charged again.

Example: Make a GMSPlaceIsOpenWithRequest request

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }
        

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

Required parameters

Use the GMSPlaceSearchByTextRequest object to specify the required parameters for the search.

• Field list

  Specify which place data properties to return. Pass a list of GMSPlace properties specifying the data fields to return. If you omit the field mask, the request will return an error.

  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:

    GMSPlacePropertyPlaceID

  • The following fields trigger the Text Search Pro SKU:

    GMSPlacePropertyAddressComponents
GMSPlacePropertyBusinessStatus
GMSPlacePropertyCoordinate
GMSPlacePropertyFormattedAddress
GMSPlacePropertyIconBackgroundColor
GMSPlacePropertyIconImageURL
GMSPlacePropertyName
GMSPlacePropertyPhotos
GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyViewport
GMSPlacePropertyWheelchairAccessibleEntrance

  • The following fields trigger the Text Search Enterprise SKU:

    GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
GMSPlacePropertyPhoneNumber
GMSPlacePropertyPriceLevel
GMSPlacePropertyRating
GMSPlacePropertyOpeningHours
GMSPlacePropertyUserRatingsTotal
GMSPlacePropertyWebsite

  • The following fields trigger the Text Search Enterprise Plus SKU:

    GMSPlacePropertyCurbsidePickup
GMSPlacePropertyDelivery
GMSPlacePropertyDineIn
GMSPlacePropertyEditorialSummary
GMSPlacePropertyReservable
GMSPlacePropertyReviews
GMSPlacePropertyServesBeer
GMSPlacePropertyServesBreakfast
GMSPlacePropertyServesBrunch
GMSPlacePropertyServesDinner
GMSPlacePropertyServesLunch
GMSPlacePropertyServesVegetarianFood
GMSPlacePropertyServesWine
GMSPlacePropertyTakeout

• textQuery

  The text string on which to search, for example: "restaurant", "123 Main Street", or "best place to visit in San Francisco".

Optional parameters

Use the GMSPlaceSearchByTextRequest object to specify the optional parameters for the search.

• includedType

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

  • let request = SearchByTextRequest()
request.includedType = "bar"
  • let request = SearchByTextRequest()
request.includedType = "pharmacy"

• isOpenNow

  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.

• isStrictTypeFiltering

  Used with the includeType parameter. When set to true, only places that match the specified types specified by includeType are returned. When false, the default, the response can contain places that don't match the specified types.

• 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. The default radius is 0.0. For example:

    let request = SearchByTextRequest()
    request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

  • 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.

• 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.

• maxResultCount

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

• minRating

  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.

• 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 values defined by PriceLevel.

  For example:

      let request = SearchByTextRequest()
      request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

• rankPreference

  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", .relevance (rank results by search relevance) is the default. You can set rankPreference to .relevance or .distance (rank results by distance).
  • For a non-categorical query such as "Mountain View, CA", we recommend that you leave rankPreference unset.

• regionCode

  The region code used to format the response, specified as a two-character CLDR code 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.

• shouldIncludePureServiceAreaBusinesses

  If true, returns pure service area businesses in the search results. A pure service area business is a business that visits or delivers to customers directly, but does not serve customers at their business address.

  For example:

  Places Swift SDK

  let request = SearchByTextRequest()
  request.shouldIncludePureServiceAreaBusinesses = true

  Swift

  let request = SearchByTextRequest()
  request.shouldIncludePureServiceAreaBusinesses: true

  Objective-C

  GMSPlaceSearchByTextRequest *request =
      [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
  request.shouldIncludePureServiceAreaBusinesses = YES;

Display attributions in your app

When your app displays information obtained from GMSPlacesClient, such as photos and reviews, the app must also display the required attributions.

For example, the reviews property of the GMSPlacesClient object contains an array of up to five GMSPlaceReview objects. Each GMSPlaceReview object can contain attributions and author attributions. If you display the review in your app, then you must also display any attribution or author attribution.

For more information, see the documentation on attributions.