Thư viện địa điểm

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Tổng quan

Các hàm trong Thư viện Địa điểm, Maps JavaScript API cho phép ứng dụng của bạn tìm kiếm các địa điểm (được xác định trong API này là cơ sở lưu trú, vị trí địa lý hoặc địa điểm nổi bật) nằm trong một khu vực xác định, chẳng hạn như ranh giới của bản đồ hoặc xung quanh một điểm cố định.

Places API cung cấp một tính năng tự động hoàn thành mà bạn có thể dùng để cung cấp cho các ứng dụng của mình hành vi tìm kiếm dự đoán của trường tìm kiếm Google Maps. Khi người dùng bắt đầu nhập địa chỉ, tính năng tự động hoàn thành sẽ điền phần còn lại. Để biết thêm thông tin, hãy xem tài liệu về tính năng tự động hoàn thành.

Bắt đầu

Nếu chưa quen với Maps JavaScript API hoặc JavaScript, bạn nên xem lại JavaScript và Lấy khoá API trước khi bắt đầu.

Tải thư viện

Dịch vụ Địa điểm là một thư viện độc lập, tách biệt với mã API Maps JavaScript chính. Để sử dụng chức năng có trong thư viện này, trước tiên, bạn phải tải thư viện này bằng tham số libraries trong URL khởi động Maps API:

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

Hãy xem bài viết Tổng quan về thư viện để biết thêm thông tin.

Thêm Places API vào danh sách hạn chế API của khoá API

Việc áp dụng các quy tắc hạn chế đối với API cho khoá sẽ giới hạn việc sử dụng khoá API cho một hoặc nhiều API hoặc SDK. Các yêu cầu gửi đến một API hoặc SDK được liên kết với khoá API sẽ được xử lý. Các yêu cầu đến một API hoặc SDK không liên kết với khoá API sẽ không thành công. Cách hạn chế sử dụng một khoá API với Thư viện địa điểm, Maps JavaScript API:
  1. Chuyển đến Bảng điều khiển Google Cloud.
  2. Nhấp vào trình đơn thả xuống dự án rồi chọn dự án có chứa khoá API mà bạn muốn bảo mật.
  3. Nhấp vào nút trình đơn rồi chọn Nền tảng Google Maps > Thông tin xác thực.
  4. Trên trang Thông tin xác thực, hãy nhấp vào tên của khoá API mà bạn muốn bảo mật.
  5. Trên trang Hạn chế và đổi tên khoá API, hãy đặt các quy tắc hạn chế:
    • Các quy định hạn chế đối với API
      • Chọn Hạn chế cho khoá.
      • Nhấp vào Chọn API rồi chọn cả Maps JavaScript API và Places API.
        (Nếu không thấy một trong hai API này, bạn cần bật API đó.)
  6. Nhấp vào LƯU.

Hạn mức sử dụng và chính sách

Hạn mức

Places Library dùng chung hạn mức sử dụng với Places API như mô tả trong tài liệu Giới hạn sử dụng của Places API.

Chính sách

Việc sử dụng Thư viện địa điểm, Maps JavaScript API phải tuân thủ các chính sách được mô tả cho Places API.

Tìm kiếm địa điểm

Với dịch vụ Places, bạn có thể thực hiện các loại tìm kiếm sau:

Thông tin được trả về có thể bao gồm các cơ sở (chẳng hạn như nhà hàng, cửa hàng và văn phòng), cũng như kết quả "mã hoá địa lý" cho biết địa chỉ, khu vực chính trị (chẳng hạn như thị trấn và thành phố) và các địa điểm khác mà người dùng quan tâm.

Tìm yêu cầu về Địa điểm

Yêu cầu Tìm địa điểm cho phép bạn tìm kiếm một địa điểm bằng cụm từ tìm kiếm dạng văn bản hoặc số điện thoại. Có hai loại yêu cầu Tìm địa điểm:

Tìm địa điểm bằng cụm từ tìm kiếm

Hàm Find Place from Query nhận một văn bản đầu vào và trả về một địa điểm. Đầu vào có thể là bất kỳ loại dữ liệu nào về Địa điểm, ví dụ: tên hoặc địa chỉ doanh nghiệp. Để thực hiện yêu cầu Tìm địa điểm theo cụm từ tìm kiếm, hãy gọi phương thức findPlaceFromQuery() của PlacesService. Phương thức này nhận các tham số sau:

  • query (bắt buộc) Chuỗi văn bản để tìm kiếm, ví dụ: "nhà hàng" hoặc "123 Main Street". Đây phải là tên địa điểm, địa chỉ hoặc danh mục của cơ sở. Mọi loại dữ liệu đầu vào khác đều có thể tạo ra lỗi và không đảm bảo trả về kết quả hợp lệ. Places API sẽ trả về các kết quả trùng khớp có thể dựa trên chuỗi này và sắp xếp các kết quả theo mức độ liên quan mà người dùng cảm nhận được.
  • fields (bắt buộc) Một hoặc nhiều trường chỉ định các loại dữ liệu Địa điểm cần trả về.
  • locationBias (không bắt buộc) Toạ độ xác định khu vực cần tìm kiếm. Đây có thể là một trong những trạng thái sau:

Bạn cũng phải truyền một phương thức gọi lại đến findPlaceFromQuery() để xử lý đối tượng kết quả và phản hồi google.maps.places.PlacesServiceStatus.

Ví dụ sau đây minh hoạ một lệnh gọi đến findPlaceFromQuery(), tìm kiếm "Bảo tàng Nghệ thuật Đương đại Úc" và bao gồm các trường name và geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 Xem ví dụ

Tìm địa điểm bằng số điện thoại

