Search - Post Search Address Batch

參考

服務:: Maps

API 版本:: 1.0

使用將查詢批次傳送至單一異步要求中的搜尋位址 API。
Post Search Address Batch API 是 HTTP POST 要求，可將查詢批次傳送至單一同步 API 呼叫中的搜尋位址 API。您可以呼叫搜尋 Address Batch API，以異步方式執行異步 (異步) 或同步 (同步處理) 。異步 API 可讓呼叫端批處理最多 10,000 個查詢，並將 API 同步處理至 100 個查詢。

提交同步批次要求

建議針對輕量型批次要求使用同步 API。當服務收到要求時，它會在計算批次專案后立即回應，而且稍後將無法擷取結果。如果要求花費超過 60 秒，同步 API 會傳回逾時錯誤 (408 回應) 。此 API 的批次項目數目限制為 100 。

POST https://atlas.microsoft.com/search/address/batch/sync/json?api-version=1.0&subscription-key={subscription-key}

提交異步批次要求

異步 API 適用於處理大量相對複雜的搜尋要求

它允許在不同的呼叫中擷取結果， (多個下載可能會) 。
異步 API 已針對可靠性進行優化，而且預期不會發生逾時。
此 API 的批次項目數目限制為 10,000 。

當您使用異步要求提出要求時，服務預設會傳回 202 回應碼，並在響應標頭的 [位置] 字段中傳回重新導向 URL。應該定期檢查此 URL，直到響應資料或錯誤資訊可用為止。異步回應會儲存 14 天。如果在到期期間之後使用，重新導向 URL 會傳回 404 回應。

請注意，異步批次要求是長時間執行的作業。以下是一般作業順序：

用戶端會將搜尋位址批次POST要求傳送至 Azure 地圖服務。

POST https://atlas.microsoft.com/search/address/batch/json?api-version=1.0&subscription-key={subscription-key}

伺服器會以下欄其中一項回應：

HTTP 202 Accepted - 已接受批次要求。

HTTP Error - 處理 Batch 要求時發生錯誤。 400 Bad Request這可能是或其他Error任何狀態代碼。
如果成功接受批次要求， Location 回應中的標頭會包含 URL 以下載批次要求的結果。此狀態 URI 如下所示：

    GET https://atlas.microsoft.com/search/address/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

用戶端會在步驟 3 取得的下載 URL 上發出GET要求，以下載批次結果。

批次要求的 POST 本文

若要傳送 搜尋地址 查詢，您將使用 POST 要求本文將包含 batchItems 格式的陣列 json ，且 Content-Type 標頭會設定為 application/json。以下是包含 5 個 搜尋地址 查詢的範例要求本文：

{
    "batchItems": [
        {"query": "?query=400 Broad St, Seattle, WA 98109&limit=3"},
        {"query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"},
        {"query": "?query=350 5th Ave, New York, NY 10118&limit=1"},
        {"query": "?query=Pike Pl, Seattle, WA 98101&lat=47.610970&lon=-122.342469&radius=1000"},
        {"query": "?query=Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France&limit=1"}
    ]
}

批次中的 搜尋地址 查詢只是沒有通訊協定、基底 URL、路徑、api-version 和 subscription-key 的部分 URL。它可以接受任何支援的 搜尋位址URI 參數。 搜尋地址查詢中的字串值必須正確逸出， (例如“ 字元應該以 \ ) 逸出，而且也應該正確編碼 URL。

異步 API 可讓呼叫端批處理最多 10,000 個查詢，並將 API 同步處理至 100 個查詢，且批次至少應包含 1 個查詢。

下載異步批次結果

若要下載異步批次結果，您將向批次下載端點發出 GET 要求。您可以從成功POST批次要求的標頭取得Location此下載 URL，如下所示：

https://atlas.microsoft.com/search/address/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

以下是下載批次結果的典型作業順序：

用戶端會使用下載 URL 傳送GET要求。
伺服器會以下欄其中一項回應：

