Find Place (Legacy)

European Economic Area (EEA) developers

A Find Place (Legacy) request takes a text input and returns a place. The input can be any kind of Places text data, such as a name, address, or phone number. The request must be a string. A Find Place (Legacy) request using non-string data such as a lat/lng coordinate or plus code generates an error.

Find Place (Legacy) requests

A Find Place (Legacy) request is an HTTP URL of the following form:

https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters

where output can be either of the following values:

  • json (recommended) indicates output in JavaScript Object Notation (JSON)
  • xml indicates output as XML

Certain parameters are required to initiate a Find Place (Legacy) request. As is standard in URLs, all parameters are separated using the ampersand (&) character.

Required parameters

  • input

    The text string on which to search. This must be a place name, address, or phone number (for example, "123 Main Street" or "City Hall").

  • inputtype

    The type of input. This can be one of either textquery or phonenumber. Phone numbers must be in international format (prefixed by a plus sign ("+"), followed by the country code, then the phone number itself). See E.164 ITU recommendation for more information.

Optional parameters

  • fields

    Caution: Place Search (Legacy) requests and Place Details (Legacy) requests don't return the same fields. Place Search (Legacy) requests return a subset of the fields that are returned by Place Details (Legacy) requests. If the field you want is not returned by Place Search (Legacy), you can use Place Search (Legacy) to get a place_id, then use that Place ID to make a Place Details (Legacy) request. For more information about the fields that are unavailable in a Place Search (Legacy) request, see Places API fields support.

    Use the fields parameter to specify a comma-separated list of place data types to return. For example: fields=formatted_address,name,geometry. Use a forward slash when specifying compound values. For example: opening_hours/open_now.

    Fields are divided into three billing categories: Basic, Contact, and Atmosphere. Basic fields are billed at base rate, and Contact and Atmosphere fields are billed at a higher rate. Basic, Contact, and Atmosphere SKUs are charged in addition to the base SKU (Places Details, Find Place, Nearby Search, or Text Search) for the request that triggered them. For more information, see the pricing sheet.

    Basic

    The Basic category includes the following fields: address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color, name, permanently_closed (deprecated), photo, place_id, plus_code, type, url, utc_offset, vicinity, wheelchair_accessible_entrance.

    Contact

    The Contact category includes the following fields: current_opening_hours, formatted_phone_number, international_phone_number, opening_hours, secondary_opening_hours, website

    Atmosphere

    The Atmosphere category includes the following fields: curbside_pickup, delivery, dine_in, editorial_summary, price_level, rating, reservable, reviews, serves_beer, serves_breakfast, serves_brunch, serves_dinner, serves_lunch, serves_vegetarian_food, serves_wine, takeout, user_ratings_total.

    Note: Attributions, html_attributions, are always returned with every call, regardless of whether the field has been requested.

  • language

    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 language 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

    Prefer results in a specified area, by specifying either a radius plus lat/lng, or two lat/lng pairs representing the points of a rectangle. If this parameter is not specified, the API uses IP address biasing by default.

    • IP bias: Instructs the API to use IP address biasing. Pass the string ipbias (this option has no additional parameters).
    • Circular: A string specifying radius in meters, plus lat/lng in decimal degrees. Use the following format: circle:radius@lat,lng.
    • Rectangular: A string specifying two lat/lng pairs in decimal degrees, representing the south/west and north/east points of a rectangle. Use the following format:rectangle:south,west|north,east. Note that east/west values are wrapped to the range -180, 180, and north/south values are clamped to the range -90, 90.

Find Place (Legacy) examples

The following example shows a Find Place (Legacy) request for "Museum of Contemporary Art Australia", including the photos, formatted_address, name, rating, opening_hours, and geometry fields:

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

The following example shows a Find Place (Legacy) request for "Mongolian Grill", using the locationbias parameter to prefer results within 2000 meters of the specified coordinates:

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

The following example shows a Find Place (Legacy) request for a phone number. Note that the international call prefix "+" has been encoded to %2B so that this request is a compliant URL. Left unencoded, the + prefix would be decoded to a space on the server, resulting in an invalid phone number lookup.

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

Find Place (Legacy) responses

A Find Place (Legacy) response contains only the data types that were specified using the fields parameter, plus html_attributions. The following example shows the response for a Find Place (Legacy) request for "Museum of Contemporary Art Australia", including the formatted_address, geometry, name, opening_hours, photos, rating fields.

