Các phương thức của Geocoding API v4 có hạn mức mặc định là 25 truy vấn mỗi giây (QPS). Để biết thông tin về cách yêu cầu hạn mức cao hơn, hãy xem bài viết Xem và quản lý hạn mức rồi chọn Geocoding API làm dịch vụ.

Tìm điểm đến

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

A Destination đề cập đến một địa điểm yêu thích quan trọng hoặc một vị trí cụ thể mà người dùng dự định đến hoặc di chuyển đến. Destination có thể bao gồm thông tin như điểm điều hướng, địa danh, lối vào và đường viền của toà nhà.

Phương thức SearchDestinations của Geocoding API (API Mã hoá địa lý) cho phép bạn truy xuất thông tin chi tiết về nhiều đích đến dựa trên các tiêu chí đầu vào khác nhau, chẳng hạn như địa chỉ, mã địa điểm hoặc toạ độ vĩ độ và kinh độ.

Yêu cầu tìm kiếm đích đến

Yêu cầu tìm kiếm đích đến là một yêu cầu HTTP POST đến một URL ở dạng:

https://geocode.googleapis.com/v4/geocode/destinations

Truyền tất cả các tham số trong nội dung yêu cầu JSON hoặc trong tiêu đề dưới dạng một phần của yêu cầu POST. Ví dụ:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

Bạn có thể chỉ định vị trí để tìm kiếm một đích đến theo một trong 3 cách:

Địa chỉ
Mã địa điểm
Vĩ độ và kinh độ

Tìm kiếm một đích đến theo địa chỉ

Bạn có thể chỉ định địa chỉ dưới dạng một chuỗi không có cấu trúc. Tính năng mã hoá địa lý không phân giải toạ độ vĩ độ và kinh độ hoặc các chuỗi không có cấu trúc khác không đại diện cho một địa chỉ. Các yêu cầu sử dụng những chuỗi như vậy không được hỗ trợ và có thể dẫn đến phản hồi lỗi hoặc hành vi không xác định. Sau đây là một số ví dụ về truy vấn không được hỗ trợ:

Loại truy vấn	Ví dụ:
Vĩ độ và kinh độ. Thay vào đó, hãy sử dụng truy vấn vị trí.	"37.422131,-122.084801"
Có quá nhiều khái niệm hoặc ràng buộc, chẳng hạn như tên của nhiều địa điểm, đường hoặc thành phố trong một truy vấn	"Market Street San Francisco San Jose Airport"
Các thành phần địa chỉ bưu chính không được biểu thị trên Google Maps	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
Tên của doanh nghiệp, chuỗi cửa hàng hoặc danh mục kết hợp với các vị trí mà những thực thể này không có	"Tesco near Dallas, Texas"
Truy vấn không rõ ràng có nhiều cách diễn giải	"Charger drop-off"
Tên cũ không còn được sử dụng	"Middlesex United Kingdom"
Ý định hoặc thành phần không gian địa lý	"How many boats are in Ventura Harbor?"
Tên không chính thức hoặc tên tuỳ chỉnh	"The Jenga" "The Helter Skelter"
Các thực thể chính trị lớn (Thành phố, Tiểu bang, Quốc gia)	"New York City" "California" "USA"
Tuyến đường không có địa chỉ cụ thể	"1st Ave., NYC, NY" "I-95"

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

hoặc dưới dạng postalAddress:

