Use a API Microsoft Web IQ Places para pesquisar locais e recuperar informações estruturadas, como endereços, horários de funcionamento, revisões e fotos.
Endpoint:POST https://api.microsoft.ai/v3/search/places
Todas as solicitações exigem uma chave de API ou um token de acesso Microsoft Entra ID. Consulte Autenticação para obter instruções de instalação.
Solicitação de exemplo
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
| Parâmetro |
Required |
Tipo |
Default |
Description |
query |
Yes |
cadeia |
- |
Uma consulta de pesquisa para locais, por exemplo, popular restaurants in Seattle, WA. O comprimento máximo é de 1000 caracteres. |
maxResults |
No |
inteiro |
10 |
Número máximo de resultados a serem retornados. Deve estar entre 1 e 10; Valores fora do intervalo retornam um erro de validação. Omitido ou nulo usa 10. Menos resultados podem ser retornados quando menos locais estão disponíveis. |
language |
No |
cadeia |
"en" |
Um código de idioma ISO 639-1 de 2 letras para linguagem de interface nos resultados da pesquisa. Consulte os idiomas com suporte para a lista completa. |
region |
No |
cadeia |
"US" |
Um código de país/região de duas letras de onde os resultados devem vir, por exemplo, "EUA", "JP" ou "FR". Consulte as regiões com suporte para a lista completa. |
location |
No |
cadeia |
- |
Informações de localização em lat:<float>;long:<float> formato. Se não for especificado, o serviço usará informações de localização da consulta. |
| Field |
Tipo |
Description |
| hospedar |
cadeia |
Host para APIs de IA Microsoft: api.microsoft.ai. |
| x-apikey ou Autorização |
cadeia |
Sua chave de API ou Entra ID token de acesso para autenticação. |
| tipo de conteúdo |
cadeia |
Tipo MIME do corpo da solicitação. Use application/json. |
Resposta
Campos com null ou valores de cadeia de caracteres vazios são omitidos da resposta e os campos de lista podem estar vazios ([]) ou ausentes. Trate um campo ausente como indisponível e uma lista vazia ou ausente como sem itens. Consulte Noções básicas sobre a resposta.
PlacesResponse
| Field |
Tipo |
Description |
placeResults |
matriz de PlaceResult |
Lista de resultados do local. |
traceId |
cadeia |
ID de rastreamento para depuração e acompanhamento. |
PlaceResult
| Field |
Tipo |
Description |
name |
cadeia |
O nome do lugar. |
category |
cadeia |
Informações sobre categoria. |
phone |
cadeia |
Contate o número de telefone. |
businessUrl |
cadeia |
A URL de negócios para o local. |
location |
PlaceLocation |
Informações de localização. |
timeZone |
cadeia |
O deslocamento UTC do local, por exemplo, UTC-08:00 (8 horas atrás de UTC, equivalente ao deslocamento -08:00ISO 8601). |
openHours |
PlaceOpenHour |
Informações de horário de funcionamento. |
closureState |
cadeia |
Indica se o local está permanente ou temporariamente fechado. |
descriptions |
matriz de PlaceDescription |
Descrições ou realces do local. |
passages |
matriz de Passagem |
Lista de passagens e links relacionados à consulta. |
reviews |
matriz de PlaceReview |
Classificações do provedor e detalhes de revisão individual. |
photos |
matriz de PlacePhoto |
Lista de fotos. |
amenities |
matriz de strings |
Comodidades oferecidas pelo lugar. |
actions |
matriz de PlaceAction |
Ações associadas ao local. |
socialProfiles |
matriz de PlaceSocialProfile |
Perfis de mídia social associados ao local. |
PlaceLocation
Os nomes de campo a seguir são nomes de propriedade JSON retornados pela API.
| Field |
Tipo |
Description |
addressLine |
cadeia |
Linha de endereço. |
city |
cadeia |
Nome da cidade. |
region |
cadeia |
Estado ou região. |
country |
cadeia |
Nome do país ou região. |
postalCode |
cadeia |
CeP ou CEP. |
latitude |
duplo |
Coordenada de latitude. |
longitude |
duplo |
Coordenada longitude. |
PlaceReview
| Field |
Tipo |
Description |
ratingScore |
duplo, opcional |
Pontuação de classificação agregada, variando de 1 a 5. Omitido quando o provedor não tem classificação agregada. |
ratingCount |
inteiro, opcional |
Número de classificações. Omitido quando o provedor não tem classificação agregada. |
reviewDetails |
matriz de PlaceReviewDetail |
Detalhes de revisão individual do provedor. |
providerName |
cadeia |
Nome do provedor. |
providerLogo |
cadeia |
URL do logotipo do provedor. |
providerUrl |
cadeia |
URL do site do provedor. |
PlaceReviewDetail
| Field |
Tipo |
Description |
text |
cadeia |
Revise o texto. |
score |
duplo |
Pontuação de revisão. A escala depende do provedor de revisão. |
PlacePhoto
| Field |
Tipo |
Description |
url |
cadeia |
URL da foto. |
caption |
cadeia |
Descrição da foto. |
thumbnailUrl |
cadeia |
URL da imagem em miniatura. |
providerName |
cadeia |
Nome do provedor. |
providerUrl |
cadeia |
URL do site do provedor. |
PlaceOpenHour
| Field |
Tipo |
Description |
standard |
map<string, string[]> |
Mapa de intervalos de horas abertas semanais padrão chaveados por dia (mon, , tue, wed, thu, fri, sat, ). sun Cada valor é uma matriz de HH:mm-HH:mm intervalos. |
exceptions |
matriz de PlaceOpenHourException |
Horários de funcionamento ou fechamentos que se aplicam a datas específicas. |
PlaceOpenHourException
| Field |
Tipo |
Description |
date |
cadeia |
A data em que a exceção se aplica. |
closed |
boolean |
Se o local está fechado na data da exceção. |
hours |
matriz de strings |
Os intervalos de hora de abertura que se aplicam na data da exceção. |
PlaceAction
| Field |
Tipo |
Description |
actionType |
cadeia |
O tipo de ação disponível na URL. |
url |
cadeia |
A URL para executar a ação. |
providerName |
cadeia |
Nome do provedor. |
providerLogo |
cadeia |
URL do logotipo do provedor. |
providerUrl |
cadeia |
URL do site do provedor. |
PlaceDescription
| Field |
Tipo |
Description |
text |
cadeia |
Uma descrição ou realce para o local. |
providerName |
cadeia |
Nome do provedor. |
providerLogo |
cadeia |
URL do logotipo do provedor. |
providerUrl |
cadeia |
URL do site do provedor. |
PlaceSocialProfile
| Field |
Tipo |
Description |
name |
cadeia |
O nome da rede social ou do perfil. |
url |
cadeia |
A URL do perfil social. |
logo |
cadeia |
A URL do logotipo do perfil social. |
Passagem
| Field |
Tipo |
Description |
url |
cadeia |
A URL da passagem. |
content |
cadeia |
O conteúdo do texto da passagem. |
crawledAt |
cadeia |
A data em que a passagem foi rastreada pela última vez. |
Resposta de exemplo
{
"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"
}
A ferramenta LOCAIS MCP é denominada places. Ele aceita os mesmos parâmetros que a API REST (ver Parâmetros) e retorna o mesmo objeto de resposta em structuredContent. Para configurar, consulte 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
}
Códigos de erro
| Código de Status |
Categoria do Erro |
Description |
Causas comuns |
| 200 |
Êxito |
O pedido foi bem-sucedido. |
- |
| 400 |
Solicitação incorreta |
Parâmetros de solicitação inválidos. |
Campos necessários ausentes, valores de parâmetro inválidos, JSON malformado |
| 401 |
Unauthorized |
Falha ou falha na autenticação. |
Chave de API inválida, cabeçalho x-apikey ausente |
| 403 |
Proibido |
Credenciais válidas, mas permissões insuficientes. |
A chamada IQ AppID da Web não está habilitada para Locais |
| 410 |
Sumiu (Gone) |
HTTPS necessário. |
Solicitação feita por HTTP em vez de HTTPS |
| 415 |
Tipo de mídia sem suporte |
Não há suporte para o tipo de conteúdo. |
Cabeçalho de tipo de conteúdo ausente ou incorreto |
| 429 |
Número Excessivo de Solicitações |
Limite de taxa excedido. |
Muitas solicitações na janela de tempo |
| 500 |
Erro interno do servidor |
Falha no servidor ou no serviço upstream. |
Problema temporário do servidor, falha ou tempo limite do serviço upstream |
Para obter diretrizes detalhadas de tratamento de erros, consulte Tratamento de erros.
Conteúdo relacionado