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

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Tổng quan

Các chức năng trong Thư viện địa điểm, API JavaScript cho phép ứng dụng của bạn tìm kiếm các địa điểm (được định nghĩa trong API này dưới dạng cơ sở, vị trí địa lý hoặc địa điểm nổi bật mà bạn quan tâ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.

API Địa điểm cung cấp tính năng tự động hoàn thành mà bạn có thể dùng để cung cấp cho ứng dụng hành vi tìm kiếm trước loại trường trường tìm kiếm của 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 vào các mục 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 không quen với API JavaScript cho Maps hoặc JavaScript, bạn nên xem lại JavaScript và nhận khoá API trước khi bắt đầu.

Bật API

Trước khi sử dụng thư viện Địa điểm trong API JavaScript của Maps, trước tiên hãy đảm bảo rằng API địa điểm đã được bật trong Google Cloud Console, trong cùng một dự án mà bạn đã thiết lập cho API JavaScript của Maps.

Cách xem danh sách API đã bật:

  1. Truy cập vào Google Cloud Console.
  2. Nhấp vào nút Select a project (Chọn dự án), sau đó chọn dự án mà bạn đã thiết lập cho API JavaScript cho Maps và nhấp vào Mở.
  3. Từ danh sách API trên Trang tổng quan, hãy tìm API Địa điểm.
  4. Nếu bạn thấy API địa điểm trong danh sách, thì có nghĩa là API này đã được bật. Nếu API không được liệt kê, hãy bật API:
    1. Ở đầu trang, hãy chọn ENABLE APIS AND Services (Bật API VÀ DỊCH VỤ) để hiển thị thẻ Library (Thư viện). Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
    2. Tìm API Địa điểm, sau đó chọn API này trong danh sách kết quả.
    3. Chọn BẬT. Khi quá trình này kết thúc, API Địa điểm sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Đang 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 JavaScript chính của Maps. Để sử dụng chức năng có trong thư viện này, trước tiên bạn phải tải chức năng này bằng cách sử dụng thông số libraries trong URL khởi động API của Maps:

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

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

Thêm API Địa điểm vào danh sách hạn chế API của khóa API

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

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

Hạn mức

Thư viện địa điểm, JavaScript API chia sẻ hạn mức sử dụng với API địa điểm theo mô tả trong tài liệu về Giới hạn sử dụng cho API địa điểm. Giới hạn tốc độ truy vấn trên mỗi giây được áp dụng cho mỗi phiên người dùng, bất kể có bao nhiêu người dùng dùng chung một dự án.*

Lưu ý: Khi tải API lần đầu tiên, bạn sẽ được phân bổ một hạn mức yêu cầu ban đầu. Sau khi bạn sử dụng hạn mức này, API sẽ thực thi các giới hạn tốc độ đối với các yêu cầu bổ sung trên mỗi giây. Nếu có quá nhiều yêu cầu được thực hiện trong một khoảng thời gian nhất định, API sẽ trả về mã phản hồi OVER_QUERY_LIMIT. Giới hạn tốc độ trên mỗi phiên ngăn chặn việc sử dụng dịch vụ phía máy khách cho yêu cầu hàng loạt. Đối với các yêu cầu hàng loạt, hãy sử dụng API dịch vụ web của chúng tôi.

Chính sách

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

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

Với dịch vụ Địa điểm, 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ư & # 39; ã con dữ liệu\39; kết quả cho biết địa chỉ, khu vực chính trị như thị trấn và thành phố, cùng những địa điểm yêu thích khác.

Tìm yêu cầu Đị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 truy vấn 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 từ truy vấn

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

  • query (bắt buộc) Chuỗi văn bản cần tìm kiếm, ví dụ: "factory" hoặc "123 Main Street" Đây phải là tên địa điểm, địa chỉ hoặc loại hình cơ sở. Mọi loại dữ liệu đầu vào khác đều có thể gây ra lỗi và không đảm bảo sẽ trả về kết quả hợp lệ. API Địa điểm sẽ trả về kết quả phù hợp với ứng viên dựa trên chuỗi này và sắp xếp kết quả dựa trên mức độ liên quan đã nhận thấy.
  • fields (bắt buộc) Một hoặc nhiều trường chỉ định loại dữ liệu Địa điểm cần trả về.
  • locationBias (không bắt buộc) Tọa độ xác định khu vực để tìm kiếm. 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 cho findPlaceFromQuery() để xử lý đối tượng kết quả và phản hồi google.maps.places.PlacesServiceStatus.

Ví dụ sau hiển thị 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 namegeometry.

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 từ số điện thoại

Tìm địa điểm từ số điện thoại sẽ lấy số điện thoại và trả lại một địa điểm. Để thực hiện yêu cầu Tìm địa điểm từ số điện thoại, hãy gọi phương thức PlaceService&<39;s findPlaceFromPhoneNumber(). Phương thức này sẽ 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 loại dữ liệu Địa điểm cần trả về.
  • locationBias (không bắt buộc) Tọa độ để xác định khu vực cần tìm kiếm. 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 cho 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 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ị phức 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 ba danh mục thanh toán: Cơ bản, 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 tính thêm phí. Các trường Địa chỉ liên hệ và Khí quyển được tính phí 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ề với mọi lệnh gọi, bất kể trường đó có đượ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:
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

Liên hệ

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

Khí quyển

Danh mục Khí quyển bao gồm các trường sau: price_level, rating, user_ratings_total

Phương thức findPlaceFromQuery()findPlaceFromPhoneNumber() sử dụng cùng một nhóm các trường và có thể trả về cùng một trường trong các phản hồi tương ứng.

Thiết lập vị trí (Tìm phương thức Địa điểm)

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

Xu hướng dẫn đến 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ể dùng LatLngBounds.

Xác định bán kính để tìm kiếm (tính bằng mét), căn giữa theo 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 các địa điểm trong một khu vực cụ thể theo từ khoá hoặc loại. Tính năng Tìm kiếm lân cận phải luôn bao gồm một vị trí. Bạn có thể chỉ định vị trí này theo một trong hai cách sau:

  • LatLngBounds.
  • một vùng tròn được xác định là tổ hợp của thuộc tính location — xác đị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.

Tìm kiếm Địa điểm lân cận được bắt đầu bằng lệnh gọi đến phương thức nearbySearch() của PlacesService. Phương thức này sẽ trả về một loạt các đối tượng PlaceResult. Lưu ý rằng phương thức nearbySearch() 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 nhận yêu cầu bằng các trường sau:

  • Một trong hai cách sau:
    • bounds, phải là một đối tượng google.maps.LatLngBounds xác định khu vực tìm kiếm hình chữ nhật; hoặc
    • locationradius; phương thức trước lấy đối tượng google.maps.LatLng, còn đối tượng sau lấy đối số nguyên đơn giản, biểu thị bán kính của vòng tròn tính bằng mét. Bán kính tối đa cho phép là 50.000 mét. Xin lưu ý rằng khi rankBy được đặt thành PageSpeed, 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ừ sẽ được so 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ư bài đánh giá của khách hàng và nội dung khác của bên thứ ba.
  • minPriceLevelmaxPriceLevel (không bắt buộc) — Hạn chế kết quả chỉ tại 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 (giá cả phải chăng nhất) đến 4 (đắt nhất), bao gồm cả hai giá trị đó.
  • name không được dùng nữa. Tương đương với keyword. Giá trị trong trường này được kết hợp với các giá trị trong trường keyword và được chuyể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ụ Địa điểm sẽ chỉ trả về những địa điểm đang mở cửa kinh doanh tại thời điểm gửi truy vấn. Các địa điểm không chỉ định giờ mở cửa trong cơ sở dữ liệu của Google Địa điểm sẽ không được trả về nếu bạn đưa thông số này vào truy vấn của mình. 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). Tuỳ chọn này sắp xếp các kết quả dựa trên tầm quan trọng của chúng. Thứ hạng sẽ ưu tiên các địa điểm nổi bật trong phạm vi bán kính đã đặt so với các đị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ể phụ thuộc vào 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, cần có tham số radius.
    • google.maps.places.RankBy.DISTANCE. Tuỳ chọn này sắp xếp các kết quả theo thứ tự tăng dần theo khoảng cách từ location được 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 chỉ định RankBy.DISTANCE. Khi bạn chỉ định RankBy.DISTANCE, cần có một hoặc nhiều keyword, name hoặc type.
  • type – Hạn chế kết quả ở những nơi phù hợp với loại đã 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ì mọi 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 cho 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 văn bản

