Method: resolveNames

將地點名稱 (或地址) 清單解析為 Google 地圖上的特定地理空間實體 (例如地點)。

HTTP 要求

POST https://mapstools.googleapis.com/v1alpha:resolveNames

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體會包含結構如下的資料：

JSON 表示法 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
欄位
queries[]

object (LocationQuery)

必填。待解決的營業地點查詢清單。最多可指定 20 個查詢。
locationBias

object (LocationBias)

(選用步驟) 可選區域，用於調整解析結果。如果指定了這個區域，解析結果會偏向較接近這個區域的實體。加入 locationBias 或 regionCode 通常能縮小搜尋範圍，提供更符合需求的結果。

如果同時指定 locationBias 和 regionCode，系統會優先採用 locationBias。regionCode
regionCode

string

(選用步驟) 選用區域代碼，可讓解析結果偏向特定區域。如果指定區域，解析結果會偏向指定區域內或附近的實體。這應該是 CLDR 區域代碼。例如「US」或「CA」。加入 locationBias 或 regionCode 通常能縮小搜尋範圍，提供更符合需求的結果。

如果同時指定 locationBias 和 regionCode，系統會優先採用 locationBias。regionCode

回應主體

v1alpha.resolveNames 的回應訊息。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
欄位
results[]

object (Result)

僅供輸出。位置查詢中已解析的實體清單。保證與要求 queries 索引 1:1 對應。索引 i 的空字串表示該查詢的解析失敗。如果解析失敗，請檢查 failedRequests 欄位的錯誤狀態。
failedRequests

map (key: integer, value: object (Status))

僅供輸出。地圖會傳達部分失敗情形。這個鍵是 queries 欄位中失敗要求的索引。這個值是錯誤狀態，詳細說明解析失敗的原因。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/maps-platform.mapstools
  • https://www.googleapis.com/auth/cloud-platform.read-only

LocationQuery

地點查詢代表可透過 Google 地圖解析的特定地點實體。目前僅支援地點名稱和地址做為地點查詢。

JSON 表示法 
{
  "text": string
}
欄位
text

string

必填。要解析為 Google 地圖上特定地理空間實體的文字查詢，例如地點或地址。查詢越具體，解決方式就越準確。例如「舊金山」、「Googleplex, Mountain View, CA」、「1600 Amphitheatre Parkway, Mountain View, CA」或「巴黎鐵塔, Paris」。查詢內容必須是特定地址或地名。不支援一般地點，例如連鎖店名稱 (如「星巴克」) 或搜尋查詢 (如「餐廳」)。

LocationBias

要將解析度結果偏向的區域。

JSON 表示法 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
欄位
聯集欄位 type。位置偏誤的類型。type 只能是下列其中一項：
viewport

object (Viewport)

由定界框定義的可視區域。

可視區域

經緯度可視區域，以兩個對角相反的 low 和 high 點表示。可視區域視為封閉區域，也就是說，可視區域包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍必須介於 -180 到 180 度之間 (含首尾)。這類情況包括：

  • 如果 low = high，可視區域就是該單一點。

  • 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區域會跨越 180 度的經度線)。

  • 如果 low.longitude = -180 度且 high.longitude = 180 度，可視區域會包含所有經度。

  • 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會空白。

  • 如果 low.latitude > high.latitude，緯度範圍會空白。

low 和 high 都必須填入，且代表的方塊不得為空 (如上述定義所指定)。如果檢視區塊為空白，就會發生錯誤。

舉例來說，這個檢視區塊完全涵蓋紐約市：

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

JSON 表示法 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
欄位
low

object (LatLng)

必填。可視區域的最低點。
high

object (LatLng)

必填。可視區域的最高點。

LatLng

代表經緯度組合的物件。這個物件會同時指出經度和緯度的度數。除非另有指定，否則這個物件必須符合 WGS84 標準。此外，值必須在正規化範圍內。

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數，必須介於 [-90.0, +90.0] 的範圍之間。
longitude

number

經度度數，必須介於 [-180.0, +180.0] 的範圍之間。

結果

從指定位置查詢中解析出的單一實體，以及解析的信賴水準。

JSON 表示法 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
欄位
entity

object (Entity)

僅供輸出。位置查詢中已解析的實體。
confidence

enum (Confidence)

僅供輸出。解決方案的信賴水準。

可信度

解決方案的信賴水準。

列舉
CONFIDENCE_UNSPECIFIED 預設值。這個值不會使用。
MEDIUM 中等信賴度表示解析結果可能正確，但可能還有其他候選項目。
HIGH 高信賴度表示解析結果正確，且代表特定地理空間實體 (例如特定地點)。