Places REST API reference

Use the Microsoft Web IQ Places API to search for places and retrieve structured information such as addresses, opening hours, reviews, and photos. Endpoint: POST https://api.microsoft.ai/v3/search/places

All requests require an API key or Microsoft Entra ID access token. See Authentication for setup instructions.

Sample request

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

Parameter Required Type Default Description
query Yes string - A search query for places, for example, popular restaurants in Seattle, WA. Maximum length is 1000 characters.
maxResults No integer 10 Maximum number of results to return. Must be between 1 and 10; out-of-range values return a validation error. Omitted or null uses 10. Fewer results may be returned when fewer places are available.
language No string "en" A 2-letter ISO 639-1 language code for interface language in the search results. See Supported languages for the full list.
region No string "US" A 2-letter country/region code for where the results should come from, for example, "US", "JP", or "FR". See Supported regions for the full list.
location No string - Location information in lat:<float>;long:<float> format. If not specified, the service uses location information from the query.

Request headers

Field Type Description
host string Host for Microsoft AI APIs: api.microsoft.ai.
x-apikey or Authorization string Your API key or Entra ID access token for authentication.
content-type string MIME type of the request body. Use application/json.

Response

Fields with null or empty string values are omitted from the response, and list fields can be empty ([]) or absent. Treat an absent field as unavailable and an empty or absent list as having no items. See Understand the response.

PlacesResponse

Field Type Description
placeResults array of PlaceResult List of place results.
traceId string Trace ID for debugging and tracking.

PlaceResult

Field Type Description
name string The name of the place.
category string Category information.
phone string Contact phone number.
businessUrl string The business URL for the place.
location PlaceLocation Location information.
timeZone string The place's UTC offset, for example, UTC-08:00 (8 hours behind UTC, equivalent to the ISO 8601 offset -08:00).
openHours PlaceOpenHour Opening hours information.
closureState string Indicates if the place is permanently or temporarily closed.
descriptions array of PlaceDescription Descriptions or highlights of the place.
passages array of Passage List of passages and links related to the query.
reviews array of PlaceReview Provider ratings and individual review details.
photos array of PlacePhoto List of photos.
amenities array of string Amenities offered by the place.
actions array of PlaceAction Actions associated with the place.
socialProfiles array of PlaceSocialProfile Social media profiles associated with the place.

PlaceLocation

The following field names are JSON property names returned by the API.

Field Type Description
addressLine string Address line.
city string City name.
region string State or region.
country string Country or region name.
postalCode string Postal or ZIP code.
latitude double Latitude coordinate.
longitude double Longitude coordinate.

PlaceReview

Field Type Description
ratingScore double, optional Aggregated rating score, ranging from 1 to 5. Omitted when the provider has no aggregated rating.
ratingCount integer, optional Number of ratings. Omitted when the provider has no aggregated rating.
reviewDetails array of PlaceReviewDetail Individual review details from the provider.
providerName string Provider's name.
providerLogo string Provider's logo URL.
providerUrl string Provider's website URL.

PlaceReviewDetail

Field Type Description
text string Review text.
score double Review score. The scale depends on the review provider.

PlacePhoto

Field Type Description
url string Photo URL.
caption string Description of the photo.
thumbnailUrl string Thumbnail image URL.
providerName string Provider's name.
providerUrl string Provider's website URL.

PlaceOpenHour

Field Type Description
standard map<string, string[]> Map of standard weekly open-hour ranges keyed by day (mon, tue, wed, thu, fri, sat, sun). Each value is an array of HH:mm-HH:mm ranges.
exceptions array of PlaceOpenHourException Opening hours or closures that apply on specific dates.

PlaceOpenHourException

Field Type Description
date string The date on which the exception applies.
closed boolean Whether the place is closed on the exception date.
hours array of string The opening-hour ranges that apply on the exception date.

PlaceAction

Field Type Description
actionType string The type of action available at the URL.
url string The URL for performing the action.
providerName string Provider's name.
providerLogo string Provider's logo URL.
providerUrl string Provider's website URL.

PlaceDescription

Field Type Description
text string A description or highlight for the place.
providerName string Provider's name.
providerLogo string Provider's logo URL.
providerUrl string Provider's website URL.

PlaceSocialProfile

Field Type Description
name string The name of the social network or profile.
url string The URL of the social profile.
logo string The URL of the social profile's logo.

Passage

Field Type Description
url string The URL of the passage.
content string The text content of the passage.
crawledAt string The date when the passage was last crawled.

Example response

{
  "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 tool

The Places MCP tool is named places. It accepts the same parameters as the REST API (see Parameters) and returns the same response object in structuredContent. For setup, see 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
}

Error codes

Status Code Error Category Description Common Causes
200 Success The request succeeded. -
400 Bad Request Invalid request parameters. Missing required fields, invalid parameter values, malformed JSON
401 Unauthorized Authentication failed or missing. Invalid API key, missing x-apikey header
403 Forbidden Valid credentials but insufficient permissions. The calling Web IQ AppID isn't enabled for Places
410 Gone HTTPS required. Request made over HTTP instead of HTTPS
415 Unsupported Media Type Content type not supported. Missing or incorrect content-type header
429 Too Many Requests Rate limit exceeded. Too many requests in time window
500 Internal Server Error Server or upstream service failure. Temporary server issue, upstream service failure or timeout

For detailed error handling guidance, see Error handling.