Places REST API 參考

使用 Microsoft Web IQ Places API 搜尋地點並取得結構化資訊,如地址、營業時間、評論和照片。 端點:POST https://api.microsoft.ai/v3/search/places

所有請求都需要 API 金鑰或 Microsoft Entra ID 存取權杖。 請參閱 認證 部分的設定說明。

範例要求

curl -X POST "https://api.microsoft.ai/v3/search/places" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Cafe Flora Seattle",
    "maxResults": 5,
    "language": "en",
    "region": "US",
    "location": "lat:47.6062;long:-122.3321"
  }'

Parameters

參數 Required 類型 Default Description
query Yes 字串 - 例如,對地點的搜尋查詢。 popular restaurants in Seattle, WA 長度上限為 1000 個字元。
maxResults No 整數 10 要傳回的結果數目上限。 必須介於1到10之間;超出範圍的值會回傳驗證錯誤。 省略或空的使用10。 當名額減少時,回報的成績可能會減少。
language No 字串 「en」 搜尋結果中介面語言的兩字母 ISO 639-1 語言代碼。 完整列表請參閱 支援語言 。
region No 字串 "US" 一個兩字母的國家/地區代碼,表示結果應該來自哪裡,例如「美國」、「日本」或「FR」。 完整列表請參閱 支援地區 。
location No 字串 - 位置資訊格式化 lat:<float>;long:<float> 。 若未指定,服務會使用查詢中的位置資訊。

請求標頭

Field 類型 Description
主持人 字串 Microsoft AI API 主機: api.microsoft.ai
x-apikey 或 授權 字串 你的 API 金鑰或 Entra ID 存取權杖用於認證。
內容類型 字串 請求實體的 MIME 類型。 請使用 application/json。

回應

包含 null 或空字串值的欄位會被省略,列表欄位則可能是空[]()或缺席。 將缺席欄位視為不可用,空缺清單視為無項目。 請參閱「了解回應」。

地點回應

Field 類型 Description
placeResults PlaceResult 陣列 名次成績列表。
traceId 字串 追蹤識別碼用於除錯與追蹤。

地點結果

Field 類型 Description
name 字串 地點的名稱。
category 字串 分類資訊。
phone 字串 聯絡電話號碼。
businessUrl 字串 該地點的商業網址。
location 地點地點 位置資訊。
timeZone 字串 例如 UTC-08:00 該地的UTC偏移(比UTC慢8小時,相當於ISO 8601的偏移 -08:00)。
openHours 地點開放時段 營業時間資訊。
closureState 字串 表示該地點是永久還是暫時關閉。
descriptions 地點描述陣列 關於該地點的描述或亮點。
passages 通道陣列 與查詢相關的段落與連結列表。
reviews PlaceReview 的array 提供者評分與個別評論細節。
photos PlacePhoto 的陣列 照片列表。
amenities 字串陣列 這裡提供的便利設施。
actions PlaceAction 陣列 與該地點相關的行動。
socialProfiles PlaceSocialProfile 陣列 與該地點相關的社群媒體帳號。

地點地點

以下欄位名稱為 API 回傳的 JSON 屬性名稱。

Field 類型 Description
addressLine 字串 地址線。
city 字串 城市名稱。
region 字串 州或地區。
country 字串 國家或地區名稱。
postalCode 字串 郵政編碼或郵政編碼。
latitude double 緯度座標。
longitude double 經度座標。

地點評論

Field 類型 Description
ratingScore 雙重,選配 綜合評分,範圍為1到5。 當提供者沒有綜合評分時,則會被省略。
ratingCount 整數,選擇性 評分數。 當提供者沒有綜合評分時,則會被省略。
reviewDetails 地點數列 ReviewDetail 提供者提供個別評價細節。
providerName 字串 提供者姓名。
providerLogo 字串 服務提供者的標誌網址。
providerUrl 字串 提供者的網站網址。

地點、評論、詳細

Field 類型 Description
text 字串 複習文本。
score double 複習分數。 體重計量表取決於審查機構。

地點照片

Field 類型 Description
url 字串 照片網址。
caption 字串 照片描述。
thumbnailUrl 字串 縮圖影像 URL。
providerName 字串 提供者姓名。
providerUrl 字串 提供者的網站網址。

地點開放時段

Field 類型 Description
standard map<string, string[]> 標準每週開放時間範圍地圖,按天mon數(, tue, wedthufrisat) sun 每個值是一個範圍 HH:mm-HH:mm 陣列。
exceptions array of PlaceOpenHourException 特定日期的開放時間或休息時間。

PlaceOpenHourException

Field 類型 Description
date 字串 例外適用的日期。
closed boolean 該地點在例外日期是否關閉。
hours 字串陣列 例外日期適用的開放時間範圍。

地點行動

Field 類型 Description
actionType 字串 網址上可行的動作類型。
url 字串 執行動作的網址。
providerName 字串 提供者姓名。
providerLogo 字串 服務提供者的標誌網址。
providerUrl 字串 提供者的網站網址。

地點描述

Field 類型 Description
text 字串 一個地方的描述或亮點。
providerName 字串 提供者姓名。
providerLogo 字串 服務提供者的標誌網址。
providerUrl 字串 提供者的網站網址。

地點社會檔案

Field 類型 Description
name 字串 社交網路或個人檔案名稱。
url 字串 社群帳號的網址。
logo 字串 社群帳號標誌的網址。

通道

Field 類型 Description
url 字串 該段落的網址。
content 字串 文章內容。
crawledAt 字串 那是通道最後一次被爬行的日期。

範例回應

