搜尋目的地

歐洲經濟區 (EEA) 開發人員

Destination 是指使用者想前往或導航至的特定位置或地點。Destination 也包含與位置或地點相關的資訊集合，例如導航點、地標、入口和建築物輪廓。

Geocoding API 的 SearchDestinations 方法可讓您根據不同的輸入條件 (例如地址、地點 ID 或經緯度座標)，擷取各種目的地的詳細資訊。

搜尋目的地要求

搜尋目的地要求是 HTTP POST 要求，網址格式如下：

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

在 JSON 要求內文或標頭中，傳遞所有參數做為 POST 要求的一部分。例如：

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

您可以透過下列 3 種方式指定搜尋目的地的位置：

  • 地址
  • 地點 ID
  • 經緯度座標

依地址搜尋目的地

您可以將地址指定為非結構化字串。地址地理編碼不會解析經緯度座標，或其他不代表地址的非結構化字串。系統不支援使用這類字串的要求，可能會導致錯誤回應或未指定的行為。不支援的查詢範例如下：

查詢類型 範例
經緯度座標。請改用位置查詢。 "37.422131,-122.084801"
概念或限制過多，例如單一查詢中包含多個地點、道路或城市名稱 「Market Street San Francisco San Jose Airport」
Google 地圖未顯示郵政地址元素 "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
商家、連鎖店或類別的名稱，加上這些實體未提供的地點 「德州達拉斯附近的 Tesco」
有多種解讀方式的模稜兩可查詢 「充電器交寄」
不再使用的歷史名稱 "Middlesex United Kingdom"
非地理空間元素或意圖 「文圖拉港有多少艘船？」
非官方或自訂名稱 「疊疊樂」
「螺旋滑梯」
大型政治實體 (城市、州/省、國家/地區) "New York City"
"California"
"USA"
沒有特定地址的路線 「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

或 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

處理 HTML 表單中擷取的地址元件時，通常會使用 postalAddress 格式。

依地點 ID 搜尋目的地

您可以提供地點 ID 來擷取目的地：

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

支援的地點 ID

「搜尋目的地」方法最適合用來代表特定可導航目的地的地點 ID。一般支援 establishment、point_of_interest、premise、street_address 和 subpremise 等類型的地點 ID。不支援不代表特定位置的地點 ID，例如從地址範圍推斷出的地點 ID (例如「10-20 Main St」)、沒有特定編號的路段，或 Plus Code。如果結果的區域過大 (例如「太平洋」)，系統也不支援這類結果的地點 ID。

搭配使用 Autocomplete (新版) 和 Search Destinations

為確保相容性，請使用 Autocomplete (新版) 尋找地點 ID，以便搭配搜尋目的地使用。使用 Autocomplete (新版) 時，應使用 includedPrimaryTypes 參數依類型篩選結果。使用下列建議篩選器，透過 Autocomplete (新版) 傳回的地點 ID 支援搜尋目的地：

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

此外，請勿在 Autocomplete (新版) 要求中，將 include_pure_service_area_businesses 標記設為 true。

依地點搜尋目的地

你可以提供經緯度座標來搜尋目的地：

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

使用 OAuth 提出要求

Geocoding API v4 支援 OAuth 2.0 驗證。如要搭配使用 OAuth 和 Geocoding API，必須為 OAuth 權杖指派正確的範圍。Geocoding API 支援下列範圍，可搭配 Destinations 方法使用：

  • https://www.googleapis.com/auth/maps-platform.geocode — 搭配所有 Geocoding API 方法使用。

此外，您也可以將一般 https://www.googleapis.com/auth/cloud-platform 範圍用於所有 Geocoding API 方法。這個範圍在開發期間很有用，但不適用於正式環境，因為這是可存取所有方法的通用範圍。

如需更多資訊和範例，請參閱「使用 OAuth」。

搜尋目的地回應

「搜尋目的地」回應會提供豐富的超區域性地點脈絡。