Hàm Find Place from Phone Number nhận một số điện thoại và trả về một địa điểm. Để đưa ra yêu cầu Tìm địa điểm qua số điện thoại, hãy gọi phương thức findPlaceFromPhoneNumber() của PlacesService. Phương thức này nhận các tham số sau:

  • phoneNumber (bắt buộc) Số điện thoại ở định dạng E.164.
  • fields (bắt buộc) Một hoặc nhiều trường chỉ định các loại dữ liệu Địa điểm cần trả về.
  • locationBias (không bắt buộc) Toạ độ xác định khu vực cần tìm kiếm. Đây có thể là một trong những trường hợp sau:

Bạn cũng phải truyền một phương thức gọi lại đến findPlaceFromPhoneNumber() để xử lý đối tượng kết quả và phản hồi google.maps.places.PlacesServiceStatus.

Trường (phương thức Tìm địa điểm)

Sử dụng tham số fields để chỉ định một mảng các loại dữ liệu địa điểm cần trả về. Ví dụ: fields: ['formatted_address', 'opening_hours', 'geometry']. Sử dụng dấu chấm khi chỉ định các giá trị kết hợp. Ví dụ: opening_hours.weekday_text.

Các trường tương ứng với kết quả Tìm kiếm địa điểm và được chia thành 3 danh mục thanh toán: Cơ bản, Thông tin liên hệ và Bầu không khí. Các trường cơ bản được tính theo mức giá cơ sở và không phát sinh thêm phí. Các trường Contact (Liên hệ) và Atmosphere (Bầu không khí) được tính phí ở mức cao hơn. Hãy xem bảng giá để biết thêm thông tin. Thuộc tính (html_attributions) luôn được trả về trong mọi lệnh gọi, bất kể bạn có yêu cầu trường này hay không.

Cơ bản

Danh mục Cơ bản bao gồm các trường sau:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (không dùng nữa), photos, place_id, plus_code, types

Thông tin liên hệ

Danh mục Liên hệ bao gồm trường sau: opening_hours
(không dùng nữa trong Thư viện địa điểm, Maps JavaScript API. Sử dụng yêu cầu Chi tiết về địa điểm để nhận kết quả opening_hours).

Khí quyển

Danh mục Atmosphere bao gồm các trường sau: price_level, rating, user_ratings_total

Mỗi phương thức findPlaceFromQuery() và findPlaceFromPhoneNumber() đều lấy cùng một tập hợp các trường và có thể trả về cùng các trường trong phản hồi tương ứng.

Đặt độ lệch vị trí (phương thức Tìm địa điểm)

Sử dụng tham số locationBias để ưu tiên kết quả Tìm địa điểm ở một khu vực cụ thể. Bạn có thể đặt locationBias theo những cách sau:

Thiên vị kết quả cho một khu vực cụ thể:

locationBias: {lat: 37.402105, lng: -122.081974}

Xác định một vùng hình chữ nhật để tìm kiếm:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

Bạn cũng có thể sử dụng LatLngBounds.

Xác định bán kính để tìm kiếm (tính bằng mét), tập trung vào một khu vực cụ thể:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Yêu cầu tìm kiếm lân cận

Tính năng Tìm kiếm lân cận cho phép bạn tìm kiếm địa điểm trong một khu vực cụ thể theo từ khoá hoặc loại. Yêu cầu Tìm kiếm lân cận phải luôn có vị trí. Bạn có thể chỉ định vị trí theo một trong hai cách:

  • a LatLngBounds.
  • một vùng hình tròn được xác định là tổ hợp của thuộc tính location – chỉ định tâm của hình tròn dưới dạng một đối tượng LatLng – và bán kính, được đo bằng mét.

Bạn có thể bắt đầu tìm kiếm Địa điểm lân cận bằng cách gọi phương thức nearbySearch() của PlacesService. Phương thức này sẽ trả về một mảng các đối tượng PlaceResult. Xin lưu ý rằng phương thức nearbySearch() sẽ thay thế phương thức search() kể từ phiên bản 3.9.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

Phương thức này sử dụng một yêu cầu có các trường sau:

  • Một trong hai trường hợp sau:
    • bounds, phải là một đối tượng google.maps.LatLngBounds xác định vùng tìm kiếm hình chữ nhật. Khoảng cách đường chéo tối đa được hỗ trợ cho vùng ranh giới là khoảng 100.000 mét.
    • location và radius; location lấy một đối tượng google.maps.LatLng, còn radius lấy một số nguyên đơn giản, biểu thị bán kính của vòng tròn theo mét. Bán kính tối đa được phép là 50.000 mét. Xin lưu ý rằng khi đặt rankBy thành DISTANCE, bạn phải chỉ định location nhưng không thể chỉ định radius hoặc bounds.
  • keyword (không bắt buộc) – Một cụm từ cần khớp với tất cả các trường có sẵn, bao gồm nhưng không giới hạn ở tên, loại và địa chỉ, cũng như các bài đánh giá của khách hàng và nội dung khác của bên thứ ba.
  • minPriceLevel và maxPriceLevel (không bắt buộc) – Chỉ giới hạn kết quả ở những địa điểm trong phạm vi đã chỉ định. Các giá trị hợp lệ nằm trong khoảng từ 0 (rẻ nhất) đến 4 (đắt nhất), bao gồm cả hai giá trị này.
  • name Không dùng nữa. Tương đương với keyword. Các giá trị trong trường này được kết hợp với các giá trị trong trường keyword và được truyền dưới dạng một phần của cùng một chuỗi tìm kiếm.
  • openNow (không bắt buộc) – Giá trị boolean, cho biết rằng dịch vụ Places chỉ nên trả về những địa điểm đang mở cửa vào thời điểm gửi truy vấn. Những địa điểm không chỉ định giờ mở cửa trong cơ sở dữ liệu Google Places sẽ không được trả về nếu bạn thêm tham số này vào truy vấn. Việc đặt openNow thành false không có hiệu lực.
  • rankBy (không bắt buộc) – Chỉ định thứ tự liệt kê kết quả. Các giá trị có thể sử dụng là:
    • google.maps.places.RankBy.PROMINENCE (mặc định). Lựa chọn này sắp xếp kết quả dựa trên mức độ quan trọng. Thứ hạng sẽ ưu tiên những địa điểm nổi bật trong bán kính đã đặt hơn những địa điểm lân cận phù hợp nhưng ít nổi bật hơn. Mức độ nổi bật có thể bị ảnh hưởng bởi thứ hạng của một địa điểm trong chỉ mục của Google, mức độ phổ biến trên toàn cầu và các yếu tố khác. Khi bạn chỉ định google.maps.places.RankBy.PROMINENCE, tham số radius là bắt buộc.
    • google.maps.places.RankBy.DISTANCE. Lựa chọn này sắp xếp kết quả theo thứ tự tăng dần dựa trên khoảng cách từ location đã chỉ định (bắt buộc). Xin lưu ý rằng bạn không thể chỉ định bounds và/hoặc radius tuỳ chỉnh nếu bạn chỉ định RankBy.DISTANCE. Khi chỉ định RankBy.DISTANCE, bạn phải cung cấp một hoặc nhiều trong số keyword, name hoặc type.
  • type – Hạn chế kết quả ở những địa điểm phù hợp với loại được chỉ định. Bạn chỉ có thể chỉ định một loại (nếu bạn cung cấp nhiều loại, thì tất cả các loại sau mục nhập đầu tiên sẽ bị bỏ qua). Xem danh sách các loại được hỗ trợ.

