Tìm địa điểm (Cũ)

Yêu cầu Tìm địa điểm (Cũ) nhận dữ liệu đầu vào dạng văn bản và trả về một địa điểm. Thông tin đầu vào có thể là bất kỳ loại dữ liệu văn bản nào về Địa điểm, chẳng hạn như tên, địa chỉ hoặc số điện thoại. Yêu cầu phải là một chuỗi. Yêu cầu Tìm địa điểm (Cũ) sử dụng dữ liệu không phải chuỗi, chẳng hạn như toạ độ vĩ độ/kinh độ hoặc Plus Code, sẽ tạo ra lỗi.

Yêu cầu Tìm địa điểm (Cũ)

Yêu cầu Tìm địa điểm (Cũ) là một URL loại HTTP có dạng như sau:

https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters

trong đó output có thể là một trong các giá trị sau:

• json (nên dùng) cho biết kết quả đầu ra ở định dạng Ký hiệu đối tượng JavaScript (JSON)
• xml cho biết kết quả đầu ra ở định dạng XML

Bạn phải cung cấp một số tham số nhất định để bắt đầu yêu cầu Tìm địa điểm (Cũ). Theo tiêu chuẩn trong URL, tất cả tham số đều được phân tách bằng ký tự dấu và (&).

Tham số bắt buộc

• input

  Chuỗi văn bản cần tìm kiếm. Đây phải là tên địa điểm, địa chỉ hoặc số điện thoại (ví dụ: "123 Đường Xuân Thuỷ" hoặc "Toà thị chính").

• inputtype

  Loại dữ liệu đầu vào. Đây có thể là textquery hoặc phonenumber. Số điện thoại phải ở định dạng quốc tế (bắt đầu bằng dấu cộng ("+"), theo sau là mã quốc gia, rồi đến số điện thoại). Hãy xem khuyến nghị E.164 của ITU để biết thêm thông tin.

Thông số tùy chọn

• fields

  Lưu ý: Yêu cầu Tìm kiếm địa điểm (Cũ) và yêu cầu Place Details (Cũ) không trả về cùng một trường. Yêu cầu Tìm kiếm địa điểm (Cũ) trả về một nhóm nhỏ các trường được trả về theo yêu cầu Chi tiết địa điểm (Cũ). Nếu trường bạn muốn không được trả về bằng tính năng Tìm địa điểm (Cũ), thì bạn có thể dùng tính năng Tìm địa điểm (Cũ) để lấy place_id, sau đó dùng Mã địa điểm đó để gửi yêu cầu Chi tiết địa điểm (Cũ). Để biết thêm thông tin về các trường không có sẵn trong yêu cầu Tìm kiếm địa điểm (Cũ), hãy xem phần Hỗ trợ trường Places API.

  Sử dụng tham số fields để chỉ định danh sách các loại dữ liệu địa điểm được phân tách bằng dấu phẩy cần trả về. Ví dụ: fields=formatted_address,name,geometry. Sử dụng dấu gạch chéo xuôi khi chỉ định giá trị phức hợp. Ví dụ: opening_hours/open_now.

  Các trường được chia thành ba 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 giá cơ bản, còn các trường Thông tin liên hệ và Bầu không khí được tính phí theo mức giá cao hơn. SKU Cơ bản, SKU Thông tin liên hệ và SKU Bầu không khí được tính phí ngoài SKU cơ bản (Place Details, Tìm địa điểm, Nearby Search hoặc Tìm kiếm văn bản) cho yêu cầu kích hoạt các SKU đó. Để biết thêm thông tin, hãy xem bảng giá.

  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, vicinity, wheelchair_accessible_entrance.

  Thông tin liên hệ

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

  Không gian

  Danh mục Bầu không khí bao gồm các trường sau: curbside_pickup, delivery, dine_in, editorial_summary, price_level, rating, reservable, reviews, serves_beer, serves_breakfast, serves_brunch, serves_dinner, serves_lunch, serves_vegetarian_food, serves_wine, takeout, user_ratings_total.

  Lưu ý: Thông tin ghi nhận tác giả, html_attributions, luôn được trả về trong mỗi lệnh gọi, bất kể trường này có được yêu cầu hay không.

• language

  Ngôn ngữ để trả về kết quả.

  • Xem danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.
  • Nếu bạn không cung cấp language, API sẽ cố gắng sử dụng ngôn ngữ ưu tiên như được chỉ định trong tiêu đề Accept-Language.
  • API này cố gắng hết sức để cung cấp địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, API này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một hệ thống chữ viết mà người dùng có thể đọc được (nếu cần), đồng thời tuân thủ ngôn ngữ ưu tiên. Tất cả các địa chỉ khác được trả về bằng ngôn ngữ ưu tiên. Tất cả thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
  • Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng tên phù hợp nhất.
  • Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến nhóm kết quả mà API chọn trả về và thứ tự trả về. Bộ mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utca và tér là các từ đồng nghĩa với "đường" trong tiếng Hungary.

