Tìm điểm đến

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

Destination là một địa điểm đáng chú ý 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à.

Điểm cuối SearchDestinations của Geocoding API 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 điểm đến

Yêu cầu tìm kiếm điểm đến là một yêu cầu HTTP POST đến một URL có dạng:

https://geocode.googleapis.com/v4alpha/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 đề như 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/v4alpha/geocode/destinations

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

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

Tìm kiếm điểm đế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:

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/v4alpha/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/v4alpha/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 ghi lại trong biểu mẫu HTML.

Tìm kiếm một điểm đế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ã đị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/v4alpha/geocode/destinations

Tìm kiếm điểm đến theo vị trí

Bạn có thể tìm kiếm một điểm đến bằng cách cung cấp toạ độ theo 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/v4alpha/geocode/destinations

Sử dụng OAuth để đưa ra 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 chỉ định phạm vi chính xác cho mã thông báo OAuth. Geocoding API hỗ trợ các phạm vi sau để sử dụng với điểm cuối Destinations:

  • https://www.googleapis.com/auth/maps-platform.geocode – Sử dụng với tất cả các điểm cuối của 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 điểm cuối của 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à một phạm vi chung cho phép truy cập vào tất cả các điểm cuối.

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

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

Bối cảnh siêu địa phương về vị trí

Phản hồi của Search Destinations cung cấp bối cảnh phong phú, siêu cục bộ về vị trí. Các trường chính bao gồm:

  • primary: Địa điểm chính được xác định bằng cụm từ tìm kiếm 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 (ví dụ: một trung tâm mua sắm có chứa một cửa hàng).
  • subDestinations: Vị trí cụ thể hơn trong điểm đến chính (ví dụ: căn hộ trong một toà nhà).
  • entrances: Điểm vào và điểm thoát cụ thể cho đích đến.
  • navigationPoints: Vị trí phù hợp gần đường để điều hướng đến điểm cuối.
  • arrivalSummary: Thông tin chi tiết dựa trên AI để hỗ trợ bạn đến nơi. Xem phần Bản tóm tắt dựa trên AI.
  • landmarks: Những địa điểm đáng chú ý ở gần đó giúp người dùng hiểu được môi trường xung quanh điểm đến.

Để 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.

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

SearchDestinations trả về một 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",
          "american_restaurant",
          "meal_takeaway",
          "restaurant",
          "food_store",
          "food",
          "point_of_interest",
          "store",
          "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/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "florist",
              "butcher_shop",
              "deli",
              "bakery",
              "food_delivery",
              "supermarket",
              "market",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 158.65607,
          "travelDistanceMeters": 131.16699
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "types": [
              "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":
 { ... } {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ]
            }

          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 87.34801,
          "travelDistanceMeters": 214.08084
        },
        {
          "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
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 61.182194,
          "travelDistanceMeters": 63.075645
        },
        {
          "place": {
            "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk",
            "displayName": {
              "text": "Madras Café",
              "languageCode": "en"
            },
            "primaryType": "indian_restaurant",
            "types": [
              "indian_restaurant",
              "coffee_shop",
              "cafe",
              "restaurant",
              "food_store",
              "food",
              "point_of_interest",
              "store",
              "establishment"
            ],
            "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1026",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1177 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743,
              "longitude": -122.0549333
            }
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "relationalDescription": {
            "text": "Near Madras Café",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 204.45102,
          "travelDistanceMeters": 235.12041
        }
      ]
,
      "entrances": [
        {
          "location": {
            "latitude": 37.373531299999996,
            "longitude": -122.05694519999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "UNKNOWN"
          ]
        }
      ]
    }
  ]
}

Thông số bắt buộc

  • Một trong 3 tham số sau đây phải có trong yêu cầu API, trong đó chỉ định địa chỉ, địa điểm hoặc vị trí để tìm kiếm một đích đến:
    • addressQuery – địa chỉ cần tìm.
    • place – mã địa điểm của địa điểm cần tìm.
    • locationQuery – toạ độ vĩ độ và kinh độ của vị trí cần tì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 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ề các 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/v4alpha/geocode/destinations

    Không có danh sách mặc định về 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 này sẽ trả về lỗi. Đặt mặt nạ trường thành * để trả về tất cả các trường. Hãy 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 những loại navigationPoints cần trả về. Các điểm điều hướng cho các phương thức di chuyển khác sẽ bị lọc bỏ. Nếu bạn không đặt travelModes, thì hệ thống có thể trả về các điểm điều hướng của tất cả phương tiện đi lại.

  • languageCode

    Ngôn ngữ mà bạn muốn dù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 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 này 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 đó, phương thức này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản 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 đều đượ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ề. Trình mã hoá địa lý diễn giải các từ viết tắt theo những 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.

  • 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 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 hoàn toàn hạn chế kết quả từ dịch vụ đối với khu vực đượ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ể 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 một cụm từ tìm kiếm locationQuery để đáp ứng các yêu cầu của bạn, chẳng hạn như chỉ trả về những đích đến là toà nhà hoặc chỉ trả về những đích đến có địa chỉ rõ ràng.

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

    Bộ lọc structureType cho phép bạn chỉ định loại cấu trúc mà truy vấn trả về:

    • Tách biệt các toà nhà: Sử dụng "structureType": "BUILDING" để hiện đường viền của toà nhà trên bản đồ hoặc xem thông tin chi tiết về 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ôn viên. Điều này hữu ích khi truy vấn các khu vực rộng 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 địa điểm nào cũng có địa chỉ rõ ràng ở cấp đường. Bộ lọc addressability giúp bạn kiểm soát chất lượng của đị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, 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 địa chỉ rõ ràng là yếu tố quan trọng.
    • Cho phép địa chỉ trong các vị trí phụ: Trong trường hợp vị trí chính có thể không có địa chỉ, nhưng các đơn vị trong vị trí đó thì 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 vị trí chính hoặc một trong các vị trí phụ của vị trí đó có địa chỉ.
    • Mọi kết quả: 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 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/v4alpha/geocode/destinations

Phản hồi

Đây là một điểm cuối thử nghiệm của Geocoding API. Chúng tôi rất mong nhận được ý kiến phản hồi tại địa chỉ geocoding-feedback-channel@google.com.