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. |
| 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"
}
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.
Related content