Bạn cũng phải truyền một phương thức gọi lại đến nearbySearch() để xử lý đối tượng kết quả và phản hồi google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433, 151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: 500,
    type: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

Xem ví dụ

Yêu cầu tìm kiếm bằng văn bản

Dịch vụ Tìm kiếm bằng văn bản của Google Places là một dịch vụ web trả về thông tin về một nhóm địa điểm dựa trên một chuỗi, chẳng hạn như "pizza ở New York" hoặc "cửa hàng giày gần Ottawa". Dịch vụ này sẽ phản hồi bằng một danh sách các địa điểm khớp với chuỗi văn bản và mọi thiên kiến về vị trí đã được đặt. Phản hồi tìm kiếm sẽ bao gồm danh sách các địa điểm. Bạn có thể gửi yêu cầu Chi tiết về địa điểm để biết thêm thông tin về bất kỳ địa điểm nào trong phản hồi.

Các lượt tìm kiếm văn bản được bắt đầu bằng lệnh gọi đến phương thức textSearch() của PlacesService.

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

Phương thức này sử dụng một yêu cầu có các trường sau:

  • query (bắt buộc) Chuỗi văn bản dùng để tìm kiếm, ví dụ: "nhà hàng" hoặc "123 Main Street". Đây phải là tên địa điểm, địa chỉ hoặc danh mục của các cơ sở. Mọi loại dữ liệu đầu vào khác đều có thể tạo ra lỗi và không đảm bảo trả về kết quả hợp lệ. Dịch vụ Places sẽ trả về các kết quả trùng khớp đề xuất dựa trên chuỗi này và sắp xếp các kết quả theo mức độ liên quan mà người dùng cảm nhận được. Tham số này trở thành tham số không bắt buộc nếu tham số type cũng được dùng trong yêu cầu tìm kiếm.
  • Không bắt buộc:
    • openNow – Một giá trị boolean, cho biết rằng dịch vụ Places chỉ nên trả về những địa điểm đang mở cửa kinh doanh tại thời điểm gửi truy vấn. Những địa điểm không chỉ định giờ mở cửa trong cơ sở dữ liệu Google Places sẽ không được trả về nếu bạn thêm tham số này vào truy vấn. Việc đặt openNow thành false không có hiệu lực.
    • minPriceLevel và maxPriceLevel – Chỉ hiển thị kết quả là những địa điểm có mức giá được chỉ định. Các giá trị hợp lệ nằm trong khoảng từ 0 (giá cả phải chăng nhất) đến 4 (đắt nhất).
    • Một trong hai trường hợp sau:
      • bounds, phải là một đối tượng google.maps.LatLngBounds xác định vùng tìm kiếm hình chữ nhật. Khoảng cách đường chéo tối đa được hỗ trợ cho vùng ranh giới là khoảng 100.000 mét.
      • location và radius – Bạn có thể thiên vị kết quả cho một vòng tròn cụ thể bằng cách truyền tham số location và radius. Thao tác này sẽ hướng dẫn dịch vụ Địa điểm ưu tiên hiển thị kết quả trong vòng tròn đó. Kết quả bên ngoài khu vực được xác định vẫn có thể xuất hiện. Vị trí nhận một đối tượng google.maps.LatLng và bán kính nhận một số nguyên đơn giản, đại diện cho bán kính của vòng tròn tính bằng mét. Bán kính tối đa được phép là 50.000 mét.
    • type – Hạn chế kết quả ở những địa điểm phù hợp với loại được chỉ định. Bạn chỉ có thể chỉ định một loại (nếu bạn cung cấp nhiều loại, thì tất cả các loại sau mục nhập đầu tiên sẽ bị bỏ qua). Hãy xem danh sách các loại được hỗ trợ.

Bạn cũng phải truyền một phương thức gọi lại đến textSearch() để xử lý đối tượng kết quả và phản hồi google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: 500,
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Phản hồi tìm kiếm

Mã trạng thái