HTTP 202 Accepted - 已接受批次要求，但仍正在處理。請稍後再試一次。

HTTP 200 OK - 已成功處理批次要求。回應本文包含所有批次結果。

批次回應模型

傳回的數據內容類似於異步和同步處理要求。下載異步批次要求的結果時，如果批次已完成處理，回應本文就會包含批次回應。此批次回應包含一個 summary 元件，指出 totalRequests 屬於原始批次要求的一部分， successfulRequests亦即已成功執行的查詢。批次回應也包含 batchItems 數位，其中包含批次要求中每個查詢的回應。 batchItems將會以與批次要求中傳送原始查詢完全相同的順序來包含結果。中的每個 batchItems 專案都包含 statusCode 和 response 欄位。中的每個 responsebatchItems 是下列其中一種類型：

SearchAddressResult - 如果查詢順利完成。
Error - 如果查詢失敗。在這裡案例中，回應會包含 code 和 message 。

以下是 2 個成功 且 1 個失敗 結果的批次回應範例：

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "one microsoft way redmond wa 98052"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.63989,
                            "lon": -122.12509
                        }
                    }
                ]
            }
        },
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "pike pl seattle wa 98101"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.60963,
                            "lon": -122.34215
                        }
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

POST https://atlas.microsoft.com/search/address/batch/json?api-version=1.0

URI 參數

名稱	位於	必要	類型	Description
format	path	True	JsonFormat	所需的回應格式。僅支援 `json` 格式。
api-version	query	True	string	Azure 地圖服務 API 的版本號碼。

要求標頭

名稱	必要	類型	Description
x-ms-client-id		string	指定哪個帳戶與 Microsoft Entra ID 安全性模型搭配使用。它代表 Azure 地圖服務帳戶的唯一標識符，而且可以從 Azure 地圖服務管理平面帳戶 API 擷取。若要在 Azure 地圖服務中使用 Microsoft Entra ID 安全性，請參閱下列文章以取得指引。

要求本文

名稱	類型	Description
batchItems	BatchRequestItem[]	要處理的查詢清單。

回應

名稱	類型	Description
200 OK	SearchAddressBatchProcessResult	確定
202 Accepted		僅支援異步要求。已接受要求：要求已接受進行處理。請使用位置標頭中的 URL 來重試或存取結果。標題 Location: string
Other Status Codes	ErrorResponse	發生意外錯誤。

名稱

類型

Description

200 OK

SearchAddressBatchProcessResult

確定

202 Accepted

僅支援異步要求。 已接受要求：要求已接受進行處理。請使用位置標頭中的 URL 來重試或存取結果。

標題

Location: string

Other Status Codes

ErrorResponse

發生意外錯誤。

安全性

AADToken

這些是 Microsoft Entra OAuth 2.0 流程。與 Azure 角色型存取控制配對時，可用來控制對 Azure 地圖服務 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務資源帳戶或子資源的存取權。任何使用者、群組或服務主體都可以透過內建角色或由一或多個許可權組成的自定義角色來授與存取權，以 Azure 地圖服務 REST API。

若要實作案例，建議您檢視驗證概念。總而言之，此安全性定義會透過能夠針對特定 API 和範圍進行訪問控制的物件，提供將應用程式模型化 () 的解決方案。

注意

此安全性定義需要使用x-ms-client-id 標頭來指出應用程式要求存取權 Azure 地圖服務資源。這可以從地圖管理 API 取得。
Authorization URL專屬於 Azure 公用雲端實例。主權雲端具有唯一的授權 URL 和 Microsoft Entra ID 設定。
Azure 角色型訪問控制是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API 從 Azure 管理平面設定。
Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式設定。
如需 Microsoft 身分識別平台的詳細資訊，請參閱 Microsoft 身分識別平台概觀。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

這是在 Azure 入口網站或使用PowerShell、CLI、Azure SDK 或 REST API 中建立 Azure 地圖服務帳戶時所佈建的共用密鑰。

