Thư viện địa điểm (original) (raw)

Tổng quan

Các hàm trong Thư viện địa điểm, API JavaScript của Maps 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ác cơ sở, vị trí địa lý hoặc điểm yêu thích nổi bật) nằm trong một khu vực đượ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ể sử dụng để cung cấp cho ứng dụng của mình hành vi tìm kiếm nhập trước của trường tìm kiếm trên 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 API JavaScript của Maps hoặc với JavaScript, bạn nên xem lại JavaScript và Lấy 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 bạn đã bật API Địa điểm 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. Chuyển đến Google Cloud Console.
  2. Nhấp vào nút Chọn dự án, sau đó chọn chính dự án mà bạn đã thiết lập cho API Maps JavaScript rồi nhấp vào Mở.
  3. Trong 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, tức là API này đã được bật. Nếu API không có trong danh sách, hãy bật API đó:
    1. Ở đầu trang, hãy chọn BẬT API VÀ DỊCH VỤ để hiển thị thẻ 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 kiếm Places API, sau đó chọn API đó trong danh sách kết quả.
    3. Chọn BẬT. Khi quá trình này hoàn tất, API Địa điểm sẽ xuất hiện trong danh sách API trên Trang tổng quan.

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 chức năng đó bằng tham số libraries trong URL khởi động của API Maps:

Hãy xem phần 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ế về API cho khoá sẽ giới hạn việc sử dụng khoá API ở một hoặc nhiều API hoặc SDK. Các yêu cầu đến một API hoặc SDK 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ế một khoá API để sử dụng 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 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ế:
    • Quy định hạn chế về API
      • Chọn Restrict key (Hạn chế khoá).
      • Nhấp vào Chọn API rồi chọn cả Maps JavaScript API và API Địa điểm.
        (Nếu một trong hai API không có trong danh sách, bạn cần bật API đó.)
  6. Nhấp vào LƯU.

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

Hạn mức

Thư viện Địa điểm chia sẻ hạn mức sử dụng với API Địa điểm như mô tả trong tài liệu về Giới hạn sử dụng cho API Địa điểm.

Chính sách

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

Nội dung 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ư kết quả "mã địa lý", cho biết địa chỉ, khu vực hành chính như thị trấn và thành phố, cũng như các địa điểm yêu thích khác.

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 theo 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 từ cụm từ tìm kiếm

Hàm Tìm địa điểm từ truy vấn sẽ nhận dữ liệu đầu vào là văn bản và trả về một địa điểm. Dữ liệu đầ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 doanh nghiệp hoặc địa chỉ. Để tạo yêu cầu Tìm địa điểm từ truy vấn, hãy gọi phương thức findPlaceFromQuery() của PlacesService. Phương thức này sẽ nhận các tham số 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 cho thấy 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 theo số điện thoại

Tìm địa điểm từ số điện thoại sẽ lấy một số điện thoại và trả về một địa điểm. Để tạo yêu cầu Tìm địa điểm từ 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:

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ị 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 3 danh mục thanh toán: Cơ bản, Thông tin liên hệ và Không gian. Các trường cơ bản được tính phí theo mức giá cơ bản và không tính thêm phí. Các trường Liên hệ và Bầu không khí sẽ được tính phí ở mức cao hơn. Hãy xem trang tính giá để biết thêm thông tin. 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 yêu cầu hay chưa.

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

Lượt liên hệ

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

Khí quyển

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

Phương thức findPlaceFromQuery() và findPlaceFromPhoneNumber() đều lấy cùng một tập hợp trường và có thể trả về cùng một tập hợp trường trong các 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ả của tính năng 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:

Kết quả thiên vị về 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 các địa điểm trong một khu vực cụ thể theo từ khoá hoặc loại. Một kết quả 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í theo một trong hai cách sau:

Thao tác 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 mảng các đối tượng PlaceResult. Xin 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 sẽ lấy một yêu cầu có các trường sau:

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 văn bản

Dịch vụ Tìm kiếm bằng văn bản của Google Địa điểm là một dịch vụ web trả về thông tin về một tập hợp địa điểm dựa trên một 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 địa điểm khớp với chuỗi văn bản và mọi độ lệch vị trí đã được đặt. Phản hồi tìm kiếm sẽ bao gồm danh sách đị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 đế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ẽ lấy một yêu cầu có các trường sau:

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

Nội dung trả lời trên Mạng 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à:

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

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:

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 cụm từ tìm kiếm. Tuy nhiên, mỗi nội dung 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ể xem 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 chụp đối tượng PlaceSearchPagination thông qua một hàm gọi lại. Đối tượng PlaceSearchPagination được xác định là:

Để 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 được tính là một yêu cầu đối với giới hạn 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 để thu thập đối tượng PlaceSearchPagination, nhờ đó bạn có thể đưa ra nhiều yêu cầu tìm kiếm.

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ũ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ể sử dụng mã địa điểm của đị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 của người dùng và bài đánh giá, v.v.

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

Thông tin chi tiết về địa điểm được yêu cầu bằng lệnh gọi đến 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 địa điểm mong muốn và các trường cho biết 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 cần 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 (Thông tin chi tiết về địa điểm)

Tham số fields nhận một mảng 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ị phức hợp. Ví dụ: opening_hours.weekday_text.

Các trường tương ứng với kết quả của Chi tiết đị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à Không gian. Các trường cơ bản được tính theo mức giá cơ bản và không tính thêm phí. Các trường Liên hệ và Môi trường sẽ được tính phí ở mức cao hơn. Hãy xem trang tính giá để biết thêm thông tin. Thuộc tính (html_attributions) luôn được trả về với mọi lệnh gọi, bất kể lệnh gọi đó 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_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ữatrong Thư viện địa điểm, Maps JavaScript API), utc_offset_minutes,vicinity

Lượt 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 Bầu khí quyển bao gồm các trường sau:price_level, rating, reviews,user_ratings_total

Tìm hiểu thêm về 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à tính phí.

Nội dung 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 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à:

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:

Lưu ý: Điểm xếp hạng nhiều phương diện có thể không có ở một số vị trí. Nếu có quá ít bài đánh giá, thì nội dung 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 đến một Địa điểm bằng Mã địa điểm

Mã địa điểm là một 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ể 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 phải tuân thủ các quy định hạn chế về việc lưu vào bộ nhớ đệm 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. Để biết các phương pháp hay nhất khi lưu trữ mã địa điểm, hãy xem phần 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 Ả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 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 Thông tin chi tiết về địa điểm, hệ thống sẽ trả về các tệp tham chiếu ảnh cho nội dung ảnh có liên quan. 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 tham chiếu ảnh duy nhất cho mỗi địa điểm, khi có liên quan. Sau đó, bạn có thể sử dụng dịch vụ Ảnh để truy cập vào cá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 đố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.

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ệ. Đối tượng PhotoOptions cho phép bạn chỉ định chiều cao và chiều rộng tối đa mong muốn của hình ảnh. Nếu bạn chỉ định một 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 gốc.

Đoạn mã sau đây chấp nhận đố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 điểm đánh dấu mặc định sẽ đượ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ụ Photos trả về được lấy từ nhiều nguồn, bao gồm cả ảnh do chủ doanh nghiệp và người dùng đóng góp. Trong hầu hết trường hợp, bạn có thể sử dụng những bức ảnh này mà không cần ghi công hoặc sẽ có phần ghi công bắt buộc trong hình ả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 hiển thị hình ảnh.