Đối tượng phản hồi PlacesServiceStatus chứa trạng thái của yêu cầu và có thể chứa thông tin gỡ lỗi để giúp bạn theo dõi lý do khiến yêu cầu về địa điểm không thành công. Các giá trị trạng thái có thể là:

  • INVALID_REQUEST: Yêu cầu này không hợp lệ.
  • OK: Phản hồi chứa một kết quả hợp lệ.
  • OVER_QUERY_LIMIT: Trang web đã vượt quá hạn mức yêu cầu.
  • REQUEST_DENIED: Trang web không được phép sử dụng PlacesService.
  • UNKNOWN_ERROR: Yêu cầu PlacesService không xử lý được do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.
  • ZERO_RESULTS: Không tìm thấy kết quả nào cho yêu cầu này.

Kết quả tìm kiếm địa điểm

Các hàm findPlace(), nearbySearch() và textSearch() trả về một mảng các đối tượng PlaceResult.

Mỗi đối tượng PlaceResult có thể bao gồm các thuộc tính sau:

  • business_status cho biết trạng thái hoạt động của địa điểm, nếu đó là một doanh nghiệp. Thuộc tính này có thể chứa một trong các giá trị sau:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Nếu không có dữ liệu, business_status sẽ không được trả về.
  • formatted_address là một chuỗi chứa địa chỉ mà con người có thể đọc được của địa điểm này. Thuộc tính formatted_address chỉ được trả về cho Tìm kiếm bằng văn bản.

    Địa chỉ này thường tương đương với địa chỉ bưu điện. Xin lưu ý rằng một số quốc gia (chẳng hạn như Vương quốc Anh) không cho phép phân phối địa chỉ bưu chính thực do các quy định hạn chế về việc cấp phép.

    Địa chỉ được định dạng bao gồm một hoặc nhiều thành phần địa chỉ. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "8th Avenue" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang của Hoa Kỳ).

    Không phân tích cú pháp địa chỉ được định dạng theo phương thức lập trình. Thay vào đó, bạn nên sử dụng các thành phần địa chỉ riêng lẻ mà phản hồi API bao gồm ngoài trường địa chỉ được định dạng.

  • geometry: Thông tin liên quan đến hình học của địa điểm. Trong đó có:
    • location cung cấp vĩ độ và kinh độ của địa điểm.
    • viewport xác định khung nhìn ưu tiên trên bản đồ khi xem địa điểm này.
  • permanently_closed (không dùng nữa) là một cờ boolean cho biết liệu địa điểm đã đóng cửa vĩnh viễn hay tạm thời (giá trị true). Đừng dùng permanently_closed. Thay vào đó, hãy sử dụng business_status để biết trạng thái hoạt động của doanh nghiệp.
  • plus_code (xem Mã vị trí mở và plus code) là một thông tin tham chiếu vị trí được mã hoá, bắt nguồn từ toạ độ vĩ độ và kinh độ, đại diện cho một khu vực: 1/8000 độ theo 1/8000 độ (khoảng 14 m x 14 m tại đường xích đạo) hoặc nhỏ hơn. Bạn có thể dùng plus code thay cho địa chỉ đường phố ở những nơi không có địa chỉ đường phố (nơi các toà nhà không được đánh số hoặc đường phố không được đặt tên).

    Mã cộng được định dạng dưới dạng mã toàn cầu và mã kết hợp:

    • global_code là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên (849VCWC8+R9).
    • compound_code là mã địa phương có từ 6 ký tự trở lên và có vị trí cụ thể (CWC8+R9, Mountain View, California, Hoa Kỳ). Không phân tích cú pháp nội dung này theo cách lập trình.
    Thông thường, cả mã toàn cầu và mã kết hợp đều được trả về. Tuy nhiên, nếu kết quả ở một vị trí từ xa (ví dụ: đại dương hoặc sa mạc), thì chỉ mã toàn cầu mới có thể được trả về.
  • html_attributions: Một mảng các thông tin ghi nhận quyền tác giả mà bạn nên hiển thị khi hiển thị kết quả tìm kiếm. Mỗi mục trong mảng chứa văn bản HTML cho một thông tin ghi nhận quyền tác giả. Lưu ý: Đây là thông tin tổng hợp của tất cả các thông tin ghi nhận quyền tác giả cho toàn bộ kết quả tìm kiếm. Do đó, tất cả các đối tượng PlaceResult trong phản hồi đều chứa danh sách phân bổ giống hệt nhau.
  • icon trả về URL cho một biểu tượng PNG có màu với kích thước 71px x 71px.
  • icon_mask_base_uri trả về URL cơ sở cho một biểu tượng không có màu, trừ đuôi .svg hoặc .png.
  • icon_background_color trả về mã màu HEX mặc định cho danh mục của địa điểm.
  • name: Tên của địa điểm.
  • opening_hours có thể chứa những thông tin sau:
    • open_now là một giá trị boolean cho biết địa điểm có đang mở cửa tại thời điểm hiện tại hay không (Không dùng nữa trong Thư viện Địa điểm, Maps JavaScript API, thay vào đó hãy dùng utc_offset_minutes).
  • place_id là giá trị nhận dạng dạng văn bản giúp xác định một địa điểm duy nhất. Để truy xuất thông tin về địa điểm, hãy truyền giá trị nhận dạng này trong yêu cầu Chi tiết về địa điểm. Tìm hiểu thêm về cách tham chiếu một địa điểm bằng mã địa điểm.
  • rating chứa điểm xếp hạng của địa điểm, từ 0.0 đến 5.0, dựa trên bài đánh giá tổng hợp của người dùng.
  • types Một mảng các loại cho địa điểm này (ví dụ: ["political", "locality"] hoặc ["restaurant", "lodging"]). Mảng này có thể chứa nhiều giá trị hoặc có thể trống. Chúng tôi có thể giới thiệu các giá trị mới mà không cần thông báo trước. Xem danh sách các loại được hỗ trợ.
  • vicinity: Địa chỉ đơn giản của địa điểm, bao gồm tên đường, số nhà và địa phương, nhưng không bao gồm tỉnh/tiểu bang, mã bưu chính hoặc quốc gia. Ví dụ: văn phòng của Google tại Sydney, Úc có giá trị vicinity là 5/48 Pirrama Road, Pyrmont.

