放置 REST API 参考

使用 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"
}

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 成功 请求成功。 -
400 错误的请求 无效的请求参数。 缺少必填字段、无效参数值、格式不正确的 JSON
401 Unauthorized 身份验证失败或缺失。 API 密钥无效,缺少 x-apikey 标头
403 已禁止 有效凭据但权限不足。 未为 Places 启用调用 Web IQ AppID
410 不存在 (Gone) 需要 HTTPS。 通过 HTTP 而不是 HTTPS 发出的请求
415 不支持的媒体类型 不支持内容类型。 缺少或不正确的内容类型标头
429 请求过多 超出速率限制。 时间范围内请求过多
500 内部服务器错误 服务器或上游服务故障。 临时服务器问题、上游服务故障或超时

有关详细的错误处理指南,请参阅 错误处理。