Place Class (preview)

Overview

The Place class provides a simpler API for using the Places Library, Maps JavaScript API, and supports modern usage patterns such as Promises.

Get started

Get an API key and enable the required APIs

Before using the Place class preview, you need a Cloud project with a billing account; you must also enable the Maps JavaScript API and Places API. To do this, follow the instructions to enable one or more APIs or SDKs. Note that both APIs must be enabled in the same project in the Cloud Console.

Get an API key

Load the Places Library

To use the functionality contained within the Places Library, you must first load it using the libraries parameter in the Maps JavaScript API script loading URL. For this preview, you must also specify v=beta.

<script async
  src="https://maps.googleapis.com/maps/api/js?v=beta&key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Find a place by text query

Call findPlaceFromQuery to find a place by text query. Use the fields parameter to specify a comma-separated list of one or more place data fields in camel case. Use fields: ['*'] to return all the data for a place (for testing only, not recommended in a production environment).

The following example shows using an async/await pattern to call findPlaceFromQuery and display the results on a map.

TypeScript

let map: google.maps.Map;
let centerCoordinates = { lat: 37.4161493, lng: -122.0812166 };

function initMap() {
    map = new google.maps.Map(document.getElementById('map') as HTMLElement, {
        center: centerCoordinates,
        zoom: 14,
        // ...
    });

    findPlace();
}

async function findPlace() {
    const request = {
        query: 'Sports Page',
        fields: ['displayName', 'location'],
        locationBias: centerCoordinates,
    };

    const { places } = await google.maps.places.Place.findPlaceFromQuery(request);

    if (places.length) {
        const place = places[0];
        const location = place.location as google.maps.LatLng;
        const markerView = new google.maps.marker.AdvancedMarkerView({
            map,
            position: place.location,
            title: place.displayName,
        });

        map.setCenter(location);

    } else {
        console.log('No results');
    }
}
index.ts

JavaScript

let map;
let centerCoordinates = { lat: 37.4161493, lng: -122.0812166 };

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: centerCoordinates,
    zoom: 14,
    // ...
  });
  findPlace();
}

async function findPlace() {
  const request = {
    query: "Sports Page",
    fields: ["displayName", "location"],
    locationBias: centerCoordinates,
  };
  const { places } = await google.maps.places.Place.findPlaceFromQuery(request);

  if (places.length) {
    const place = places[0];
    const location = place.location;
    const markerView = new google.maps.marker.AdvancedMarkerView({
      map,
      position: place.location,
      title: place.displayName,
    });

    map.setCenter(location);
  } else {
    console.log("No results");
  }
}

index.js

Find a place by phone number

Call findPlaceFromPhoneNumber to find a place by phone number. 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. Use the fields parameter to specify a comma-separated list of one or more place data fields in camel case. Use fields: ['*'] to return all the data for a place (for testing only, not recommended in a production environment).

The following example shows using an async/await pattern to call findPlaceFromPhoneNumber and display the results on a map.

TypeScript

async function findPlaceByPhone() {
    const request = {
        phoneNumber: '+1(206)787-5388',
        fields: ['displayName', 'location'],
    }

    const { places } = await google.maps.places.Place.findPlaceFromPhoneNumber(request);

    if (places.length) {
        const place = places[0];
        const markerView = new google.maps.marker.AdvancedMarkerView({
            map,
            position: place.location,
            title: place.displayName,
        });
        console.log(place.displayName);
    } else {
        console.log('No results');
    }
}
index.ts

JavaScript

async function findPlaceByPhone() {
  const request = {
    phoneNumber: "+1(206)787-5388",
    fields: ["displayName", "location"],
  };
  const { places } = await google.maps.places.Place.findPlaceFromPhoneNumber(
    request
  );

  if (places.length) {
    const place = places[0];
    const markerView = new google.maps.marker.AdvancedMarkerView({
      map,
      position: place.location,
      title: place.displayName,
    });

    console.log(place.displayName);
  } else {
    console.log("No results");
  }
}

window.initMap = initMap;

index.js

Get Place Details

If you already have a Place object or place ID, you can call Place.fetchFields to get more details about that place. Use the fields parameter to specify a comma-separated list of one or more place data fields in camel case. Use fields: ['*'] to return all data fields (for testing only, not recommended in a production environment).

TypeScript

async function getPlaceDetails() {
    // Use place ID to create a new Place instance.
    const place = new google.maps.places.Place({
        id: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
        requestedLanguage: 'en', // optional
    });

    // Call fetchFields, passing the desired data fields.
    await place.fetchFields({ fields: ['displayName', 'formattedAddress'] });

    // Show the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
index.ts

JavaScript

async function getPlaceDetails() {
  // Use place ID to create a new Place instance.
  const place = new google.maps.places.Place({
    id: "ChIJN1t_tDeuEmsRUsoyG83frY4",
    requestedLanguage: "en", // optional
  });

  // Call fetchFields, passing the desired data fields.
  await place.fetchFields({ fields: ["displayName", "formattedAddress"] });
  // Show the result
  console.log(place.displayName);
  console.log(place.formattedAddress);
}

index.js

Place data fields

Fields correspond to Place Details results, and are divided into three billing categories: Basic, Contact, and Atmosphere. Basic fields are billed at base rate, and incur no additional charges. Contact and Atmosphere fields are billed at a higher rate. See the pricing sheet for more information. Attributions (html_attributions) are always returned with every call, regardless of whether it has been requested.

The Place class supports the following fields:

Basic Data

Field Place class (v=beta channel only)
Address Component addressComponents
Business Status businessStatus
Formatted Address adrFormatAddress
Location location
Icon icon
Icon Mask Base URI svgIconMaskUri
Icon Background Color iconBackgroundColor
Name displayName
Photo photos
Place ID id
Plus Code plusCode
Type types
URL websiteURI
UTC Offset utcOffsetMinutes
Viewport viewport
Wheelchair Accessible Entrance hasWheelchairAccessibleEntrance

Contact Data Fields

Field Place class (v=beta channel only)
Phone Number nationalPhoneNumber
International Phone Number internationalPhoneNumber
Opening Hours openingHours
Website websiteURI

Atmosphere Data Fields

Field Place class (v=beta channel only)
Curbside Pickup hasCurbsidePickup
Delivery hasDelivery
Dine-in hasDineIn
Price Level priceLevel
Rating rating
Reservable isReservable
Reviews reviews
Serves Beer servesBeer
Serves Breakfast servesBreakfast
Serves Brunch servesBrunch
Serves Dinner servesDinner
Serves Lunch servesLunch
Serves Vegetarian Food servesVegetarianFood
Serves Wine servesWine
Takeout hasTakeout
User Ratings Total userRatingsCount