curl -X POST -d '{
  "addressQuery": {
    "address": {
      "addressLines": ["601 S Bernardo Ave"],
      "locality": "Sunnyvale",
      "postalCode": "94087",
      "administrativeArea": "CA",
      "regionCode": "US"
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

Bạn thường sử dụng định dạng postalAddress khi xử lý các thành phần địa chỉ được thu thập trong biểu mẫu HTML.

Tìm kiếm một đích đến theo mã địa điểm

Bạn có thể truy xuất một đích đến bằng cách cung cấp một mã địa điểm:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

Mã địa điểm được hỗ trợ

Phương thức Tìm kiếm đích đến hoạt động hiệu quả nhất với Mã địa điểm đại diện cho các đích đến cụ thể, có thể điều hướng. Mã địa điểm cho các loại như establishment, point_of_interest, premise, street_address, và subpremise thường được hỗ trợ. Mã địa điểm không đại diện cho các vị trí riêng biệt, chẳng hạn như mã địa điểm được suy ra từ phạm vi địa chỉ (ví dụ: "10-20 Main St"), các phần của một tuyến đường không có số cụ thể hoặc mã cộng không được hỗ trợ. Mã địa điểm cho các kết quả có diện tích quá lớn (ví dụ: "Thái Bình Dương") cũng không được hỗ trợ.

Sử dụng tính năng Tự động hoàn thành của Places API (Mới) với tính năng Tìm kiếm đích đến

Để đảm bảo khả năng tương thích, hãy sử dụng tính năng Tự động hoàn thành của Places API (Mới) để tìm Mã địa điểm dùng với tính năng Tìm kiếm đích đến. Khi sử dụng tính năng Tự động hoàn thành, bạn nên lọc kết quả theo loại bằng cách sử dụng includedPrimaryTypes tham số. Mã địa điểm do tính năng Tự động hoàn thành trả về bằng bộ lọc được đề xuất sau đây được tính năng Tìm kiếm đích đến hỗ trợ:

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

Ngoài ra, bạn không nên đặt include_pure_service_area_businesses cờ thành true trong yêu cầu Tự động hoàn thành.

Tìm kiếm một đích đến theo vị trí

Bạn có thể tìm kiếm một đích đến bằng cách cung cấp toạ độ vĩ độ và kinh độ:

curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

Sử dụng OAuth để tạo yêu cầu

Geocoding API phiên bản 4 hỗ trợ OAuth 2.0 để xác thực. Để sử dụng OAuth với Geocoding API, bạn phải gán phạm vi chính xác cho mã thông báo OAuth. Geocoding API hỗ trợ các phạm vi sau đây để sử dụng với phương thức Đích đến:

https://www.googleapis.com/auth/maps-platform.geocode – Sử dụng với tất cả các phương thức Geocoding API.

Ngoài ra, bạn có thể sử dụng phạm vi https://www.googleapis.com/auth/cloud-platform chung cho tất cả các phương thức Geocoding API. Phạm vi đó hữu ích trong quá trình phát triển nhưng không hữu ích trong quá trình sản xuất vì đây là phạm vi chung cho phép truy cập vào tất cả các phương thức.

Để biết thêm thông tin và ví dụ, hãy xem bài viết Sử dụng OAuth.

Phản hồi tìm kiếm đích đến

Phản hồi Tìm kiếm đích đến cung cấp thông tin theo bối cảnh chi tiết, theo từng khu vực cụ thể về vị trí.

Các đối tượng PlaceView trong phản hồi Tìm kiếm đích đến (chẳng hạn như primary, các mục trong containingPlaces, và landmarks) sử dụng các trường để cho biết loại địa điểm:

types: Một mảng các chuỗi cho biết(các) loại địa điểm.
primaryType: Một chuỗi cho biết loại chính của địa điểm.

Các giá trị chuỗi có thể có cho cả types và primaryType được lấy từ Bảng A và Bảng B trên trang Loại địa điểm (Mới).

Phần này mô tả các trường phản hồi chính. Để biết đầy đủ thông tin chi tiết về tất cả các trường phản hồi, hãy xem Tài liệu tham khảo về API.

`primary`

Địa điểm chính do truy vấn xác định trong yêu cầu.

`containingPlaces`

Các thực thể lớn hơn mà đích đến chính là một phần của thực thể đó (ví dụ: một trung tâm mua sắm có chứa một cửa hàng).

`subDestinations`

Các vị trí cụ thể hơn trong đích đến chính (ví dụ: các căn hộ trong một toà nhà).

`entrances`

Các đối tượng trong mảng entrances[] có các trường sau:

location

Một cặp toạ độ vĩ độ/kinh độ duy nhất xác định vị trí của một điểm vào và điểm ra vào một địa điểm.
entrance_tags[]

Một mảng các thẻ lối vào mô tả các đặc điểm của lối vào. Giá trị sau đây được hỗ trợ:
- "PREFERRED"
Cho biết lối vào này có thể cung cấp quyền truy cập thực tế vào địa điểm được trả về. Một địa điểm có thể có nhiều lối vào ưu tiên. Nếu một lối vào không có thẻ này, thì có nghĩa là lối vào đó nằm trên cùng một toà nhà nhưng không nhất thiết cung cấp quyền truy cập vào địa điểm.

Ví dụ: nếu địa điểm được trả về là một nhà hàng trong một khu mua sắm, thì các lối vào "PREFERRED" sẽ là những lối vào dẫn vào chính nhà hàng đó, trong khi các lối vào được trả về khác sẽ là các lối vào khác cho toà nhà, chẳng hạn như lối vào các nhà hàng khác trong khu mua sắm.

Nếu địa điểm được trả về là chính toà nhà đó, thì các lối vào "PREFERRED" sẽ là những lối vào dẫn vào phần "chính" của toà nhà. Ví dụ: trong một trung tâm mua sắm, các lối vào "PREFERRED" sẽ là những lối vào cho phép truy cập vào khu vực sảnh chính, nhưng nếu một lối vào chỉ cung cấp quyền truy cập vào một cửa hàng ở bên cạnh toà nhà, thì đó sẽ không phải là lối vào "PREFERRED".

`structureType`

Loại cấu trúc mà địa điểm này đại diện.

POINT

Một vị trí điểm.
SECTION

Một phần phụ của toà nhà.
BUILDING

Một toà nhà.
GROUNDS

Một khu vực rộng lớn thường chứa nhiều toà nhà, chẳng hạn như khuôn viên trường đại học, khu chung cư hoặc trung tâm mua sắm.

`navigationPoints`

Trường navigationPoints trong phản hồi Mã hoá địa lý chứa danh sách các điểm hữu ích để di chuyển đến địa điểm. Cụ thể, bạn nên sử dụng các điểm này làm điểm bắt đầu hoặc điểm kết thúc khi định tuyến trên mạng lưới đường bộ từ hoặc đến địa điểm. Mỗi điểm điều hướng chứa các giá trị sau:

navigationPointToken là một mã thông báo chứa thông tin theo bối cảnh trong trường navigationPoints. Bạn có thể gửi mã thông báo này đến các API định tuyến và điều hướng để cải thiện trải nghiệm định tuyến và sông trong ứng dụng của mình. Hãy xem bài viết Định tuyến bằng mã thông báo điểm điều hướng để biết thêm thông tin.
location chứa giá trị vĩ độ, kinh độ của điểm điều hướng. Vị trí này sẽ luôn rất gần với mạng lưới đường bộ và đại diện cho một điểm dừng hoặc điểm xuất phát lý tưởng để di chuyển đến và đi từ một địa điểm. Điểm này được cố ý đặt lệch một chút so với đường tâm của đường để đánh dấu rõ ràng phía đường nơi địa điểm đó nằm.
travelModes là danh sách các chế độ di chuyển mà bạn có thể truy cập vào điểm điều hướng:
- "DRIVE" là chế độ di chuyển tương ứng với chỉ đường lái xe.
- "WALK" là chế độ di chuyển tương ứng với chỉ đường đi bộ.
usages là danh sách các mục đích sử dụng được điểm điều hướng hỗ trợ. Các mục đích sử dụng có thể là:
- "DROPOFF"
- "PICKUP"
- "PARKING"

`arrivalSummary`

Thông tin chi tiết dựa trên AI để hỗ trợ việc đến. Xem phần Thông tin tóm tắt dựa trên AI.

`landmarks`

Các địa điểm đáng chú ý ở gần đó để giúp người dùng hiểu được môi trường xung quanh đích đến.

Định dạng của phản hồi

SearchDestinations trả về SearchDestinationsResponse ở dạng JSON sau:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }
      },
      "containingPlaces": [
        {
          "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw",
          "displayName": {
            "text": "Cherry Chase Shopping Center",
            "languageCode": "en"
          },
          "primaryType": "shopping_mall",
          "types": [
            "shopping_mall",
            "point_of_interest",
            "establishment"
          ],
          "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA",
          "postalAddress": {
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94087-1020",
            "administrativeArea": "CA",
            "locality": "Sunnyvale",
            "addressLines": [
              "663 S Bernardo Ave"
            ]
          },
          "structureType": "GROUNDS",
          "location": {
            "latitude": 37.3731231,
            "longitude": -122.0578211
          },
          "displayPolygon": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -122.057112227103,
                  37.3714618008523
                ],
                [
                  -122.057076849821,
                  37.3715743611411
                ],
                [
                  -122.056963607756,
                  37.3719081793948
                ],
                [
                  -122.056865279559,
                  37.3722026053835
                ],
                [
                  -122.056687872374,
                  37.3727258358476
                ],
                [
                  -122.056580005889,
                  37.3730511370747
                ],
                [
                  -122.056498845827,
                  37.3732994782583
                ],
                [
                  -122.056338259713,
                  37.3737878663325
                ],
                [
                  -122.056618678291,
                  37.373887693582
                ],
                [
                  -122.056912102521,
                  37.3740010327191
                ],
                [
                  -122.057532418159,
                  37.3742476426462
                ],
                [
                  -122.057673926626,
                  37.3742441740031
                ],
                [
                  -122.057735663106,
                  37.3742328516943
                ],
                [
                  -122.057766531332,
                  37.3742220604378
                ],
                [
                  -122.057797572967,
                  37.37420520725
                ],
                [
                  -122.057828267759,
                  37.3741852342085
                ],
                [
                  -122.058060299297,
                  37.3740060842535
                ],
                [
                  -122.058199726081,
                  37.3737861673422
                ],
                [
                  -122.05836707267,
                  37.373524542556
                ],
                [
                  -122.058569622393,
                  37.3732018598683
                ],
                [
                  -122.0587638478,
                  37.3728890198039
                ],
                [
                  -122.058934661823,
                  37.3726036257774
                ],
                [
                  -122.059164956851,
                  37.3722498383629
                ],
                [
                  -122.058997784906,
                  37.3721804442035
                ],
                [
                  -122.057936479838,
                  37.3717605636234
                ],
                [
                  -122.057495827092,
                  37.3715860151634
                ],
                [
                  -122.057112227103,
                  37.3714618008523
                ]
              ]
            ]
          }
        }
      ],
      "landmarks": [
        {
          "place": {
            "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg",
            "displayName": {
              "text": "Chase Bank",
              "languageCode": "en"
            },
            "primaryType": "bank",
            "types": [
              "bank",
              "atm",
              "finance",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1234 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.373579,
              "longitude": -122.05752700000001
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "639 S Bernardo Ave"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3727912,
              "longitude": -122.0581172
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "fast_food_restaurant",
              "restaurant",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1028",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1241 W El Camino Real"
              ]
            },
            "structureType": "BUILDING",
            "location": {
              "latitude": 37.3746764,
              "longitude": -122.05708860000001
            },
            "displayPolygon": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

Thông số bắt buộc

Bạn phải có một trong 3 tham số sau đây trong yêu cầu API. Tham số này chỉ định địa chỉ, địa điểm hoặc vị trí để tìm kiếm một đích đến:
- addressQuery – địa chỉ để tìm kiếm.
- place – mã địa điểm của địa điểm để tìm kiếm.
- locationQuery – toạ độ vĩ độ và kinh độ của vị trí để tìm kiếm.
FieldMask

Chỉ định danh sách các trường cần trả về trong phản hồi bằng cách tạo mặt nạ trường phản hồi. Truyền mặt nạ trường phản hồi đến phương thức bằng cách sử dụng tham số URL $fields hoặc fields, hoặc bằng cách sử dụng tiêu đề HTTP X-Goog-FieldMask. Ví dụ: yêu cầu bên dưới sẽ chỉ trả về lối vào, điểm điều hướng và mã địa điểm của đích đến chính.
```
  curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
    -H "X-Goog-Api-Key: API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
    https://geocode.googleapis.com/v4/geocode/destinations
  
```
Không có danh sách mặc định các trường được trả về trong phản hồi. Nếu bạn bỏ qua mặt nạ trường, phương thức sẽ trả về lỗi. Đặt mặt nạ trường thành * để trả về tất cả các trường. Xem phần Chọn các trường cần trả về để biết thêm thông tin chi tiết.

Thông số tùy chọn

travelModes

Chỉ định loại navigationPoints cần trả về. Các điểm điều hướng cho các chế độ di chuyển khác sẽ bị lọc bỏ. Nếu travelModes không được đặt, thì các điểm điều hướng của tất cả các chế độ di chuyển có thể được trả về.
languageCode

Ngôn ngữ để trả về kết quả.
- Xem danh sách ngôn ngữ được hỗ trợ . Google thường cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể không đầy đủ.
- Nếu bạn không cung cấp languageCode, API sẽ mặc định là en. Nếu bạn chỉ định một mã ngôn ngữ không hợp lệ, API sẽ trả về lỗi INVALID_ARGUMENT.
- API cố gắng cung cấp một đị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 sẽ trả về địa chỉ đường phố được chuyển tự sang một tập lệnh mà người dùng có thể đọc được nếu cần, tuân theo 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ả cá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 kết quả trùng khớp gần nhất.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp 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 khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như các từ viết tắt cho các loại đường phố hoặc các từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ ở ngôn ngữ khác.
regionCode

Mã khu vực dưới dạng giá trị mã CLDR gồm 2 ký tự. Không có giá trị mặc định. Hầu hết các mã CLDR đều giống với mã ISO 3166-1.
Khi mã hoá địa lý một địa chỉ, mã hoá địa lý chuyển tiếp, tham số này có thể ảnh hưởng nhưng không hạn chế hoàn toàn kết quả từ dịch vụ đến khu vực đã chỉ định. Khi mã hoá địa lý một vị trí hoặc một địa điểm, mã hoá địa lý ngược hoặc mã hoá địa lý địa điểm, bạn có thể sử dụng tham số này để định dạng địa chỉ. Trong mọi trường hợp, tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
placeFilter

Cho phép bạn lọc kết quả của locationQuery tìm kiếm để đáp ứng các yêu cầu của bạn, chẳng hạn như chỉ trả về các đích đến là tòa nhà hoặc chỉ trả về các đích đến có địa chỉ rõ ràng.

Lọc theo mức độ chi tiết cấu trúc

Bộ lọc structureType cho phép bạn chỉ định loại cấu trúc do truy vấn trả về:
- Tách biệt các toà nhà: Sử dụng "structureType": "BUILDING" để hiển thị đường viền của toà nhà trên bản đồ hoặc nhận thông tin chi tiết cho một cấu trúc cụ thể.
- Tìm hiểu về các khu phức hợp: Sử dụng "structureType": "GROUNDS" để đảm bảo kết quả chính là toàn bộ khu đất. Điều này hữu ích khi truy vấn các khu vực lớn hơn như khuôn viên trường đại học hoặc trung tâm mua sắm.
- Tập trung vào các đơn vị/phần: Sử dụng "structureType": "SECTION" để xác định các phần trong một toà nhà.
Đảm bảo địa chỉ hữu ích

Không phải tất cả các địa điểm đều có địa chỉ rõ ràng ở cấp đường phố. Bộ lọc addressability giúp bạn kiểm soát chất lượng địa chỉ trong kết quả:
- Yêu cầu địa chỉ chính rõ ràng: Để đảm bảo kết quả đích đến chính luôn có địa chỉ hoặc tên ở cấp đường phố, hãy sử dụng "addressability": "PRIMARY". Điều này hữu ích cho mục đích điều hướng hoặc hiển thị khi cần có địa chỉ rõ ràng
- Cho phép địa chỉ trong các đích đến phụ: Trong trường hợp địa điểm chính có thể không có địa chỉ, nhưng các đơn vị trong đó có (chẳng hạn như các căn hộ trong một toà nhà), "addressability": "WEAK" đảm bảo rằng ít nhất địa điểm chính hoặc một trong các đích đến phụ của địa điểm đó có địa chỉ.
- Bất kỳ kết quả nào: Nếu sự hiện diện của địa chỉ không liên quan đến trường hợp sử dụng của bạn, hãy sử dụng "addressability": "ANY".
Ví dụ: Lọc các toà nhà có địa chỉ
```
curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4/geocode/destinations
```

Tìm điểm đến Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Yêu cầu tìm kiếm đích đến

Tìm kiếm một đích đến theo địa chỉ

Tìm kiếm một đích đến theo mã địa điểm

Mã địa điểm được hỗ trợ

Sử dụng tính năng Tự động hoàn thành của Places API (Mới) với tính năng Tìm kiếm đích đến

Tìm kiếm một đích đến theo vị trí

Sử dụng OAuth để tạo yêu cầu

Phản hồi tìm kiếm đích đến

primary

containingPlaces

subDestinations

entrances

structureType

navigationPoints

arrivalSummary

landmarks

Định dạng của phản hồi

Thông số bắt buộc

FieldMask

Thông số tùy chọn

travelModes

languageCode

regionCode

placeFilter

Lọc theo mức độ chi tiết cấu trúc

Đảm bảo địa chỉ hữu ích