JSON

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

PlacesFindPlaceFromTextResponse

Field Required Type Description
required Array<Place>

Contains an array of Place candidates.

Place Search (Legacy) requests return a subset of the fields that are returned by Place Details (Legacy) requests. If the field you want is not returned by Place Search (Legacy), you can use Place Search (Legacy) to get a place_id, then use that Place ID to make a Place Details (Legacy) request.

See Place for more information.
required PlacesSearchStatus

Contains the status of the request, and may contain debugging information to help you track down why the request failed.

See PlacesSearchStatus for more information.

optional string

When the service returns a status code other than OK<, there may be an additional error_message field within the response object. This field contains more detailed information about the reasons behind the given status code. This field is not always returned, and its content is subject to change.

optional Array<string>

When the service returns additional information about the request specification, there may be an additional info_messages field within the response object. This field is only returned for successful requests. It may not always be returned, and its content is subject to change.

PlacesSearchStatus

Status codes returned by service.

  • OK indicating the API request was successful.
  • ZERO_RESULTS indicating that the search was successful but returned no results. This may occur if the search was passed a latlng in a remote location.
  • INVALID_REQUEST indicating the API request was malformed, generally due to missing required query parameter (location or radius).
  • OVER_QUERY_LIMIT indicating any of the following:
    • You have exceeded the QPS limits.
    • Billing has not been enabled on your account.
    • The monthly $200 credit, or a self-imposed usage cap, has been exceeded.
    • The provided method of payment is no longer valid (for example, a credit card has expired).
    See the Maps FAQ for more information about how to resolve this error.
  • REQUEST_DENIED indicating that your request was denied, generally because:
    • The request is missing an API key.
    • The key parameter is invalid.
  • UNKNOWN_ERROR indicating an unknown error.

Place

Place Search responses return the following subset of the Place fields. Not all attributes are available for all place types. To retrieve fields that Place Search doesn't return, such as address_components, formatted_phone_number, reviews, or website, pass the returned place_id in a Place Details (Legacy) request. For field availability and pricing tiers across endpoints, see Place Data Fields (Legacy).

Field Type Description
business_status string Indicates the operational status of the place, if it's a business: OPERATIONAL, CLOSED_TEMPORARILY, or CLOSED_PERMANENTLY. Omitted if no status data exists.
formatted_address string The human-readable address of this place. Returned by Text Search (Legacy) and Find Place (Legacy). Don't parse the formatted address programmatically; request address_components in Place Details (Legacy) instead.
geometry Geometry Contains the geocoded location with lat and lng coordinates, and the preferred viewport with northeast and southwest bounds.
icon string The URL of a suggested icon that you can display when indicating this result on a map.
icon_background_color string The default hexadecimal color code for the place's category.
icon_mask_base_uri string The base URL of a recommended icon, without the SVG or PNG file type extension.
name string The human-readable name for the returned result. For establishment results, this value is usually the canonicalized business name.
opening_hours PlaceOpeningHours Opening hours information. Place Search endpoints return only the open_now boolean subfield; request opening_hours in Place Details (Legacy) for periods and weekday_text.
permanently_closed boolean Deprecated: Use business_status to check the operational status of a business.
photos Array<PlacePhoto> An array of PlacePhoto objects, each containing a photo_reference, height, width, and html_attributions. For usage details, see Place Photos (Legacy).
place_id string A textual identifier that uniquely identifies a place. Pass this ID in the place_id parameter of a Place Details (Legacy) request. See the place ID overview.
plus_code PlusCode An encoded location reference derived from latitude and longitude coordinates, containing a global_code and an optional compound_code.
price_level integer The price level of the place on a scale from 0 to 4, from least expensive to most expensive. See price_level.
rating number The place's rating, from 1.0 to 5.0, based on aggregated user reviews.
reference string Deprecated: Use place_id instead.
scope string Deprecated: Indicates the scope of the place_id, which is always GOOGLE. Returned by Nearby Search (Legacy).
types Array<string> An array of feature types describing the given result. See Place Types (Legacy).
user_ratings_total integer The total number of ratings, with or without review text, for this place.
vicinity string A simplified address for the place, including the street name, street number, and locality, without the state or province, postal code, or country. Returned by Nearby Search (Legacy).