• locationbias

  Ưu tiên kết quả trong một khu vực cụ thể bằng cách chỉ định bán kính cộng với vĩ độ/kinh độ hoặc hai cặp vĩ độ/kinh độ đại diện cho các điểm của hình chữ nhật. Nếu bạn không chỉ định tham số này, thì theo mặc định, API sẽ sử dụng tính năng thiên vị địa chỉ IP.

  • Xu hướng IP: Hướng dẫn API sử dụng xu hướng địa chỉ IP. Truyền chuỗi ipbias (tuỳ chọn này không có tham số bổ sung).
  • Hình tròn: Một chuỗi chỉ định bán kính tính bằng mét, cộng với vĩ độ/kinh độ theo độ thập phân. Hãy dùng định dạng sau: circle:radius@lat,lng.
  • Hình chữ nhật: Một chuỗi chỉ định hai cặp vĩ độ/kinh độ theo độ thập phân, biểu thị các điểm nam/tây và bắc/đông của một hình chữ nhật. Hãy dùng định dạng sau:rectangle:south,west|north,east. Lưu ý rằng các giá trị đông/tây được gói trong phạm vi -180, 180 và các giá trị bắc/nam được giới hạn trong phạm vi -90, 90.

Ví dụ về Tìm địa điểm (Cũ)

Ví dụ sau đây cho thấy một yêu cầu Tìm địa điểm (Cũ) cho "Bảo tàng Nghệ thuật Đương đại Úc", bao gồm các trường photos, formatted_address, name, rating, opening_hours và geometry:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

Ví dụ sau đây cho thấy một yêu cầu Tìm địa điểm (Cũ) cho "Mongolian Grill", sử dụng tham số locationbias để ưu tiên kết quả trong phạm vi 2.000 mét tính từ toạ độ đã chỉ định:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

Ví dụ sau đây cho thấy một yêu cầu Tìm địa điểm (Cũ) cho một số điện thoại. Xin lưu ý rằng tiền tố cuộc gọi quốc tế "+" đã được mã hoá thành %2B để yêu cầu này là một URL tuân thủ. Nếu không được mã hoá, tiền tố + sẽ được giải mã thành một dấu cách trên máy chủ, dẫn đến việc tra cứu số điện thoại không hợp lệ.

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

Phản hồi của dịch vụ Tìm địa điểm (Cũ)

Phản hồi của dịch vụ Tìm địa điểm (Cũ) chỉ chứa các loại dữ liệu được chỉ định bằng tham số fields, cộng với html_attributions. Ví dụ sau đây cho thấy phản hồi cho một yêu cầu Tìm địa điểm (Cũ) về "Bảo tàng Nghệ thuật Đương đại Úc", bao gồm các trường formatted_address, geometry, name, opening_hours, photos, rating.

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}    

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

    

PlacesFindPlaceFromTextResponse

PlacesSearchStatus

Mã trạng thái do dịch vụ trả về.

• OK cho biết yêu cầu API đã thành công.
• ZERO_RESULTS cho biết rằng lượt tìm kiếm đã thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu kết quả tìm kiếm được chuyển đến một latlng ở vị trí từ xa.
• INVALID_REQUEST cho biết yêu cầu API không đúng định dạng, thường là do thiếu tham số truy vấn bắt buộc (location hoặc radius).
• OVER_QUERY_LIMIT cho biết bất kỳ điều nào sau đây:
  • Bạn đã vượt quá giới hạn QPS.
  • Bạn chưa bật tính năng thanh toán trên tài khoản của mình.
  • Bạn đã vượt quá khoản tín dụng 200 USD hằng tháng hoặc hạn mức sử dụng do bạn tự đặt ra.
  • Phương thức thanh toán được cung cấp không còn hợp lệ (ví dụ: thẻ tín dụng đã hết hạn).
  Hãy xem phần Câu hỏi thường gặp về Maps để biết thêm thông tin về cách giải quyết lỗi này.
• REQUEST_DENIED cho biết yêu cầu của bạn đã bị từ chối, thường là do:
  • Yêu cầu thiếu khoá API.
  • Tham số key không hợp lệ.
• UNKNOWN_ERROR cho biết lỗi không xác định.

Địa điểm

Phản hồi của tính năng Tìm kiếm địa điểm trả về một nhóm nhỏ các trường Địa điểm sau đây. Không phải loại địa điểm nào cũng có tất cả các thuộc tính. Để truy xuất các trường mà tính năng Tìm kiếm địa điểm không trả về, chẳng hạn như address_components, formatted_phone_number, reviews hoặc website, hãy truyền place_id được trả về trong một yêu cầu Place Details (Phiên bản cũ). Để biết thông tin về phạm vi cung cấp của trường và các cấp giá trên các điểm cuối, hãy xem phần Trường dữ liệu địa điểm (Cũ).