Dịch vụ Tìm kiếm văn bản trên Google Địa điểm là một dịch vụ web trả về thông tin về một nhóm các địa điểm dựa trên chuỗi – ví dụ: "pizza ở New York" hoặc cửa hàng "giày gần Ottawa" Dịch vụ này phản hồi bằng một danh sách các vị trí phù hợp với chuỗi văn bản và mọi vị trí đã đặt. Nội dung phản hồi tìm kiếm sẽ bao gồm một danh sách các địa điểm. Bạn có thể gửi yêu cầu Thông tin 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.

Tìm kiếm văn bản được bắt đầu bằng lệnh gọi 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 nhận yêu cầu bằng các trường sau:

  • query (bắt buộc) Chuỗi văn bản cần tìm kiếm, ví dụ: "factory" hoặc "123 Main Street" Đây phải là tên, địa chỉ hoặc danh mục cơ sở lưu trú. Mọi loại dữ liệu đầu vào khác đều có thể gây ra lỗi và không đảm bảo sẽ trả về kết quả hợp lệ. Dịch vụ Địa điểm sẽ trả về kết quả đề xuất phù hợp dựa trên chuỗi này và sắp xếp kết quả dựa trên mức độ liên quan đã nhận thấy. Thông số này sẽ không bắt buộc nếu bạn cũng dùng thông số type trong yêu cầu tìm kiếm.
  • Không bắt buộc:
    • openNow – Một giá trị boolean cho biết dịch vụ Địa điểm chỉ được trả về những địa điểm đang mở cửa kinh doanh tại thời điểm gửi truy vấn. Các địa điểm không chỉ định giờ mở cửa trong cơ sở dữ liệu của Google Địa điểm sẽ không được trả về nếu bạn đưa thông số này vào truy vấn của mình. Việc đặt openNow thành false không có hiệu lực.
    • minPriceLevelmaxPriceLevel – Chỉ cho phép kết quả tìm kiếm ở những vị trí trong phạm vi mức giá đã 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), bao gồm cả hai giá trị đó.
    • Một trong hai cách sau:
      • bounds – Một đối tượng google.maps.LatLngBounds xác định hình chữ nhật để tìm kiếm; hoặc
      • locationradius — Bạn có thể thiên về kết quả vòng tròn chỉ định bằng cách truyền một tham số locationradius. Việ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 kết nối đó. Kết quả nằm ngoài phạm vi đã xác định có thể vẫn hiển thị. Vị trí này sẽ lấy một đối tượng google.maps.LatLng và bán kính nhận một số nguyên đơn giản, biểu thị 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 vị trí phù hợp với loại đã 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 cho textSearch() để xử lý đối tượng kết quả và một 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]);
    }
  }
}

