使用 Microsoft Web IQ 位置 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 之间;超出范围的值返回验证错误。 省略或 null 使用 10。 当可用位置较少时,可能会返回更少的结果。 |
language |
No |
字符串 |
“en” |
搜索结果中接口语言的 2 字母 ISO 639-1 语言代码。 有关完整列表,请参阅 支持的语言 。 |
region |
No |
字符串 |
"US" |
结果应来自的 2 个字母国家/地区代码,例如“US”、“JP”或“FR”。 有关完整列表,请参阅 支持的区域 。 |
location |
No |
字符串 |
- |
格式的位置信息 lat:<float>;long:<float> 。 如果未指定,服务将使用查询中的位置信息。 |
| 领域 |
类型 |
Description |
| 主持人 |
字符串 |
适用于 Microsoft AI API 的主机:api.microsoft.ai. |
| x-apikey 或 授权 |
字符串 |
API 密钥或Entra ID访问令牌进行身份验证。 |
| Content-Type |
字符串 |
请求正文的 MIME 类型。 使用 application/json。 |
Response
响应中省略带 null 或空字符串值的字段,列表字段可以为空([])或不存在。 将缺席字段视为不可用,将空或缺席列表视为没有项目。 请参阅 “了解响应”。
PlacesResponse
| 领域 |
类型 |
Description |
placeResults |
PlaceResult 数组 |
位置结果列表。 |
traceId |
字符串 |
用于调试和跟踪的跟踪 ID。 |
PlaceResult
| 领域 |
类型 |
Description |
name |
字符串 |
地点的名称。 |
category |
字符串 |
类别信息。 |
phone |
字符串 |
联系电话号码。 |
businessUrl |
字符串 |
地点的业务 URL。 |
location |
PlaceLocation |
位置信息。 |
timeZone |
字符串 |
例如, UTC-08:00 位置的 UTC 偏移量(比 UTC 落后 8 小时,相当于 ISO 8601 偏移量 -08:00)。 |
openHours |
PlaceOpenHour |
打开小时数信息。 |
closureState |
字符串 |
指示该位置是永久的还是暂时关闭的。 |
descriptions |
PlaceDescription 数组 |
位置的说明或亮点。 |
passages |
段落数组 |
与查询相关的段落和链接的列表。 |
reviews |
PlaceReview 数组 |
提供商分级和个人评审详细信息。 |
photos |
PlacePhoto 数组 |
照片列表。 |
amenities |
字符串数组 |
这个地方提供的设施。 |
actions |
PlaceAction 数组 |
与位置关联的操作。 |
socialProfiles |
PlaceSocialProfile 数组 |
与该地点关联的社交媒体配置文件。 |
PlaceLocation
以下字段名称是 API 返回的 JSON 属性名称。
| 领域 |
类型 |
Description |
addressLine |
字符串 |
地址行。 |
city |
字符串 |
城市名称。 |
region |
字符串 |
州或区域。 |
country |
字符串 |
国家或地区名称。 |
postalCode |
字符串 |
邮政编码。 |
latitude |
double |
纬度坐标。 |
longitude |
double |
经度坐标。 |
PlaceReview
| 领域 |
类型 |
Description |
ratingScore |
double、optional |
聚合评分分数,范围为 1 到 5。 提供程序没有聚合分级时省略。 |
ratingCount |
integer、optional |
分级数。 提供程序没有聚合分级时省略。 |
reviewDetails |
PlaceReviewDetail 数组 |
提供程序中的单独评审详细信息。 |
providerName |
字符串 |
提供程序的名称。 |
providerLogo |
字符串 |
提供程序的徽标 URL。 |
providerUrl |
字符串 |
提供程序的网站 URL。 |
PlaceReviewDetail
| 领域 |
类型 |
Description |
text |
字符串 |
查看文本。 |
score |
double |
查看分数。 规模取决于评审提供程序。 |
PlacePhoto
| 领域 |
类型 |
Description |
url |
字符串 |
照片 URL。 |
caption |
字符串 |
照片的说明。 |
thumbnailUrl |
字符串 |
缩略图 URL。 |
providerName |
字符串 |
提供程序的名称。 |
providerUrl |
字符串 |
提供程序的网站 URL。 |
PlaceOpenHour
| 领域 |
类型 |
Description |
standard |
map<string, string[]> |
按天(mon、tuethuwed、、fri、、、sat)sun键的标准每周开放小时范围的地图。 每个值都是范围的数组 HH:mm-HH:mm 。 |
exceptions |
PlaceOpenHourException 数组 |
在特定日期适用的营业时间或关闭时间。 |
PlaceOpenHourException
| 领域 |
类型 |
Description |
date |
字符串 |
例外适用的日期。 |
closed |
boolean |
地点是否在例外日期关闭。 |
hours |
字符串数组 |
例外日期适用的开小时范围。 |
PlaceAction
| 领域 |
类型 |
Description |
actionType |
字符串 |
URL 中可用的操作类型。 |
url |
字符串 |
用于执行操作的 URL。 |
providerName |
字符串 |
提供程序的名称。 |
providerLogo |
字符串 |
提供程序的徽标 URL。 |
providerUrl |
字符串 |
提供程序的网站 URL。 |
PlaceDescription
| 领域 |
类型 |
Description |
text |
字符串 |
位置的说明或突出显示。 |
providerName |
字符串 |
提供程序的名称。 |
providerLogo |
字符串 |
提供程序的徽标 URL。 |
providerUrl |
字符串 |
提供程序的网站 URL。 |
PlaceSocialProfile
| 领域 |
类型 |
Description |
name |
字符串 |
社交网络或配置文件的名称。 |
url |
字符串 |
社交配置文件的 URL。 |
logo |
字符串 |
社交配置文件徽标的 URL。 |
段落
| 领域 |
类型 |
Description |
url |
字符串 |
段落的 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 |
成功 |
请求成功。 |
- |
| 400 |
错误的请求 |
无效的请求参数。 |
缺少必填字段、无效参数值、格式不正确的 JSON |
| 401 |
Unauthorized |
身份验证失败或缺失。 |
API 密钥无效,缺少 x-apikey 标头 |
| 403 |
已禁止 |
有效凭据但权限不足。 |
未为 Places 启用调用 Web IQ AppID |
| 410 |
不存在 (Gone) |
需要 HTTPS。 |
通过 HTTP 而不是 HTTPS 发出的请求 |
| 415 |
不支持的媒体类型 |
不支持内容类型。 |
缺少或不正确的内容类型标头 |
| 429 |
请求过多 |
超出速率限制。 |
时间范围内请求过多 |
| 500 |
内部服务器错误 |
服务器或上游服务故障。 |
临时服务器问题、上游服务故障或超时 |
有关详细的错误处理指南,请参阅 错误处理。
相关内容