地点类(预览版)

概览

地点类提供了一个更简单的 API,用于使用 Maps JavaScript API 地点库,还支持 promise 等新型使用模式。

开始使用

获取 API 密钥并启用所需的 API

在使用地点类预览版之前,您需要有一个设置了结算帐号的 Cloud 项目;您还必须启用 Maps JavaScript API 和 Places API。为此,请按照说明启用一个或多个 API 或 SDK。请注意,必须在 Cloud 控制台中针对同一项目启用这两个 API。

获取 API 密钥

加载地点库

若要使用地点库中包含的功能,您必须先在 Maps JavaScript API 脚本加载网址中使用 libraries 参数加载该库。对于此预览版,您还必须指定 v=beta

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

通过文本查询查找地点

调用 findPlaceFromQuery 即可通过文本查询查找地点。您可以使用 fields 参数指定一个逗号分隔列表,其中包含一个或多个采用驼峰式大小写形式的地点数据字段。使用 fields: ['*'] 可返回某一地点的所有数据(仅供测试使用,不建议在生产环境中使用)。

以下示例展示了如何使用 async/await 模式调用 findPlaceFromQuery 并在地图上显示结果。

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');
    }
}

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");
  }
}

通过电话号码查找地点

调用 findPlaceFromPhoneNumber 即可通过电话号码查找地点。电话号码必须采用国际电话号码格式(以加号 [“+”] 为前缀,后跟国家/地区代码,然后是电话号码本身)。如需了解详情,请参阅 E.164 ITU 建议书。您可以使用 fields 参数指定一个逗号分隔列表,其中包含一个或多个采用驼峰式大小写形式的地点数据字段。使用 fields: ['*'] 可返回某一地点的所有数据(仅供测试使用,不建议在生产环境中使用)。

以下示例展示了如何使用 async/await 模式调用 findPlaceFromPhoneNumber 并在地图上显示结果。

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');
    }
}

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;

获取地点详情

如果您已有 Place 对象或地点 ID,则可以调用 Place.fetchFields 获取有关该地点的更多详情。您可以使用 fields 参数指定一个逗号分隔列表,其中包含一个或多个采用驼峰式大小写形式的地点数据字段。使用 fields: ['*'] 可返回所有数据字段(仅供测试使用,不建议在生产环境中使用)。

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);
}

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);
}

地点数据字段

这些字段与“地点详情”结果相对应,而且分为三个结算类别:基本、联系人和氛围。“基本”字段按基本费率结算,且不会产生额外费用。“联系人”和“氛围”字段按更高的费率结算。如需了解详情,请参阅定价表。无论是否针对提供方说明发出请求,每次调用都会返回提供方 (html_attributions) 说明。

地点类支持以下字段:

基本数据

字段 地点类(仅限 Beta 渠道版)
地址组成部分 addressComponents
商家状态 businessStatus
设置了格式的地址 adrFormatAddress
位置 location
图标 icon
图标遮罩基本 URI svgIconMaskUri
图标背景颜色 iconBackgroundColor
名称 displayName
照片 photos
地点 ID id
Plus Code plusCode
类型 types
网址 websiteURI
UTC 时差 utcOffsetMinutes
视口 viewport
无障碍入口 hasWheelchairAccessibleEntrance

联系人数据字段

字段 地点类(仅限 Beta 渠道版)
电话号码 nationalPhoneNumber
国际电话号码 internationalPhoneNumber
营业时间 openingHours
网站 websiteURI

氛围数据字段

字段 地点类(仅限 Beta 渠道版)
路边自提 hasCurbsidePickup
送餐 hasDelivery
堂食 hasDineIn
价格水平 priceLevel
评分 rating
可预订 isReservable
评价 reviews
供应啤酒 servesBeer
供应早餐 servesBreakfast
供应早午餐 servesBrunch
供应晚餐 servesDinner
供应午餐 servesLunch
供应素食 servesVegetarianFood
供应葡萄酒 servesWine
外带 hasTakeout
用户评分总计 userRatingsCount