Truy cập vào Kết quả bổ sung

Theo mặc định, mỗi lượt tìm kiếm địa điểm sẽ trả về tối đa 20 kết quả cho mỗi truy vấn. Tuy nhiên, mỗi lượt tìm kiếm có thể trả về tối đa 60 kết quả, được chia thành 3 trang. Bạn có thể sử dụng các trang bổ sung bằng đối tượng PlaceSearchPagination. Để truy cập vào các trang bổ sung, bạn phải ghi lại đối tượng PlaceSearchPagination bằng hàm gọi lại. Đối tượng PlaceSearchPagination được xác định như sau:

  • hasNextPage là một thuộc tính boolean cho biết liệu có thêm kết quả hay không. true khi có thêm một trang kết quả.
  • nextPage() một hàm sẽ trả về tập hợp kết quả tiếp theo. Sau khi thực hiện một lượt tìm kiếm, bạn phải đợi 2 giây thì trang kết quả tiếp theo mới xuất hiện.

Để xem nhóm kết quả tiếp theo, hãy gọi nextPage. Mỗi trang kết quả phải được hiển thị trước khi hiển thị trang kết quả tiếp theo. Xin lưu ý rằng mỗi lượt tìm kiếm được tính là một yêu cầu duy nhất trong hạn mức sử dụng của bạn.

Ví dụ dưới đây minh hoạ cách thay đổi hàm gọi lại để nắm bắt đối tượng PlaceSearchPagination, nhờ đó, bạn có thể đưa ra nhiều yêu cầu tìm kiếm.

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
Xem ví dụ

Dùng thử mẫu

Thông tin về địa điểm

Ngoài việc cung cấp danh sách các địa điểm trong một khu vực, dịch vụ Places cũng có thể trả về thông tin chi tiết về một địa điểm cụ thể. Sau khi một địa điểm được trả về trong phản hồi tìm kiếm địa điểm, bạn có thể dùng mã địa điểm của địa điểm đó để yêu cầu thông tin chi tiết bổ sung về địa điểm đó, chẳng hạn như địa chỉ đầy đủ, số điện thoại, điểm xếp hạng và bài đánh giá của người dùng, v.v.

Yêu cầu về thông tin chi tiết về địa điểm

Bạn có thể yêu cầu Thông tin chi tiết về địa điểm bằng cách gọi phương thức getDetails() của dịch vụ.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

Phương thức này nhận một yêu cầu, chứa placeId của một địa điểm và các trường cho biết những loại dữ liệu Địa điểm cần trả về. Tìm hiểu thêm về cách tham chiếu một địa điểm bằng mã địa điểm.

Phương thức này cũng lấy một phương thức gọi lại, cần xử lý mã trạng thái được truyền trong phản hồi google.maps.places.PlacesServiceStatus, cũng như đối tượng google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

Xem ví dụ

Trường (Thông tin chi tiết về địa điểm)

Tham số fields nhận một mảng gồm các chuỗi (tên trường).

Sử dụng tham số fields để chỉ định một mảng các loại dữ liệu địa điểm cần trả về. Ví dụ: fields: ['address_components', 'opening_hours', 'geometry']. Sử dụng dấu chấm khi chỉ định các giá trị kết hợp. Ví dụ: opening_hours.weekday_text.

Các trường tương ứng với kết quả Chi tiết về địa điểm và được chia thành 3 danh mục thanh toán: Cơ bản, Thông tin liên hệ và Bầu không khí. Các trường cơ bản được tính phí theo mức cơ bản và không phát sinh thêm phí. Các trường Contact và Atmosphere được tính phí ở mức cao hơn. Hãy xem bảng giá để biết thêm thông tin. Các thuộc tính (html_attributions) luôn được trả về trong mọi lệnh gọi, bất kể bạn có yêu cầu hay không.

Cơ bản

Danh mục Cơ bản bao gồm các trường sau:
address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (không dùng nữa), photo, place_id, plus_code, type, url, utc_offset (không dùng nữa trong Thư viện địa điểm, Maps JavaScript API), utc_offset_minutes, vicinity

Thông tin liên hệ

Danh mục Thông tin liên hệ bao gồm các trường sau:
formatted_phone_number, international_phone_number, opening_hours, website

Khí quyển

Danh mục Atmosphere bao gồm các trường sau: price_level, rating, reviews, user_ratings_total

Tìm hiểu thêm về các trường địa điểm. Để biết thêm thông tin về cách tính phí cho các yêu cầu về dữ liệu Địa điểm, hãy xem phần Mức sử dụng và việc thanh toán.

Phản hồi về thông tin chi tiết về địa điểm

Mã trạng thái

Đối tượng phản hồi PlacesServiceStatus chứa trạng thái của yêu cầu và có thể chứa thông tin gỡ lỗi để giúp bạn theo dõi lý do khiến yêu cầu Chi tiết về địa điểm không thành công. Các giá trị trạng thái có thể là:

  • INVALID_REQUEST: Yêu cầu này không hợp lệ.
  • OK: Phản hồi chứa một kết quả hợp lệ.
  • OVER_QUERY_LIMIT: Trang web đã vượt quá hạn mức yêu cầu.
  • NOT_FOUND Không tìm thấy vị trí được tham chiếu trong cơ sở dữ liệu Địa điểm.
  • REQUEST_DENIED: Trang web không được phép sử dụng PlacesService.
  • UNKNOWN_ERROR: Yêu cầu PlacesService không xử lý được do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.
  • ZERO_RESULTS: Không tìm thấy kết quả nào cho yêu cầu này.