{
  "placeResults": [
    {
      "name": "Cafe Flora",
      "category": "Vegetarian restaurant",
      "phone": "(206) 325-9100",
      "businessUrl": "https://cafeflora.com/",
      "location": {
        "addressLine": "2901 E Madison St",
        "city": "Seattle",
        "region": "WA",
        "postalCode": "98112",
        "country": "United States",
        "latitude": 47.624027,
        "longitude": -122.29511
      },
      "timeZone": "UTC-08:00",
      "openHours": {
        "standard": {
          "tue": ["09:00-21:00"],
          "wed": ["09:00-21:00"],
          "thu": ["09:00-21:00"],
          "fri": ["09:00-21:00"],
          "sat": ["08:00-14:30", "17:00-21:00"],
          "sun": ["08:00-14:30", "17:00-21:00"]
        },
        "exceptions": [
          {
            "date": "2026-12-24",
            "closed": false,
            "hours": ["11:00-16:00", "17:00-22:00"]
          }
        ]
      },
      "descriptions": [
        {
          "text": "Established in 1991, Cafe Flora serves vegetarian, vegan, and gluten-free cuisine.",
          "providerName": "Cafe Flora",
          "providerLogo": "https://cafeflora.com/favicon.ico",
          "providerUrl": "https://cafeflora.com/"
        }
      ],
      "passages": [
        {
          "url": "https://cafeflora.com/about/",
          "content": "Cafe Flora has served creative vegetarian cuisine in Seattle since 1991.",
          "crawledAt": "2026-09-15T18:30:00Z"
        }
      ],
      "reviews": [
        {
          "ratingScore": 4,
          "ratingCount": 128,
          "reviewDetails": [],
          "providerName": "HappyCow",
          "providerLogo": "https://www.bing.com/th?id=OLC.HappyCowLogo.png&pid=Local",
          "providerUrl": "https://www.happycow.net/reviews/cafe-flora-seattle-2628"
        },
        {
          "reviewDetails": [
            {
              "text": "Great vegetarian restaurant with excellent vegan and gluten-free options.",
              "score": 5
            }
          ],
          "providerName": "Tripadvisor",
          "providerLogo": "https://www.bing.com/th?id=OLC.TripAdvisor_Filled.png&pid=Local",
          "providerUrl": "https://www.tripadvisor.com/Restaurant_Review-g60878-d432891-Reviews-Cafe_Flora-Seattle_Washington.html"
        },
        {
          "reviewDetails": [
            {
              "text": "A lovely restaurant with seasonal dishes and a garden-like atmosphere.",
              "score": 5
            }
          ],
          "providerName": "Yelp",
          "providerLogo": "https://www.bing.com/th?id=OLC.Yelp_Filled.png&pid=Local",
          "providerUrl": "https://www.yelp.com/biz/cafe-flora-seattle"
        }
      ],
      "photos": [
        {
          "url": "https://images.happycow.net/venues/1024/26/28/hcmp2628_1105421.jpeg",
          "caption": "Cafe Flora dining area",
          "thumbnailUrl": "https://www.bing.com/th?id=OLC.+h449su81zbOig480x360",
          "providerName": "HappyCow",
          "providerUrl": "https://www.happycow.net/reviews/cafe-flora-seattle-2628"
        },
        {
          "url": "https://images.happycow.net/venues/1024/26/28/hcmp2628_685679.jpeg",
          "caption": "Vegetarian dish served at Cafe Flora",
          "thumbnailUrl": "https://www.bing.com/th?id=OLC.1w7CsoUrqXZGsQ480x360",
          "providerName": "HappyCow",
          "providerUrl": "https://www.happycow.net/reviews/cafe-flora-seattle-2628"
        }
      ],
      "amenities": ["Vegan options", "Gluten-free options"],
      "actions": [
        {
          "actionType": "Menu",
          "url": "https://places.singleplatform.com/cafe-flora/menu",
          "providerName": "SinglePlatform",
          "providerLogo": "https://places.singleplatform.com/favicon.ico",
          "providerUrl": "https://places.singleplatform.com/"
        }
      ],
      "socialProfiles": [
        {
          "name": "Facebook",
          "url": "https://www.facebook.com/CafeFloraVeg/",
          "logo": "https://www.facebook.com/favicon.ico"
        },
        {
          "name": "Instagram",
          "url": "https://www.instagram.com/cafefloraveg/",
          "logo": "https://www.instagram.com/favicon.ico"
        }
      ]
    }
  ],
  "traceId": "abc123-def456-ghi789"
}

MCP 工具

Places MCP 工具命名為 places。 它接受與 REST API 相同的參數(參見參數),並在 中回傳相同的回應物件。structuredContent 關於設定,請參見 MCP。

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "places",
    "arguments": {
      "query": "Cafe Flora Seattle",
      "maxResults": 5,
      "language": "en",
      "region": "US",
      "location": "lat:47.6062;long:-122.3321"
    }
  },
  "id": 1
}

錯誤碼

狀態代碼 錯誤類別 Description 常見的原因
200 Success 請求成功。 -
400 錯誤的請求 請求參數無效。 缺少必填欄位、參數值無效、JSON 格式錯誤
401 Unauthorized 驗證失敗或缺失。 API 金鑰無效,缺少 x-apikey 標頭
403 禁止 有效的憑證,但權限不足。 呼叫的 Web IQ AppID 未啟用 Places
410 消失了 需要 HTTPS 認證。 請求是透過 HTTP 而非 HTTPS 進行的
415 不支援媒體類型 內容類型不支援。 缺少或錯誤的內容類型標頭
429 過多要求 速率超過上限。 時間窗口內請求太多
500 內部伺服器錯誤 伺服器或上游服務故障。 臨時伺服器問題、上游服務故障或超時

如需詳細的錯誤處理指引,請參見錯誤處理。