使用 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"
}
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 |
內部伺服器錯誤 |
伺服器或上游服務故障。 |
臨時伺服器問題、上游服務故障或超時 |
如需詳細的錯誤處理指引,請參見錯誤處理。
相關內容