Trả lờ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 yêu cầu đị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 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: Không thể xử lý yêu cầu PlacesService 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ả cho yêu cầu này.

Đặt kết quả tìm kiếm

Các hàm findPlace(), nearbySearch()textSearch() trả về một loạt 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à doanh nghiệp. Thuộc tính này có thể chứa một trong những giá trị sau:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Nếu không có dữ liệu thì business_status sẽ không được trả về.
  • formatted_address là một chuỗi chứa địa chỉ có thể đọc được của địa điểm này. Thuộc tính formatted_address chỉ được trả về cho một Tìm kiếm văn bản (Text Search).

    Thông thường, địa chỉ này 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ỉ gửi thư thực sự do các hạn chế 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ỉ theo logic. Ví dụ: địa chỉ "111 Đại lộ 8, New York, NY" gồm các thành phần sau: "111" (số đường phố), "Đại lộ 8&&tt; (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ỉ đã đị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à nội dung phản hồi API sẽ bao gồm cùng vớ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. Hành động sửa đổi này bao gồm:
    • 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 địa điểm đã đóng cửa vĩnh viễn hoặc tạm thời (giá trị true). Không sử 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 các doanh nghiệp.
  • plus_code (xem Mở mã vị trímã cộng) là một tệp tham chiếu vị trí được mã hóa, bắt nguồn từ tọa độ theo vĩ độ và kinh độ, đại diện cho một khu vực: 1/8000 độ bằng 1/8000 độ ( nhỏ hơn khoảng 14 m x 14 m tại đường xích đạo) hoặc nhỏ hơn. Bạn có thể sử dụng Plus Code để thay thế cho địa chỉ đường phố ở những nơi không tồn tại (trong đó các toà nhà không được đánh số hoặc không có tên đường phố).

    Plus code được định dạng dưới dạng mã toàn cục và mã phức hợp:

    • global_code là mã vùng gồm 4 ký tự và mã cục bộ có 6 ký tự trở lên (849VCWC8+R9).
    • compound_code là một mã địa phương gồm 6 ký tự trở lên và có vị trí rõ ràng (CWC8+R9, Mountain View, CA, Hoa Kỳ). Không phân tích cú pháp nội dung này theo phương thức lập trình.
    Thông thường, cả mã toàn cục và mã phức hợp đều được trả về. Tuy nhiên, nếu kết quả nằm ở một vị trí từ xa (ví dụ: đại dương hoặc sa mạc), thì chỉ có thể trả về mã toàn cầu.
  • html_attributions: Một mảng thuộc tính 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 mô hình phân bổ. Lưu ý: Đây là dữ liệu tổng hợp tất cả mô hình phân bổ cho toàn bộ phản hồi tìm kiếm. Do đó, tất 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 biểu tượng PNG có màu 71px x 71px.
  • icon_mask_base_uri trả về URL cơ sở cho một biểu tượng không màu, trừ phần mở rộng .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 địa điểm.
  • opening_hours có thể chứa các thông tin sau:
    • open_now là giá trị boolean cho biết địa điểm này có mở cửa vào thời điểm hiện tại hay không (Đã ngừng sử dụng trong Thư viện địa điểm, API JavaScript của Maps, hãy sử 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 duy nhất một địa điểm. Để truy xuất thông tin về địa điểm này, hãy chuyển giá trị nhận dạng này vào yêu cầu Thông tin 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ột mã địa điểm.
  • rating chứa điểm xếp hạng của địa điểm này, từ 0 đến 5.0 dựa trên các bài đánh giá tổng hợp của người dùng.
  • types Một loạt các loại dữ liệu cho vị trí 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. Hãy xem danh sách các loại được hỗ trợ.
  • vicinity: Một địa chỉ đơn giản cho địa điểm, bao gồm tên đường, số đường và địa phương, nhưng không phải là tỉnh/tiểu bang, mã bưu chính hoặc quốc gia. Ví dụ: văn phòng của Úc ở Sydney, văn phòng của Úc có giá trị vicinity5/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 trả về tối đa 20 kết quả cho mỗi cụm từ tìm kiếm. Tuy nhiên, mỗi lượt tìm kiếm có thể trả về tối đa 60 kết quả, chia thành ba trang. Bạn có thể xem thêm các trang khác thông qua đối tượng PlaceSearchPagination. Để truy cập vào các trang khác, bạn phải ghi lại đối tượng PlaceSearchPagination thông qua hàm callback. Đối tượng PlaceSearchPagination được định nghĩa là:

  • hasNextPage một thuộc tính boolean cho biết có thêm kết quả hay không. true khi có trang kết quả bổ sung.
  • nextPage() một hàm trả về tập hợp kết quả tiếp theo. Sau khi tìm kiếm, bạn phải đợi hai giây trước khi có trang kết quả tiếp theo.

Để xem tập hợp kết quả tiếp theo, hãy gọi nextPage. Mỗi trang kết quả phải 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 sẽ được tính là một yêu cầu dựa trên hạn mức sử dụng của bạn.

Ví dụ bên dưới 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;

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;
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ụ Địa điểm còn có thể trả về thông tin chi tiết về một địa điểm cụ thể. Khi đã trả về một địa điểm trong một phản hồi tìm kiếm địa điểm, bạn có thể sử dụng mã địa điểm để yêu cầu thêm thông tin chi tiết về địa điểm đó (chẳng hạn như địa chỉ đầy đủ, số điện thoại, điểm xếp hạng từ người dùng và bài đánh giá), v.v.

Yêu cầu thông tin địa điểm

Thông tin chi tiết về địa điểm được yêu cầu bằng lệnh 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 sẽ nhận một yêu cầu, chứa placeId địa điểm mong muốn và các trường cho biết loại dữ liệu Địa điểm nào sẽ được trả về. Tìm hiểu thêm về cách tham chiếu một địa điểm bằng một mã địa điểm.

Phương thức này cũng cần có một phương thức gọi lại để 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 (Chi tiết địa điểm)

Thông số fields lấy một mảng chuỗi (tên trường).

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

Các trường tương ứng với kết quả về Thông tin chi tiết về địa điểm và được chia thành 3 danh mục thanh toán: Cơ bản, 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 tính thêm phí. Địa chỉ liên hệ và trường Khí quyển được tính phí 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ề với mọi lệnh gọi, bất kể yêu cầu đó có đượ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_component, 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 (API/201}

Liên hệ

Danh mục 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 Khí quyển bao gồm các trường sau: price_level, rating, review, 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í các yêu cầu dữ liệu về Địa điểm, hãy xem phần Mức sử dụng và thanh toán.

Câu trả lời về thông tin đị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 yêu cầu Thông tin 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 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: Không thể xử lý yêu cầu PlacesService 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ả cho yêu cầu này.

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

Lệnh gọi getDetails() thành công sẽ trả về đối tượng PlaceResult với 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 loại thành phần địa chỉ. Hãy xem danh sách các loại được hỗ trợ.
    • long_name là phần mô tả văn bản đầy đủ hoặc tên của thành phần địa chỉ do Trình mã hoá địa lý trả về.
    • short_name là tên viết tắt của thành phần địa chỉ (nếu có). Ví dụ: một thành phần địa chỉ cho tiểu bang Alaska có thể có long_name là "Alaska" và short_name là "AK" sử dụng chữ viết tắt gồm 2 chữ cái của bưu điện.

    Hãy 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 trừ 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 mã hoá địa lý ngược, chuyển vĩ độ/kinh độ của địa chỉ làm thông số cho yêu cầu.
    • Định dạng của phản hồi không phải lúc nào cũng giống nhau giữa các yêu cầu. Cụ thể, số lượng address_components sẽ thay đổi dựa trên đị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ỉ. 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.
  • business_status cho biết trạng thái hoạt động của địa điểm, nếu đó là doanh nghiệp. Thuộc tính này có thể chứa một trong những giá trị sau:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Nếu không có dữ liệu thì business_status sẽ không được trả về.
  • formatted_address: Địa chỉ mà con người có thể đọc được.

    Thông thường, địa chỉ này 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ỉ gửi thư thực sự do các hạn chế 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ỉ theo logic. Ví dụ: địa chỉ "111 Đại lộ 8, New York, NY" gồm các thành phần sau: "111" (số đường phố), "Đại lộ 8&&tt; (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ỉ đã đị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à nội dung phản hồi API sẽ bao gồm cùng vớ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ố điện thoại.
  • geometry: Thông tin liên quan đến hình học của địa điểm. Hành động sửa đổi này bao gồm:
    • 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 địa điểm đã đóng cửa vĩnh viễn hoặc tạm thời (giá trị true). Không sử 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 các doanh nghiệp.
  • plus_code (xem Mở mã vị trímã cộng) là một tệp tham chiếu vị trí được mã hóa, bắt nguồn từ tọa độ theo vĩ độ và kinh độ, đại diện cho một khu vực: 1/8000 độ bằng 1/8000 độ ( nhỏ hơn khoảng 14 m x 14 m tại đường xích đạo) hoặc nhỏ hơn. Bạn có thể sử dụng Plus Code để thay thế cho địa chỉ đường phố ở những nơi không tồn tại (trong đó các toà nhà không được đánh số hoặc không có tên đường phố).

    Plus code được định dạng dưới dạng mã toàn cục và mã phức hợp:

    • global_code là mã vùng gồm 4 ký tự và mã cục bộ có 6 ký tự trở lên (849VCWC8+R9).
    • compound_code là một mã địa phương gồm 6 ký tự trở lên và có vị trí rõ ràng (CWC8+R9, Mountain View, CA, Hoa Kỳ). Không phân tích cú pháp nội dung này theo phương thức lập trình.
    Thông thường, cả mã toàn cục và mã phức hợp đều được trả về. Tuy nhiên, nếu kết quả nằm ở một vị trí từ xa (ví dụ: đại dương hoặc sa mạc), thì chỉ có thể trả về mã toàn cầu.
  • html_attributions: Văn bản thuộc tính sẽ hiển thị cho kết quả địa điểm này.
  • icon: URL đến một tài nguyên hình ảnh có thể được dùng để thể hiện 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ó tiền tố là dấu cộng (+). Ví dụ: international_phone_number cho văn phòng của Sydney tại Úc là +61 2 9374 4000.
  • name: Tên địa điểm.
  • utc_offset Đã ngừng hoạt động trong Thư viện địa điểm, API Maps JavaScript, hãy sử dụng utc_offset_minutes.
  • utc_offset_minutes chứa số phút của múi giờ hiện tại của địa điểm này so với giờ UTC. Ví dụ: đối với những địa điểm ở Sydney, Úc vào giờ mùa hè, thì điều này sẽ là 660 (+11 giờ so với giờ UTC) và những địa điểm ở California ngoài giờ mùa hè thì phải 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, API Maps JavaScript; thay vào đó, hãy sử dụng open_hours.isOpen()). Hãy xem video này để biết cách sử dụng isOpen kèm thông tin chi tiết về địa điểm.) là giá trị boolean cho biết địa điểm có mở cửa vào 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 kéo dài 7 ngày, bắt đầu từ Chủ Nhật, theo thứ tự thời gian. Mỗi dấu chấm 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ờ (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 địa điểm này đóng cửa. Lưu ý: Nếu một địa điểm luôn mở cửa, thì phần close sẽ bị thiếu trong phản hồi. Các ứng dụng có thể dựa vào việc luôn mở được biểu thị dưới dạng 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 bảy chuỗi đại diện cho giờ mở cửa được định dạng cho mỗi ngày trong tuần. Nếu một tham số language được chỉ định trong yêu cầu Thông tin chi tiết về địa điểm, Dịch vụ địa điểm sẽ định dạng và bản địa hóa giờ mở cửa 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 các 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 địa điểm đã đóng cửa vĩnh viễn hoặc tạm thời (giá trị true). Không sử 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 các doanh nghiệp.
  • photos[]: một mảng các đối tượng PlacePhoto. Bạn có thể sử 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 thuộc tính sẽ hiển thị cùng với ảnh địa điểm này.
  • place_id: Một giá trị nhận dạng dạng văn bản giúp 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 đó qua yêu cầu Thông tin 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ột mã địa điểm.
  • rating: Điểm xếp hạng của địa điểm, từ 0 đến 5,0, 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 gồm 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 một điểm xếp hạng cho 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à thành phần chính. Mỗi PlaceAspectRating được khai báo là:
      • type tên của khía cạnh đang được xếp hạng. Chúng tôi hỗ trợ các loại sau: appeal, atmosphere, decor, facilities, food, overall, qualityservice.
      • 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á. Các bài đánh giá ẩn danh được ghi nhận là "Một người dùng Google" Nếu bạn đặt một thông 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ơ trên Google+ của người dùng, nếu có.
    • language mã ngôn ngữ IETF cho biết ngôn ngữ sử 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 chứa thẻ phụ cho biết quốc gia hoặc khu vực. Ví dụ: tất cả các bài đánh giá bằng tiếng Anh được gắn thẻ là & # 39; en & 39; và không phải là & # 39; en-AU& # 39; hoặc & # 39; en-UK\39; và v.v.
    • Điểm xếp hạng chung của người dùng là rating cho địa điểm này. Đây là một số nguyên, có giá trị từ 1 đến 5.
    • text bài đánh giá của người dùng. Khi xem xét một vị trí bằng Google Địa điểm, các 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 loạt các loại dữ liệu cho vị trí 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. Hãy xem danh sách các loại được hỗ trợ.
  • url: URL của trang Google chính thức cho địa điểm này. Đây là trang do Google sở hữu 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 hoặc nhúng trang này vào bất kỳ màn hình nào hiển thị kết quả chi tiết về địa điểm đó cho người dùng.
  • vicinity: Một địa chỉ đơn giản cho địa điểm, bao gồm tên đường, số đường và địa phương, nhưng không phải là tỉnh/tiểu bang, mã bưu chính hoặc quốc gia. Ví dụ: văn phòng của Úc ở Sydney, văn phòng của Úc có giá trị vicinity5/48 Pirrama Road, Pyrmont. Thuộc tính vicinity chỉ được trả về cho Tìm kiếm lân cận.
  • website liệt kê các trang web có căn cứ đáng tin cho địa điểm này, chẳng hạn như trang chủ của một doanh nghiệp\39; trang chủ.

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

Tham chiếu địa điểm bằng mã địa điểm

Mã địa điểm là mã 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 địa điểm, 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ã nhận dạng này, có trong PlaceResult của yêu cầu Tìm kiếm địa điểm hoặc Thông tin chi tiết. Sau đó, bạn có thể sử 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 được phép tuân theo các quy định hạn chế về việc lưu vào bộ nhớ đệm như đã nêu trong Mục 3.2.3(a) 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ữ giá trị mã địa điểm để sử dụng sau này. Để biết phương pháp hay nhất khi lưu trữ mã địa điểm, hãy xem bài viết 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

Tính năng Hình ảnh địa điểm cho phép bạn thêm nội dung ảnh chất lượng cao vào trang web của mình. Dịch vụ Ảnh cho phép bạn truy cập vào hàng triệu ảnh được lưu trữ trong cơ sở dữ liệu Địa điểm và Google+ Địa phương. Khi bạn nhận được thông tin địa điểm bằng yêu cầu Thông tin chi tiết về địa điểm, tham chiếu ả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 văn bản cũng trả về một tham chiếu ảnh duy nhất cho mỗi địa điểm, khi có liên quan. Khi sử dụng dịch vụ Photos, bạn có thể truy cập vào các ảnh đã 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.

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

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

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

Bạn có thể yêu cầu URL của hình ảnh liên kết bằng cách gọi phương thức PlacePhoto.getUrl() và chuyển đối tượng PhotoOptions hợp lệ. Đối tượng PhotoOptions cho phép bạn chỉ định chiều cao và chiều rộng tối đa mà bạn muốn cho hình ảnh. Nếu bạn chỉ định một giá trị cho cả maxHeightmaxWidth, thì 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, trong khi vẫn duy trì tỷ lệ khung hình gốc.

Đoạn mã sau đây chấp nhận một đối tượng địa điểm và thêm điểm đánh dấu vào bản đồ nếu có ảnh. Hình ảnh đánh dấu mặc định được thay thế bằng một phiên bản nhỏ của ả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ó nguồn gốc từ nhiều vị trí, bao gồm cả chủ doanh nghiệp và ảnh do 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 các ảnh này mà không cần ghi nhận tác giả hoặc sẽ có thuộc tính bắt buộc là một phần của hình ảnh. Tuy nhiên, nếu phần tử photo được trả về bao gồm một giá trị trong trường html_attributions, thì bạn phải đưa thuộc tính bổ sung vào ứng dụng bất cứ khi nào hình ảnh hiển thị.