使用此金鑰，任何應用程式都可以存取所有 REST API。換句話說，此金鑰可作為發行所在帳戶中的主要金鑰。

對於公開的應用程式，我們建議使用機密用戶端應用程式方法來存取 Azure 地圖服務 REST API，以便安全地儲存您的密鑰。

類型: apiKey
位於: query

SAS Token

這是透過 azure 管理平面透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 地圖服務資源上的列出 SAS 作業建立的共用存取簽章令牌。

使用此令牌時，任何應用程式都有權使用 Azure 角色型訪問控制進行存取，並更精細地控制到期、速率和區域 (特定令牌的使用) 。換句話說，SAS 令牌可用來允許應用程式以比共用密鑰更安全的方式來控制存取。

對於公開的應用程式，我們建議在地圖帳戶資源上設定允許的來源特定清單，以限制轉譯濫用，並定期更新 SAS 令牌。

類型: apiKey
位於: header

範例

An Address Geocoding Batch API call containing 5 Address Geocoding API queries

範例要求

HTTP

POST https://atlas.microsoft.com/search/address/batch/json?api-version=1.0

{
  "batchItems": [
    {
      "query": "?query=400 Broad St, Seattle, WA 98109&limit=3"
    },
    {
      "query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"
    },
    {
      "query": "?query=350 5th Ave, New York, NY 10118&limit=1"
    }
  ]
}

範例回覆

狀態碼:: 200

