search_places |
Gọi công cụ này khi người dùng yêu cầu tìm địa điểm, doanh nghiệp, địa chỉ, vị trí, địa điểm yêu thích hoặc bất kỳ nội dung tìm kiếm có liên quan nào khác liên quan đến Google Maps. Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG):
text_query (chuỗi – BẮT BUỘC): Cụm từ tìm kiếm chính. Điều này phải xác định rõ ràng những gì người dùng đang tìm kiếm.
- Ví dụ:
'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
- Đối với thông tin chi tiết về địa điểm cụ thể: Thêm thuộc tính được yêu cầu (ví dụ:
'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').
location_bias (đối tượng – KHÔNG BẮT BUỘC): Sử dụng đối tượng này để ưu tiên kết quả gần một khu vực địa lý cụ thể.
- Định dạng:
{"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
- Cách sử dụng:
- Để thiên về bán kính 5 km:
{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
- Để thiên về điểm giữa:
{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (bỏ qua radius_meters).
language_code (chuỗi – KHÔNG BẮT BUỘC): Ngôn ngữ dùng để hiển thị bản tóm tắt kết quả tìm kiếm.
- Định dạng: Mã ngôn ngữ gồm hai chữ cái (ISO 639-1), có thể theo sau là dấu gạch dưới và mã quốc gia gồm hai chữ cái (ISO 3166-1 alpha-2), ví dụ:
en, ja, en_US, zh_CN, es_MX. Nếu bạn không cung cấp mã ngôn ngữ, kết quả sẽ được trả về bằng tiếng Anh.
region_code (chuỗi – KHÔNG BẮT BUỘC): Mã vùng CLDR Unicode của người dùng. Tham số này được dùng để hiển thị Place Details, chẳng hạn như tên địa điểm theo khu vực cụ thể (nếu có). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
- Định dạng: Mã quốc gia gồm hai chữ cái (ISO 3166-1 alpha-2), ví dụ:
US, CA.
Hướng dẫn gọi công cụ:
Thông tin vị trí (QUAN TRỌNG): Nội dung tìm kiếm phải chứa đủ thông tin vị trí. Nếu vị trí không rõ ràng (ví dụ: chỉ "quán pizza"), bạn phải chỉ định vị trí đó trong text_query (ví dụ: "quán pizza ở New York") hoặc sử dụng tham số location_bias. Thêm tên thành phố, tiểu bang/tỉnh và khu vực/quốc gia nếu cần để phân biệt. Luôn cung cấp text_query cụ thể và có nhiều ngữ cảnh nhất có thể. Chỉ sử dụng location_bias nếu toạ độ được cung cấp rõ ràng hoặc nếu việc suy luận vị trí từ bối cảnh đã biết của người dùng là phù hợp và cần thiết để có kết quả tốt hơn. Kết quả có căn cứ phải được ghi nhận cho nguồn bằng cách sử dụng thông tin trong trường attribution (nếu có).
|
lookup_weather |
Truy xuất dữ liệu thời tiết toàn diện, bao gồm cả tình hình hiện tại, thông tin dự báo hằng giờ và hằng ngày. Dữ liệu cụ thể được cung cấp: Nhiệt độ (Hiện tại, Nhiệt độ cảm nhận, Nhiệt độ tối đa/tối thiểu, Chỉ số nhiệt), Gió (Tốc độ, Gió giật, Hướng), Sự kiện thiên văn (Bình minh/Hoàng hôn, Pha Mặt Trăng), Lượng mưa (Loại, Xác suất, Lượng mưa/QPF), Điều kiện khí quyển (Chỉ số UV, Độ ẩm, Độ che phủ của mây, Xác suất có giông bão) và Địa chỉ vị trí được mã hoá địa lý. Vị trí và quy tắc về vị trí (QUAN TRỌNG): Vị trí mà bạn yêu cầu dữ liệu thời tiết được chỉ định bằng trường location. Trường này là một cấu trúc "oneof", nghĩa là bạn CHỈ ĐƯỢC cung cấp giá trị cho MỘT TRONG ba trường phụ về vị trí bên dưới để đảm bảo tra cứu dữ liệu thời tiết chính xác.
Toạ độ địa lý (lat_lng)
- Sử dụng khi bạn được cung cấp toạ độ vĩ độ/kinh độ chính xác.
- Ví dụ: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // Los Angeles
Mã địa điểm (place_id)
- Giá trị nhận dạng chuỗi rõ ràng (Mã địa điểm trên Google Maps).
- Bạn có thể tìm nạp place_id từ công cụ search_places.
- Ví dụ: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // Tháp Eiffel
Chuỗi địa chỉ (address)
- Một chuỗi dạng tuỳ ý cần có thông tin cụ thể để mã hoá địa lý.
- Thành phố và khu vực: Luôn bao gồm khu vực/quốc gia (ví dụ: "London, Vương quốc Anh", không phải "London").
- Địa chỉ đường phố: Cung cấp địa chỉ đầy đủ (ví dụ: "1600 Pennsylvania Ave NW, Washington, DC").
- Mã bưu chính/Mã ZIP: PHẢI đi kèm với tên quốc gia (ví dụ: "90210, Hoa Kỳ", KHÔNG PHẢI "90210").
- Ví dụ: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}
Chế độ sử dụng:
Thời tiết hiện tại: Chỉ cung cấp location. Đừng chỉ định date và hour. Dự báo hằng giờ: Cung cấp location, date và hour (0-23). Sử dụng cho các thời điểm cụ thể (ví dụ: "lúc 5 giờ chiều") hoặc các cụm từ như "vài giờ tới" hoặc "cuối ngày hôm nay". Nếu người dùng chỉ định phút, hãy làm tròn xuống giờ gần nhất. Không hỗ trợ dự báo theo giờ sau 120 giờ kể từ bây giờ. Dữ liệu thời tiết hằng giờ trong quá khứ được hỗ trợ trong tối đa 24 giờ trước. Dự báo hằng ngày: Cung cấp location và date. Đừng chỉ định hour. Dùng cho các yêu cầu chung về ngày (ví dụ: "thời tiết ngày mai", "thời tiết thứ Sáu", "thời tiết ngày 25/12"). Nếu ngày hôm nay không có trong bối cảnh, bạn nên làm rõ ngày hôm nay với người dùng. Không hỗ trợ thông tin dự báo hằng ngày sau 10 ngày kể từ hôm nay. Không hỗ trợ dữ liệu thời tiết trong quá khứ. Các quy tắc ràng buộc về tham số:
|
compute_routes |
Tính toán tuyến đường di chuyển giữa điểm xuất phát và điểm đến, có thể thông qua các điểm dừng trung gian. Trả về khoảng cách và thời gian cho mỗi tuyến đường. Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG):
origin và destination (đối tượng – BẮT BUỘC): Mỗi đối tượng phải được cung cấp bằng cách sử dụng chính xác một trong các đối tượng sau:
address (chuỗi, ví dụ: 'Eiffel Tower, Paris'). Các địa điểm, địa danh và doanh nghiệp có tên được phân giải trực tiếp, vì vậy, KHÔNG gọi search_places trước chỉ để mã hoá địa lý một điểm tham chiếu. Thêm mọi thành phố, khu vực hoặc quốc gia mà người dùng đề cập.lat_lng (đối tượng, {"latitude": number, "longitude": number}).place_id (chuỗi, ví dụ: 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), chẳng hạn như từ search_places. intermediate_waypoints (mảng đối tượng – KHÔNG BẮT BUỘC): Tối đa 10 điểm dừng để đi qua, theo thứ tự, giữa điểm xuất phát và điểm đến. Định dạng tương tự như origin. Không được hỗ trợ với TRANSIT. Chỉ bao gồm những điểm dừng mà người dùng yêu cầu.
travel_mode (enum – KHÔNG BẮT BUỘC): DRIVE (mặc định), WALK, BICYCLE hoặc TRANSIT.
Thời gian (KHÔNG BẮT BUỘC – đặt tối đa MỘT): Dấu thời gian RFC 3339 có độ lệch UTC, ví dụ: '2026-09-19T08:00:00-07:00'. Mặc định là khởi hành ngay. Đối với TRANSIT, thời gian có thể là tối đa 7 ngày trước hoặc tối đa 100 ngày sau. Đối với các chế độ khác, thời gian có thể lên đến 365 ngày trong tương lai và không được là thời gian trong quá khứ.
departure_time: Sử dụng khi người dùng cho biết thời điểm họ sẽ rời đi (ví dụ: "8 giờ sáng mai").arrival_time: Sử dụng khi người dùng cho biết thời điểm họ phải đến (ví dụ: "đến đó trước 9 giờ sáng"). routing_preference (enum – KHÔNG BẮT BUỘC):
ROUTING_PREFERENCE_TRAFFIC_UNAWARE (mặc định): bỏ qua tình hình giao thông trực tiếp, sự cố và đường bị đóng. Độ trễ thấp nhất.ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: sử dụng tình trạng giao thông theo thời gian thực (nếu có). Không hỗ trợ WALK hoặc BICYCLE. CHỈ đặt trạng thái này khi người dùng hỏi về tình hình giao thông, tình trạng tắc nghẽn hoặc thời gian đến dự kiến đã điều chỉnh theo tình hình giao thông. Điều này làm tăng chi phí và độ trễ. location_bias (đối tượng – KHÔNG BẮT BUỘC): {"latitude": number, "longitude": number} dùng để phân biệt tên địa điểm trong địa chỉ điểm trung gian. Nếu tên không rõ ràng (ví dụ: "Springfield") và người dùng không cung cấp khu vực, hãy giữ nguyên tên được cung cấp trong address và đặt location_bias theo khu vực dự kiến thay vì đoán khu vực.
compute_alternative_routes (boolean – KHÔNG BẮT BUỘC): Chỉ đặt thành true khi người dùng yêu cầu các lựa chọn hoặc tuyến đường thay thế. Giá trị mặc định là false, chỉ trả về tuyến đường được đề xuất.
include_polyline (boolean – KHÔNG BẮT BUỘC): Chỉ đặt thành true khi cần có hình học tuyến đường (encoded_polyline). Giá trị mặc định là false.
Hướng dẫn gọi công cụ:
- Nếu thiếu điểm xuất phát hoặc điểm đến, bạn PHẢI yêu cầu người dùng làm rõ trước khi gọi công cụ.
- Đối với câu hỏi "A cách B bao xa?", hãy dùng B làm
origin và A làm destination.
Ví dụ về lệnh gọi công cụ: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"} Hướng dẫn trả lời:
- Khi bạn yêu cầu tuyến đường thay thế, các tuyến đường sẽ được sắp xếp theo thứ tự từ nên dùng nhất đến ít nên dùng nhất.
- Nếu
routes trống, hãy thông báo cho người dùng rằng không tìm thấy tuyến đường nào. Đừng đoán tuyến đường.
- Chỉ nêu những thông tin thực tế do công cụ trả về. KHÔNG tự tạo hướng dẫn từng chặng, tuyến phương tiện công cộng, nhà ga, sân ga hoặc điểm trung chuyển.
- Kết quả có căn cứ phải được ghi nhận cho nguồn bằng cách sử dụng trường
attribution của mỗi tuyến đường (nếu có).
|
resolve_names |
Phân giải một danh sách theo lô gồm các cụm từ tìm kiếm vị trí cụ thể (tên địa danh hoặc địa chỉ chính xác) thành Mã địa điểm chuẩn trên Google Maps. Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG):
queries (mảng đối tượng – BẮT BUỘC): Danh sách các cụm từ tìm kiếm vị trí cần phân giải. Bạn có thể chỉ định tối đa 20 cụm từ tìm kiếm.
- Mỗi đối tượng truy vấn phải có:
text (chuỗi – BẮT BUỘC): Cụm từ tìm kiếm dạng văn bản đại diện cho một tên hoặc địa chỉ địa điểm cụ thể cần phân giải.
- Ví dụ:
'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.
location_bias (đối tượng – KHÔNG BẮT BUỘC): Sử dụng đối tượng này để ưu tiên kết quả gần một khu vực địa lý cụ thể.
- Định dạng:
{"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}
region_code (chuỗi – KHÔNG BẮT BUỘC): Mã vùng CLDR Unicode (mã quốc gia gồm hai chữ cái, ví dụ: US, CA) của người dùng để thiên vị kết quả.
Hướng dẫn gọi công cụ:
- Tính cụ thể (QUAN TRỌNG): Cụm từ tìm kiếm phải thể hiện tên hoặc địa chỉ của một địa điểm cụ thể. Chúng tôi không hỗ trợ các cụm từ tìm kiếm chung như
'restaurants' hoặc tên chuỗi như 'Starbucks'.
- KHÔNG gọi công cụ này nếu các công cụ hạ nguồn mà bạn dự định gọi đã chấp nhận trực tiếp chuỗi địa chỉ thô hoặc tên địa điểm.
Lưu vào Google Maps:
- Phản hồi bao gồm một trường
save_to_maps_url: một đường liên kết duy nhất đến Google Maps chứa tất cả địa điểm đã được phân giải thành công.
- Khi người dùng muốn lưu, chia sẻ hoặc mở các địa điểm đã phân giải dưới dạng danh sách trong Google Maps, hãy hiển thị đường liên kết này cho người dùng. ĐỪNG tự tạo đường liên kết này.
Xử lý lỗi (QUAN TRỌNG):
- Đây là công cụ xử lý hàng loạt. Một yêu cầu có thể trả về "kết quả hỗn hợp" (ví dụ: một số truy vấn phân giải thành công trong khi một số khác không thành công).
- Danh sách đầu ra của
results được đảm bảo ánh xạ 1:1 với các chỉ mục queries đầu vào. Một truy vấn không thành công sẽ dẫn đến thông báo Result trống (không có entity nào được đặt) tại chỉ mục tương ứng trong danh sách results.
- Bạn PHẢI kiểm tra trường bản đồ
failed_requests trong phản hồi để xác định chỉ mục truy vấn cụ thể nào không thành công. Khoá của failed_requests đại diện cho chỉ mục dựa trên 0 của truy vấn không thành công trong yêu cầu. Đừng cho rằng toàn bộ lệnh gọi theo lô đều không thành công vì một phần không thành công.
|
resolve_maps_urls |
Phân giải danh sách URL trên Google Maps thành Mã địa điểm chính tắc trên Google Maps. Trường hợp nên gọi công cụ này (QUAN TRỌNG):
- Sử dụng công cụ này khi người dùng cung cấp một hoặc nhiều đường liên kết hoặc URL chia sẻ trên Google Maps (ví dụ: "https://maps.app.goo.gl/...", "https://www.google.com/maps/place/..." hoặc "https://maps.google.com/...") và bạn cần trích xuất Mã địa điểm chính tắc cơ bản.
- Bạn có thể chỉ định tối đa 20 URL để phân giải trong một yêu cầu theo lô.
Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG):
urls (mảng chuỗi – BẮT BUỘC): Danh sách URL của Google Maps cần phân giải. Mỗi URL phải là một URL hợp lệ, chỉ đến một địa điểm duy nhất trên Google Maps. Lưu vào Google Maps:
- Phản hồi bao gồm một trường
save_to_maps_url: một đường liên kết duy nhất đến Google Maps chứa tất cả địa điểm đã được phân giải thành công.
- Khi người dùng muốn lưu, chia sẻ hoặc mở các địa điểm đã phân giải dưới dạng danh sách trong Google Maps (ví dụ: thu thập các địa điểm được chia sẻ trong một cuộc trò chuyện), hãy cung cấp đường liên kết này cho người dùng. ĐỪNG tự tạo đường liên kết này.
Xử lý lỗi (QUAN TRỌNG):
- Đây là công cụ xử lý hàng loạt. Một yêu cầu có thể trả về "kết quả hỗn hợp" (ví dụ: một số URL phân giải thành công trong khi một số khác không thành công).
- Danh sách đầu ra của
entities được đảm bảo ánh xạ 1:1 với các chỉ mục urls đầu vào. Nếu không phân giải được URL, thì thông báo Entity sẽ trống (không có trường nào được đặt) tại chỉ mục tương ứng trong danh sách entities.
- Bạn PHẢI kiểm tra trường bản đồ
failed_requests trong phản hồi để xác định chỉ mục URL cụ thể nào không thành công. Khoá của failed_requests đại diện cho chỉ mục dựa trên 0 của URL không thành công trong yêu cầu. Đừng cho rằng toàn bộ lệnh gọi theo lô đều không thành công vì một phần không thành công.
|