「搜尋目的地」回應中的 PlaceView 物件 (例如 primary、containingPlaces 中的項目和 landmarks) 會使用欄位來指出地點類型：

  • types：字串陣列，指出地點類型。
  • primaryType：表示地點主要類型的字串。

types 和 primaryType 的可能字串值來自 Place Types (新版) 頁面的表 A 和表 B。

本節說明重要的回應欄位。如要進一步瞭解所有回應欄位，請參閱 API 參考資料。

primary

要求中查詢識別的主要地點。

addressComponents

這個陣列包含這個地址適用的各種元件。

每個地址元件通常會包含下列欄位：

  • types[] 是一個陣列，用來指出地址元件的類型。請參閱支援類型清單。
  • longText 是地理編碼器所傳回地址元件的完整文字說明或名稱。
  • shortText 是地址元件的縮寫文字名稱 (如有)。舉例來說，阿拉斯加州地址元件的 longText 可能為「Alaska」，而 shortText 則為 2 個字母的郵政簡碼「AK」。
  • languageCode 是用來格式化這個元件的語言，採用 CLDR 標記。

containingPlaces

主要目的地所屬的較大實體 (例如包含商店的購物中心)。

subDestinations

主要目的地內的更具體地點 (例如大樓內的公寓)。

entrances

entrances[] 陣列中的物件包含下列欄位：

  • location

    一組經緯度座標，定義地點的出入口位置。

  • entrance_tags[]

    描述入口特徵的入口標記陣列。支援的值如下：

    • "PREFERRED"

    表示這個入口可能提供返回地點的實體通道。一個地點可以有多個偏好入口。如果入口沒有這個標記，表示入口位於同一棟建築物內，但不一定能通往該地點。

    舉例來說，如果傳回的地點是帶狀商場中的餐廳，則 "PREFERRED" 入口會是通往餐廳本身的入口，而其他傳回的入口則是建築物的其他入口，例如帶狀商場中其他餐廳的入口。

    如果傳回的地點是建築物本身，"PREFERRED" 入口會是通往建築物「主要」部分的入口。舉例來說，在購物中心，"PREFERRED" 入口是通往主要門廳區域的入口，但如果入口只能通往建築物側邊的商店，則不屬於 "PREFERRED" 入口。

  • streetViewThumbnail和streetViewAnnotation

    街景服務 Static API 的參數，可讓您顯示這些地點的相關圖像。進一步瞭解這些欄位。

structureType

這個地點代表的建築物類型。

  • POINT

    點位置。

  • SECTION

    建築物的子區段。

  • BUILDING

    建築物。

  • GROUNDS

    通常包含多棟建築物的大型區域，例如大學校園、公寓大樓或購物中心。

地理編碼回應中的 navigationPoints 欄位包含點清單，可用於導覽至該地點。具體來說，在道路網路中規劃往返該地點的路線時，應將這些點做為起點或終點。

每個導航點都包含下列值：

  • navigationPointToken 是包含 navigationPoints 欄位中比對內容資訊的權杖。您可以將這個權杖傳送至路線規劃和導航 API，改善應用程式中的路線規劃和河流體驗。詳情請參閱「使用導航點權杖規劃路線」。
  • location 包含導航點的經緯度值。這個位置一律會非常靠近道路網路，是導航前往或離開某個地點的理想停靠或起點。該點刻意稍微偏離道路中心線，清楚標示地點所在的道路側。
  • travelModes 是導覽點可使用的交通方式清單：
    • "DRIVE" 是對應行車路線的交通方式。
    • "WALK" 是步行路線對應的交通方式。
  • usages 是導覽點支援的用途清單。使用方式如下：
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

如為接送地點，請使用交通方式為 DRIVE 且用途為 PICKUP 或 DROPOFF 的導航點。如果無法使用上車或下車地點，請使用頂端的行車導航點。

  • altitude_meters 包含導航點的海拔高度 (以公尺為單位)，相對於 WGS-84 橢球體。如果路段垂直堆疊，請使用 altitude_meters 欄位，讓系統選擇最適合導航的路段。

landmarks