{
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 3
  },
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "400 broad st seattle wa 98109",
          "queryType": "NON_NEAR",
          "queryTime": 127,
          "numResults": 3,
          "offset": 0,
          "totalResults": 9,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/20843845",
            "score": 11.966,
            "address": {
              "streetNumber": "400",
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union, Lower Queen Anne",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "400 Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62039,
              "lon": -122.34928
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.62129,
                "lon": -122.35061
              },
              "btmRightPoint": {
                "lat": 47.61949,
                "lon": -122.34795
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 47.61982,
                  "lon": -122.34886
                }
              }
            ]
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388442",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "extendedPostalCode": "981094612",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62001,
              "lon": -122.34843
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61965,
                "lon": -122.34761
              },
              "btmRightPoint": {
                "lat": 47.62066,
                "lon": -122.349
              }
            }
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388680",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, Belltown",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109,98121",
              "extendedPostalCode": "981094991,981211117,981211237,981213206",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.61691,
              "lon": -122.35251
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61502,
                "lon": -122.35041
              },
              "btmRightPoint": {
                "lat": 47.61857,
                "lon": -122.35484
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "one microsoft way redmond wa 98052",
          "queryType": "NON_NEAR",
          "queryTime": 169,
          "numResults": 2,
          "offset": 0,
          "totalResults": 3292,
          "fuzzyLevel": 2
        },
        "results": [
          {
            "type": "Street",
            "id": "US/STR/p0/1692663",
            "score": 10.225,
            "address": {
              "streetName": "Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "extendedPostalCode": "980526399,980528300",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63989,
              "lon": -122.12509
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.63748,
                "lon": -122.12309
              },
              "btmRightPoint": {
                "lat": 47.64223,
                "lon": -122.13061
              }
            }
          },
          {
            "type": "Cross Street",
            "id": "US/XSTR/p1/4779971",
            "score": 8.506,
            "address": {
              "streetName": "Microsoft Way & 157th Avenue Northeast, Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way & 157th Avenue Northeast, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63962,
              "lon": -122.13061
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.64052,
                "lon": -122.13194
              },
              "btmRightPoint": {
                "lat": 47.63872,
                "lon": -122.12928
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "350 5th ave new york ny 10118",
          "queryType": "NON_NEAR",
          "queryTime": 233,
          "numResults": 1,
          "offset": 0,
          "totalResults": 8032,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/48052000",
            "score": 14.334,
            "address": {
              "streetNumber": "350",
              "streetName": "5th Avenue",
              "municipalitySubdivision": "New York, Midtown South",
              "municipality": "New York, Manhattan",
              "countrySecondarySubdivision": "New York",
              "countryTertiarySubdivision": "Manhattan",
              "countrySubdivisionCode": "NY",
              "postalCode": "10118",
              "extendedPostalCode": "1011800",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "350 5th Avenue, NYC, NY 10118",
              "countrySubdivisionName": "New York"
            },
            "position": {
              "lat": 40.74817,
              "lon": -73.985
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 40.74907,
                "lon": -73.98619
              },
              "btmRightPoint": {
                "lat": 40.74727,
                "lon": -73.98381
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 40.74808,
                  "lon": -73.98482
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

狀態碼:: 202

Operation-Location: URL to download the results of the long-running batch request.

定義

名稱	Description
Address	結果的位址
AddressRanges	描述街道兩邊的位址範圍，以取得搜尋結果。包含位址範圍的開始和結束位置座標。
BatchRequest	此類型代表 Batch 服務的要求本文。
BatchRequestItem	Batch 要求物件
BoundingBox	檢視區，涵蓋檢視區左上角和右下角座標所代表的結果。
BoundingBoxCompassNotation	位置的周框方塊。
Brand	與 POI 相關聯的品牌
Classification	所傳回POI的分類
ClassificationName	分類的名稱
DataSources	選擇性章節。與 Get 搜尋 Polygon API 搭配使用的參考標識碼。
Entity	周框方塊的實體類型來源。針對反向地理編碼，這一律等於位置。
EntryPoint	要傳回之 POI 的進入點。
EntryPointType	進入點的類型。值可以是主要或次要。
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
GeographicEntityType	Geography 實體類型。只有在要求 entityType 且可供使用時才存在。
Geometry	結果幾何圖形的相關信息。只有在類型 == Geography 時才存在。
JsonFormat	所需的回應格式。僅支援 `json` 格式。
LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。
MatchType	反向位址搜尋作業的相符類型。
OperatingHours	POI (景點) 的上班時間。
OperatingHoursTime	表示日期和時間
OperatingHoursTimeRange	一天的開啟時間範圍
PointOfInterest	傳回 POI 的詳細數據，包括名稱、電話、URL 位址和分類等資訊。
PointOfInterestCategorySet	POI 類別
QueryType	要傳回的查詢類型：NEARBY 或 NON_NEAR。
Response	查詢的結果。如果查詢順利完成，則 SearchAddressResult，否則為 ErrorResponse。
SearchAddressBatchItem	從搜尋 Address Batch 服務呼叫傳回的專案。
SearchAddressBatchProcessResult	此物件會從成功搜尋 Address Batch 服務呼叫傳回。
SearchAddressResultItem	搜尋 API 回應的結果物件。
SearchAddressResultType	值為下列其中之一： POI 街道 [地理位置] 點地址位址範圍交叉路口
SearchSummary	搜尋 API 回應的 Summary 物件。
Summary	批次要求的結果摘要

Address

結果的位址

名稱	類型	Description
boundingBox	BoundingBoxCompassNotation	位置的周框方塊。
buildingNumber	string	街上的建築物編號。已淘汰，請改用 streetNumber。
country	string	國家/地區名稱
countryCode	string	國家/地區 (注意：這是兩個字母的代碼，而不是國家/地區名稱。)
countryCodeISO3	string	ISO Alpha-3 國家/地區代碼
countrySecondarySubdivision	string	郡/縣
countrySubdivision	string	省/市
countrySubdivisionCode	string	`countrySubdivisionCode` 前面加上 `countryCode` ( countryCode-countrySubdivisionCode ) ，而連字元會形成 ISO 3166-2 程序代碼。範例：TX for Texas、SCT for Texas 和 ON for On for Ontario。
countrySubdivisionName	string	國家/地區系統管理階層的第一層完整名稱。只有在 countrySubdivision 以縮寫形式呈現時，才會顯示此字段。僅支援美國、加拿大和英國。
countryTertiarySubdivision	string	具名區域
crossStreet	string	要交叉的街道名稱。
extendedPostalCode	string	延伸郵遞區編碼 (可用性取決於區域) 。
freeformAddress	string	根據結果的國家/地區/地區格式規則格式化的位址行，或在國家/地區的情況下，其完整國家/地區名稱。
localName	string	位址元件，代表將多個可尋址物件分組以進行尋址用途的地理區域或位置名稱，而不做為管理單位。此欄位是用來建置 `freeformAddress` 屬性。 `localName` 代表郵遞。視位置而定， `localName` 是城市或鎮的已知名稱。對於城市或城市常用的名稱，請使用 `localName` ，而不是 `municipality`。
municipality	string	城市/城市/鎮注意： `municipality` 代表居民。視位置而定， `municipality` 值可能與城市或鎮的常見已知名稱不同。對於城市或城市常用的名稱，建議 `localName` 使用值，而不是 `municipality` 值。
municipalitySubdivision	string	子/超級城市
neighbourhood	string	一個街道是城市或城市內的地理當地語系化區域，具有獨特特性，以及各地方之間的社交互動。
postalCode	string	郵遞區區編碼/郵遞區號
routeNumbers	string[]	用來明確識別街道的代碼
street	string	街地名。已淘汰，請改用 streetName。
streetName	string	街地名。
streetNameAndNumber	string	街地名和數位。
streetNumber	string	街上的建築物編號。

AddressRanges

描述街道兩邊的位址範圍，以取得搜尋結果。包含位址範圍的開始和結束位置座標。

名稱	類型	Description
from	LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。
rangeLeft	string	街道左側的位址範圍。
rangeRight	string	街道右側的位址範圍。
to	LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。

BatchRequest

此類型代表 Batch 服務的要求本文。

名稱	類型	Description
batchItems	BatchRequestItem[]	要處理的查詢清單。

BatchRequestItem

Batch 要求物件

名稱	類型	Description
query	string	此參數包含用來執行非結構化地理編碼作業的查詢字串。查詢字串將會逐字傳遞至搜尋 API 進行處理。

BoundingBox

檢視區，涵蓋檢視區左上角和右下角座標所代表的結果。

名稱	類型	Description
btmRightPoint	LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。
topLeftPoint	LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。

BoundingBoxCompassNotation

位置的周框方塊。

名稱	類型	Description
entity	Entity	周框方塊的實體類型來源。針對反向地理編碼，這一律等於位置。
northEast	string	以逗號分隔浮點數作為周框方塊的北東部緯度、經度座標
southWest	string	周框方塊的南西部緯度、經度座標，以逗號分隔的浮點數

Brand

與 POI 相關聯的品牌

名稱	類型	Description
name	string	品牌的名稱

Classification

所傳回POI的分類

名稱	類型	Description
code	string	Code 屬性
names	ClassificationName[]	名稱陣列

ClassificationName

分類的名稱

名稱	類型	Description
name	string	Name 屬性
nameLocale	string	Name Locale 屬性

DataSources

選擇性章節。與 Get 搜尋 Polygon API 搭配使用的參考標識碼。

名稱	類型	Description
geometry	Geometry	結果幾何圖形的相關信息。只有在類型 == Geography 時才存在。

Entity

周框方塊的實體類型來源。針對反向地理編碼，這一律等於位置。

名稱	類型	Description
position	string	位置實體

EntryPoint

要傳回之 POI 的進入點。

名稱	類型	Description
position	LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。
type	EntryPointType	進入點的類型。值可以是主要或次要。

EntryPointType

進入點的類型。值可以是主要或次要。

名稱	類型	Description
main	string
minor	string

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細資料。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	錯誤物件。

GeographicEntityType

Geography 實體類型。只有在要求 entityType 且可供使用時才存在。

名稱	類型	Description
Country	string	國家/地區名稱
CountrySecondarySubdivision	string	郡/縣
CountrySubdivision	string	省/市
CountryTertiarySubdivision	string	具名區域
Municipality	string	城市/城市/鎮
MunicipalitySubdivision	string	子/超級城市
Neighbourhood	string	附近
PostalCodeArea	string	郵遞區區編碼/郵遞區號

Geometry

結果幾何圖形的相關信息。只有在類型 == Geography 時才存在。

名稱	類型	Description
id	string	將此當做 geometryId 傳遞至 Get 搜尋 Polygon API，以擷取此結果的幾何資訊。

JsonFormat

所需的回應格式。僅支援 json 格式。

名稱	類型	Description
json	string	JavaScript 物件表示法數據交換格式

LatLongPairAbbreviated

以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。

名稱	類型	Description
lat	number	Latitude 屬性
lon	number	經度屬性

MatchType

反向位址搜尋作業的相符類型。

名稱	類型	Description
AddressPoint	string
HouseNumberRange	string
Street	string

OperatingHours

POI (景點) 的上班時間。

名稱	類型	Description
mode	string	要求中使用的值：none 或 “nextSevenDays”
timeRanges	OperatingHoursTimeRange[]	接下來 7 天的時間範圍清單

OperatingHoursTime

表示日期和時間

名稱	類型	Description
date	string	代表 POI 時區中的目前行事曆日期，例如 “2019-02-07”。
hour	integer	小時以 POI 當地時間的 24 小時格式表示;可能的值為 0 - 23。
minute	integer	分鐘是在 POI 的當地時間;可能的值為 0 - 59。

OperatingHoursTimeRange

一天的開啟時間範圍

名稱	類型	Description
endTime	OperatingHoursTime	當指定的 POI 關閉時，接下來 7 天範圍內的點，如果範圍在範圍之前關閉，則為該範圍的開頭。
startTime	OperatingHoursTime	當指定 POI 開啟時，接下來 7 天範圍內的點，如果範圍在範圍之前開啟，則為該範圍的開頭。

PointOfInterest

傳回 POI 的詳細數據，包括名稱、電話、URL 位址和分類等資訊。

名稱	類型	Description
brands	Brand[]	品牌陣列。要傳回之 POI 的品牌名稱。
categories	string[]	類別陣列
categorySet	PointOfInterestCategorySet[]	最特定 POI 類別的清單
classifications	Classification[]	分類陣列
name	string	POI 屬性的名稱
openingHours	OperatingHours	POI (景點) 的上班時間。
phone	string	電話號碼屬性
url	string	網站 URL 屬性

PointOfInterestCategorySet

POI 類別

名稱	類型	Description
id	integer	類別目錄識別碼

QueryType

要傳回的查詢類型：NEARBY 或 NON_NEAR。

名稱	類型	Description
NEARBY	string	搜尋是在具有定義半徑的特定緯度和經度周圍執行
NON_NEAR	string	搜尋是在全域執行，而不會偏差為特定緯度和經度，且未定義半徑

Response

查詢的結果。如果查詢順利完成，則 SearchAddressResult，否則為 ErrorResponse。

名稱	類型	Description
error	ErrorDetail	錯誤物件。
results	SearchAddressResultItem[]	#DE8C51C4F69A442788047ABA6E144B6DD API 結果的清單。
summary	SearchSummary	搜尋 API 回應的 Summary 物件

SearchAddressBatchItem

從搜尋 Address Batch 服務呼叫傳回的專案。

名稱	類型	Description
response	Response	查詢的結果。如果查詢順利完成，則 SearchAddressResult，否則為 ErrorResponse。
statusCode	integer	HTTP 要求狀態代碼。

SearchAddressBatchProcessResult

此物件會從成功搜尋 Address Batch 服務呼叫傳回。

名稱	類型	Description
batchItems	SearchAddressBatchItem[]	包含批次結果的陣列。
summary	Summary	批次要求的結果摘要

SearchAddressResultItem

搜尋 API 回應的結果物件。

名稱	類型	Description
address	Address	結果的位址
addressRanges	AddressRanges	描述街道兩邊的位址範圍，以取得搜尋結果。包含位址範圍的開始和結束位置座標。
dataSources	DataSources	選擇性章節。參考幾何標識符，以搭配 Get 搜尋 Polygon API 使用。
detourTime	integer	以秒為單位的繞道時間。只針對路由 API 對搜尋的呼叫傳回。
dist	number	結果與地理位置之間的直線距離，以公尺為單位。
entityType	GeographicEntityType	Geography 實體類型。只有在要求 entityType 且可供使用時才存在。
entryPoints	EntryPoint[]	EntryPoints 的陣列。這些描述位置可用的入口類型。對於側門和後門，類型可以是主要入口的「主要」，例如前門或大廳和「次要」。
id	string	Id 屬性
info	string	Result 原始數據源的相關信息。用於支援要求。
matchType	MatchType	相符類型的相關信息。值為下列其中之一： AddressPoint HouseNumberRange 街道
poi	PointOfInterest	傳回 POI 的詳細數據，包括名稱、電話、URL 位址和分類等資訊。
position	LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱『lat』 & 『lon』。
score	number	結果集中的值，表示結果之間的相對比對分數。您可以使用這個來判斷如果 x 的值是 y 值 2 倍，結果 x 可能會與結果 y 一樣相關。這些值會因查詢而異，而且只做為一個結果集的相對值。
type	SearchAddressResultType	值為下列其中之一： POI 街道 [地理位置] 點地址位址範圍交叉路口
viewport	BoundingBox	檢視區，涵蓋檢視區左上角和右下角座標所代表的結果。

SearchAddressResultType

值為下列其中之一：

POI
街道
[地理位置]
點地址
位址範圍
交叉路口

名稱	類型	Description
Address Range	string
Cross Street	string
Geography	string
POI	string
Point Address	string
Street	string

SearchSummary

搜尋 API 回應的 Summary 物件。

名稱	類型	Description
fuzzyLevel	integer	提供結果所需的最大模糊層級。
geoBias	LatLongPairAbbreviated	指出內部搜尋引擎何時套用地理空間偏差來改善結果的排名。在某些方法中，設定可用的 lat 和 lon 參數可能會受到影響。在其他情況下，它只是內部。
limit	integer	將傳回的回應數目上限
numResults	integer	回應中的結果數目。
offset	integer	完整結果集中傳回結果的起始位移。
query	string	用來產生這些搜尋結果的查詢參數。
queryTime	integer	解析查詢所花費的時間，以毫秒為單位。
queryType	QueryType	要傳回的查詢類型：NEARBY 或 NON_NEAR。
totalResults	integer	找到的結果總數。

Summary

批次要求的結果摘要

名稱	類型	Description
successfulRequests	integer	批次中成功的要求數目
totalRequests	integer	批次中的要求總數

共用方式為

Search - Post Search Address Batch

提交同步批次要求

提交異步批次要求

批次要求的 POST 本文

下載異步批次結果

批次回應模型

URI 參數

要求標頭

要求本文

回應

安全性

AADToken

範圍

subscription-key

SAS Token

範例

An Address Geocoding Batch API call containing 5 Address Geocoding API queries

範例要求

範例回覆

定義

Address

AddressRanges

BatchRequest

BatchRequestItem

BoundingBox

BoundingBoxCompassNotation

Brand

Classification

ClassificationName

DataSources

Entity

EntryPoint

EntryPointType

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

GeographicEntityType

Geometry

JsonFormat

LatLongPairAbbreviated

MatchType

OperatingHours

OperatingHoursTime

OperatingHoursTimeRange

PointOfInterest

PointOfInterestCategorySet

QueryType

Response

SearchAddressBatchItem

SearchAddressBatchProcessResult

SearchAddressResultItem

SearchAddressResultType

SearchSummary

Summary

其他資源