Kết quả về thông tin chi tiết về địa điểm

Lệnh gọi getDetails() thành công sẽ trả về một đối tượng PlaceResult có các thuộc tính sau:

  • address_components: Một mảng chứa các thành phần riêng biệt áp dụng cho địa chỉ này.

    Mỗi thành phần địa chỉ thường chứa các trường sau:

    • types[] là một mảng cho biết type của thành phần địa chỉ. Xem danh sách các loại được hỗ trợ.
    • long_name là nội dung mô tả hoặc tên đầy đủ của thành phần địa chỉ do Geocoder trả về.
    • short_name là tên văn bản viết tắt của thành phần địa chỉ (nếu có). Ví dụ: thành phần địa chỉ cho tiểu bang Alaska có thể có long_name là "Alaska" và short_name là "AK" bằng cách sử dụng chữ viết tắt gồm 2 chữ cái của bưu điện.

    Xin lưu ý những thông tin sau về mảng address_components[]:

    • Mảng thành phần địa chỉ có thể chứa nhiều thành phần hơn formatted_address.
    • Mảng này không nhất thiết phải bao gồm tất cả các thực thể chính trị có chứa địa chỉ, ngoài những thực thể có trong formatted_address. Để truy xuất tất cả các thực thể chính trị có chứa một địa chỉ cụ thể, bạn nên sử dụng tính năng mã hoá địa lý ngược, truyền vĩ độ/kinh độ của địa chỉ làm tham số cho yêu cầu.
    • Định dạng của phản hồi không được đảm bảo giữ nguyên giữa các yêu cầu. Cụ thể, số lượng address_components thay đổi tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng một địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại thành phần có thể thay đổi. Một thành phần cụ thể có thể bị thiếu trong phản hồi sau này.
  • business_status cho biết trạng thái hoạt động của địa điểm, nếu đó là một doanh nghiệp. Thuộc tính này có thể chứa một trong các giá trị sau:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Nếu không có dữ liệu, business_status sẽ không được trả về.
  • formatted_address: Địa chỉ mà con người có thể đọc được của địa điểm này.

    Địa chỉ này thường tương đương với địa chỉ bưu điện. Xin lưu ý rằng một số quốc gia (chẳng hạn như Vương quốc Anh) không cho phép phân phối địa chỉ bưu chính thực do các quy định hạn chế về việc cấp phép.

    Địa chỉ được định dạng bao gồm một hoặc nhiều thành phần địa chỉ. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "8th Avenue" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang của Hoa Kỳ).

    Không phân tích cú pháp địa chỉ được định dạng theo phương thức lập trình. Thay vào đó, bạn nên sử dụng các thành phần địa chỉ riêng lẻ mà phản hồi API bao gồm ngoài trường địa chỉ được định dạng.

  • formatted_phone_number: Số điện thoại của địa điểm, được định dạng theo quy ước khu vực của số.
  • geometry: Thông tin liên quan đến hình học của địa điểm. Trong đó có:
    • location cung cấp vĩ độ và kinh độ của địa điểm.
    • viewport xác định khung nhìn ưu tiên trên bản đồ khi xem địa điểm này.
  • permanently_closed (không dùng nữa) là một cờ boolean cho biết liệu địa điểm đã đóng cửa vĩnh viễn hay tạm thời (giá trị true). Đừng dùng permanently_closed. Thay vào đó, hãy sử dụng business_status để biết trạng thái hoạt động của doanh nghiệp.
  • plus_code (xem Mã vị trí mở và plus code) là một thông tin tham chiếu vị trí được mã hoá, bắt nguồn từ toạ độ vĩ độ và kinh độ, đại diện cho một khu vực: 1/8000 độ theo 1/8000 độ (khoảng 14 m x 14 m tại đường xích đạo) hoặc nhỏ hơn. Bạn có thể dùng plus code thay cho địa chỉ đường phố ở những nơi không có địa chỉ đường phố (nơi các toà nhà không được đánh số hoặc đường phố không được đặt tên).

    Mã cộng được định dạng dưới dạng mã toàn cầu và mã kết hợp:

    • global_code là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên (849VCWC8+R9).
    • compound_code là mã địa phương có từ 6 ký tự trở lên và có vị trí cụ thể (CWC8+R9, Mountain View, California, Hoa Kỳ). Không phân tích cú pháp nội dung này theo cách lập trình.
    Thông thường, cả mã toàn cầu và mã kết hợp đều được trả về. Tuy nhiên, nếu kết quả ở một vị trí từ xa (ví dụ: đại dương hoặc sa mạc), thì chỉ mã toàn cầu mới có thể được trả về.
  • html_attributions: Văn bản ghi nhận quyền tác giả sẽ xuất hiện cho kết quả về địa điểm này.
  • icon: URL đến một tài nguyên hình ảnh có thể dùng để biểu thị loại địa điểm này.
  • international_phone_number chứa số điện thoại của địa điểm ở định dạng quốc tế. Định dạng quốc tế bao gồm mã quốc gia và có dấu cộng (+) ở phía trước. Ví dụ: international_phone_number cho văn phòng của Google ở Sydney, Úc là +61 2 9374 4000.
  • name: Tên của địa điểm.
  • utc_offset Không dùng nữa trong Thư viện địa điểm, Maps JavaScript API, hãy dùng utc_offset_minutes.
  • utc_offset_minutes chứa số phút mà múi giờ hiện tại của địa điểm này nhanh hơn hoặc chậm hơn so với giờ UTC. Ví dụ: đối với những nơi ở Sydney, Úc trong thời gian tiết kiệm ánh sáng ban ngày, giá trị này sẽ là 660 (+11 giờ so với giờ UTC) và đối với những nơi ở California ngoài thời gian tiết kiệm ánh sáng ban ngày, giá trị này sẽ là -480 (-8 giờ so với giờ UTC).
  • opening_hours chứa các thông tin sau:
    • open_now (Không dùng nữa trong Thư viện địa điểm, Maps JavaScript API; thay vào đó, hãy dùng opening_hours.isOpen(). Để biết cách sử dụng isOpen với Place Details, hãy xem Cách lấy giờ mở cửa trong video Places API. `open_now` là một giá trị boolean cho biết địa điểm có đang mở cửa tại thời điểm hiện tại hay không.
    • periods[] là một mảng gồm các khoảng thời gian mở cửa trong 7 ngày, bắt đầu từ Chủ Nhật, theo thứ tự thời gian. Mỗi giai đoạn đều chứa:
      • open chứa một cặp đối tượng ngày và giờ mô tả thời điểm địa điểm mở cửa:
        • day một số từ 0 đến 6, tương ứng với các ngày trong tuần, bắt đầu từ Chủ Nhật. Ví dụ: 2 có nghĩa là thứ Ba.
        • time có thể chứa thời gian trong ngày ở định dạng hhmm 24 giờ (các giá trị nằm trong khoảng 0000 – 2359). time sẽ được báo cáo theo múi giờ của địa điểm.
      • close có thể chứa một cặp đối tượng ngày và giờ mô tả thời điểm đóng cửa của địa điểm. Lưu ý: Nếu một địa điểm luôn mở cửa, thì phần close sẽ không có trong phản hồi. Các ứng dụng có thể dựa vào trạng thái luôn mở được biểu thị dưới dạng một khoảng thời gian open chứa day có giá trị 0 và time có giá trị 0000, và không có close.
    • weekday_text là một mảng gồm 7 chuỗi biểu thị giờ mở cửa được định dạng cho mỗi ngày trong tuần. Nếu bạn chỉ định một tham số language trong yêu cầu Chi tiết về địa điểm, thì Places Service sẽ định dạng và bản địa hoá giờ mở cửa một cách phù hợp cho ngôn ngữ đó. Thứ tự của các phần tử trong mảng này phụ thuộc vào tham số language. Một số ngôn ngữ bắt đầu tuần vào thứ Hai, trong khi những ngôn ngữ khác bắt đầu vào Chủ Nhật.
  • permanently_closed (không dùng nữa) là một cờ boolean cho biết liệu địa điểm đã đóng cửa vĩnh viễn hay tạm thời (giá trị true). Đừng dùng permanently_closed. Thay vào đó, hãy sử dụng business_status để biết trạng thái hoạt động của doanh nghiệp.
  • photos[]: một mảng gồm các đối tượng PlacePhoto. Bạn có thể dùng PlacePhoto để lấy ảnh bằng phương thức getUrl() hoặc bạn có thể kiểm tra đối tượng để biết các giá trị sau:
    • height: chiều cao tối đa của hình ảnh, tính bằng pixel.
    • width: chiều rộng tối đa của hình ảnh, tính bằng pixel.
    • html_attributions: Văn bản ghi nhận quyền tác giả sẽ xuất hiện cùng với ảnh này về địa điểm.
  • place_id: Giá trị nhận dạng dạng văn bản xác định duy nhất một địa điểm và có thể dùng để truy xuất thông tin về địa điểm đó bằng yêu cầu Chi tiết về địa điểm. Tìm hiểu thêm về cách tham chiếu một địa điểm bằng mã địa điểm.
  • rating: Điểm xếp hạng của địa điểm, từ 0 đến 5, dựa trên các bài đánh giá tổng hợp của người dùng.
  • reviews một mảng có tối đa 5 bài đánh giá. Mỗi bài đánh giá bao gồm một số thành phần:
    • aspects[] chứa một mảng các đối tượng PlaceAspectRating, mỗi đối tượng cung cấp điểm xếp hạng của một thuộc tính duy nhất của cơ sở. Đối tượng đầu tiên trong mảng được coi là khía cạnh chính. Mỗi PlaceAspectRating được xác định là:
      • type tên của khía cạnh đang được đánh giá. Các loại sau đây được hỗ trợ: appeal, atmosphere, decor, facilities, food, overall, quality và service.
      • rating điểm xếp hạng của người dùng cho khía cạnh cụ thể này, từ 0 đến 3.
    • author_name tên của người dùng đã gửi bài đánh giá. Bài đánh giá ẩn danh sẽ được ghi nhận là của "Một người dùng Google". Nếu bạn đặt một tham số ngôn ngữ, thì cụm từ "Một người dùng Google" sẽ trả về một chuỗi đã bản địa hoá.
    • author_url URL đến hồ sơ Google+ của người dùng (nếu có).
    • language mã ngôn ngữ IETF cho biết ngôn ngữ được dùng trong bài đánh giá của người dùng. Trường này chỉ chứa thẻ ngôn ngữ chính, chứ không phải thẻ phụ cho biết quốc gia hoặc khu vực. Ví dụ: tất cả bài đánh giá bằng tiếng Anh đều được gắn thẻ là "en", chứ không phải "en-AU" hoặc "en-UK".
    • rating điểm xếp hạng chung của người dùng cho địa điểm này. Đây là một số nguyên, trong khoảng từ 1 đến 5.
    • text bài đánh giá của người dùng. Khi xem xét một địa điểm bằng Google Places, bài đánh giá bằng văn bản được coi là không bắt buộc; do đó, trường này có thể trống.
  • types Một mảng các loại cho địa điểm này (ví dụ: ["political", "locality"] hoặc ["restaurant", "lodging"]). Mảng này có thể chứa nhiều giá trị hoặc có thể trống. Chúng tôi có thể giới thiệu các giá trị mới mà không cần thông báo trước. Xem danh sách các loại được hỗ trợ.
  • url: URL của trang chính thức của Google cho địa điểm này. Đây là trang thuộc sở hữu của Google, chứa thông tin tốt nhất hiện có về địa điểm. Các ứng dụng phải liên kết đến hoặc nhúng trang này trên mọi màn hình hiển thị kết quả chi tiết về địa điểm cho người dùng.
  • vicinity: Địa chỉ đơn giản của địa điểm, bao gồm tên đường, số nhà và địa phương, nhưng không bao gồm tỉnh/tiểu bang, mã bưu chính hoặc quốc gia. Ví dụ: văn phòng của Google tại Sydney, Úc có giá trị vicinity là 5/48 Pirrama Road, Pyrmont. Thuộc tính vicinity chỉ được trả về cho một Tìm kiếm lân cận.
  • website liệt kê trang web chính thức của địa điểm này, chẳng hạn như trang chủ của doanh nghiệp.

Lưu ý: Điểm xếp hạng đa chiều có thể không có ở một số địa điểm. Nếu có quá ít bài đánh giá, thì phản hồi chi tiết sẽ bao gồm điểm xếp hạng cũ theo thang điểm từ 0 đến 5 (nếu có) hoặc không có điểm xếp hạng nào.

Tham chiếu một Địa điểm bằng Mã địa điểm

Mã địa điểm là một thông tin tham chiếu duy nhất đến một địa điểm trên Google Maps. Mã địa điểm có sẵn cho hầu hết các vị trí, bao gồm cả doanh nghiệp, địa danh, công viên và giao lộ.

Để sử dụng mã địa điểm trong ứng dụng, trước tiên, bạn phải tra cứu mã này. Mã này có trong PlaceResult của yêu cầu Tìm kiếm địa điểm hoặc Chi tiết. Sau đó, bạn có thể dùng mã địa điểm này để tra cứu Thông tin chi tiết về địa điểm.

Mã địa điểm không phải tuân thủ các quy định hạn chế về việc lưu vào bộ nhớ đệm được nêu trong Mục 3.2.3(b) của Điều khoản dịch vụ của Nền tảng Google Maps. Do đó, bạn có thể lưu trữ các giá trị mã địa điểm để sử dụng sau này. Để biết các phương pháp hay nhất khi lưu trữ mã địa điểm, hãy xem thông tin tổng quan về mã địa điểm.

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

Hình ảnh về địa điểm

Sử dụng tính năng Ảnh địa điểm để thêm nội dung ảnh chất lượng cao vào trang web của bạn. Dịch vụ Ảnh cho phép bạn truy cập vào hàng triệu bức ảnh được lưu trữ trong cơ sở dữ liệu của Địa điểm và Google+ Địa phương. Khi bạn nhận được thông tin về địa điểm bằng cách sử dụng yêu cầu Chi tiết về địa điểm, các thông tin tham chiếu về ảnh sẽ được trả về cho nội dung ảnh có liên quan. Các yêu cầu Tìm kiếm lân cận và Tìm kiếm bằng văn bản cũng trả về một thông tin tham chiếu duy nhất về ảnh cho mỗi địa điểm, khi có liên quan. Khi sử dụng dịch vụ Ảnh, bạn có thể truy cập vào những bức ảnh được tham chiếu và đổi kích thước hình ảnh thành kích thước tối ưu cho ứng dụng của mình.

Một mảng các đối tượng PlacePhoto sẽ được trả về trong đối tượng PlaceResult cho mọi yêu cầu getDetails(), textSearch() hoặc nearbySearch() được thực hiện đối với PlacesService.

Lưu ý: Số lượng ảnh được trả về sẽ khác nhau tuỳ theo yêu cầu.

  • Tính năng Tìm kiếm lân cận hoặc Tìm kiếm bằng văn bản sẽ trả về tối đa một đối tượng PlacePhoto.
  • Yêu cầu Chi tiết sẽ trả về tối đa 10 đối tượng PlacePhoto.

Bạn có thể yêu cầu URL cho hình ảnh được liên kết bằng cách gọi phương thức PlacePhoto.getUrl() và truyền một đối tượng PhotoOptions hợp lệ. Sử dụng đối tượng PhotoOptions để chỉ định chiều cao và chiều rộng tối đa của hình ảnh. Nếu bạn chỉ định giá trị cho cả maxHeight và maxWidth, dịch vụ ảnh sẽ đổi kích thước hình ảnh thành kích thước nhỏ hơn trong hai kích thước, đồng thời duy trì tỷ lệ khung hình ban đầu.

Đoạn mã sau đây chấp nhận một đối tượng địa điểm và thêm một điểm đánh dấu vào bản đồ nếu có ảnh. Hình ảnh điểm đánh dấu mặc định được thay thế bằng một phiên bản nhỏ của bức ảnh.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

Ảnh do dịch vụ Ảnh trả về được lấy từ nhiều vị trí, bao gồm cả ảnh do chủ sở hữu doanh nghiệp và người dùng đóng góp. Trong hầu hết các trường hợp, bạn có thể sử dụng những bức ảnh này mà không cần ghi nguồn hoặc sẽ có thông tin ghi nguồn bắt buộc trong ảnh. Tuy nhiên, nếu phần tử photo được trả về có chứa một giá trị trong trường html_attributions, thì bạn phải thêm thông tin ghi công bổ sung vào ứng dụng của mình bất cứ khi nào bạn hiển thị hình ảnh.