附近地點，協助使用者瞭解目的地周遭環境。

arrivalSummary

AI 輔助洞察資料，協助你抵達目的地。請參閱「AI 輔助摘要」。

parkingOptions

詳細停車資訊。

回覆格式

SearchDestinations 會傳回下列 JSON 格式的 SearchDestinationsResponse：

{
  "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"
          ]
        }
      ]
    }
  ]
}

必要參數

  • API 要求中必須包含下列 3 個參數之一，指定要搜尋目的地的地址、地點或位置：
    • addressQuery：要搜尋的地址。
    • place：要搜尋的地點 ID。
    • locationQuery：要搜尋的地點經緯度座標。

  • FieldMask

    建立回應欄位遮罩，指定要在回應中傳回的欄位清單。使用網址參數 $fields 或 fields，或使用 HTTP 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。舉例來說，以下要求只會傳回主要目的地的入口、導覽點和地點 ID。

      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

    回應中沒有預設的傳回欄位清單。如果省略欄位遮罩，方法會傳回錯誤。將欄位遮罩設為 *，即可傳回所有欄位。詳情請參閱「選擇要傳回的欄位」。

選用參數

  • travelModes

    指定要傳回的 navigationPoints 類型。系統會篩除其他交通方式的導航點。如果未設定 travelModes，系統會傳回所有交通方式的導航點。

  • languageCode

    傳回結果時使用的語言。

    • 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
    • 如未提供 languageCode，API 預設會使用該地點的當地語言和文字。如果指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
    • API 會盡可能提供使用者和當地人都能看懂的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要按照偏好語言，將地址音譯為使用者可閱讀的文字。所有其他地址都會以偏好語言傳回。傳回的所有地址元件都會採用相同語言，也就是第一個元件所選的語言。
    • 如果偏好語言沒有名稱，API 會使用最接近的名稱。
    • 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言，以不同方式解讀縮寫，例如街道類型的縮寫，或可能在某種語言中有效，但在另一種語言中無效的同義詞。

  • regionCode

    區域代碼，為 雙字元 CLDR 代碼值。沒有預設值。大多數 CLDR 代碼與 ISO 3166-1 代碼相同。

    對地址進行地理編碼 (正向地理編碼) 時，這個參數會影響服務傳回的結果，但不會完全限制結果只來自指定區域。進行地點或地點的反向地理編碼或地點地理編碼時，這個參數可用於設定地址格式。在所有情況下，這項參數都可能根據適用法律影響結果。

  • placeFilter

    可讓您篩選 locationQuery 搜尋結果，以符合您的需求，例如只傳回建築物目的地，或只傳回有明確地址的目的地。

    依結構精細程度篩選

    structureType 篩選器可讓您指定查詢傳回的結構類型：

    • 隔離建築物：使用 "structureType": "BUILDING" 在地圖上顯示建築物輪廓，或取得特定建築物的詳細資料。
    • 瞭解複合物：使用 "structureType": "GROUNDS" 確保主要結果是整體地面。查詢大學校園或購物中心等較大區域時，這項功能就相當實用。
    • 著重於單位/部分：使用 "structureType": "SECTION" 識別建築物內的部分。

    確保地址實用

    並非所有地點都有明確的街道地址。addressability 篩選器可協助您控管結果中的地址品質：

    • 要求提供清楚的主要地址：為確保主要目的地結果一律包含街道層級的地址或名稱，請使用 "addressability": "PRIMARY"。這項功能適用於導覽或顯示用途，因為清楚的地址至關重要。
    • 允許子目的地中的地址：如果主要地點可能沒有地址，但其中的單位有地址 (例如建築物中的公寓)，"addressability": "WEAK" 可確保至少主要地點或其中一個子目的地有地址。
    • 任何結果：如果地址存在與否與您的用途無關，請使用 "addressability": "ANY"。如果只需要幾何屬性 (例如建築物外框和導航點)，強烈建議使用這項功能，因為這樣可提高這些結果的準確度。
    範例：篩選可定址建築物 
    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