Use a API IQ Places da Microsoft Web para procurar locais e obter informações estruturadas, como moradas, horários de funcionamento, avaliações e fotografias.
Endpoint:POST https://api.microsoft.ai/v3/search/places
Todos os pedidos requerem uma chave API ou token de acesso Microsoft Entra ID.
Consulte Autenticação para instruções de configuração.
Pedido de amostra
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 |
Tipo |
Default |
Description |
query |
Yes |
cadeia (de caracteres) |
- |
Uma consulta de pesquisa para locais, por exemplo, popular restaurants in Seattle, WA. O comprimento máximo é de 1000 caracteres. |
maxResults |
No |
número inteiro |
10 |
Número máximo de resultados a devolver. Deve estar entre 1 e 10; valores fora do intervalo devolvem um erro de validação. Omitido ou nulo usa 10. Menos resultados podem ser devolvidos quando houver menos vagas disponíveis. |
language |
No |
cadeia (de caracteres) |
"en" |
Um código de língua ISO 639-1 de 2 letras para a linguagem de interface nos resultados de pesquisa.
Consulte Linguagens suportadas para a lista completa. |
region |
No |
cadeia (de caracteres) |
"US" |
Um código de país/região de 2 letras para indicar de onde devem vir os resultados, por exemplo, "EUA", "JP" ou "FR".
Consulte Regiões Suportadas para a lista completa. |
location |
No |
cadeia (de caracteres) |
- |
Informação de localização em lat:<float>;long:<float> formato. Se não for especificado, o serviço utiliza a informação de localização da consulta. |
| Field |
Tipo |
Description |
| alojar |
cadeia (de caracteres) |
Alojamento para APIs de IA da Microsoft: api.microsoft.ai. |
| x-apikey ou Autorização |
cadeia (de caracteres) |
A sua chave API ou token de acesso do Entra ID para autenticação. |
| tipo de conteúdo |
cadeia (de caracteres) |
Tipo MIME do corpo do pedido. Utilize application/json. |
Resposta
Campos com null ou valores de cadeia vazios são omitidos da resposta, e campos de lista podem estar vazios ([]) ou ausentes. Trate um campo ausente como indisponível e uma lista vazia ou ausente como sem itens. Veja Compreender a resposta.
PlacesResposta
| Field |
Tipo |
Description |
placeResults |
array de PlaceResult |
Lista de resultados de lugares. |
traceId |
cadeia (de caracteres) |
ID de rastreio para depuração e rastreio. |
PlaceResult
| Field |
Tipo |
Description |
name |
cadeia (de caracteres) |
O nome do lugar. |
category |
cadeia (de caracteres) |
Informação sobre categorias. |
phone |
cadeia (de caracteres) |
Número de telefone de contato. |
businessUrl |
cadeia (de caracteres) |
O URL do negócio do local. |
location |
LugarLocalização |
Informações de localização. |
timeZone |
cadeia (de caracteres) |
O deslocamento UTC do local, por exemplo, UTC-08:00 (8 horas atrás do UTC, equivalente ao deslocamento -08:00ISO 8601). |
openHours |
PlaceOpenHour |
Informação sobre horários de funcionamento. |
closureState |
cadeia (de caracteres) |
Indica se o local está encerrado permanentemente ou temporariamente. |
descriptions |
array do PlaceDescription |
Descrições ou destaques do local. |
passages |
array de Passagem |
Lista de passagens e links relacionados com a consulta. |
reviews |
array de PlaceReview |
Avaliações dos fornecedores e detalhes de avaliações individuais. |
photos |
array do PlacePhoto |
Lista de fotografias. |
amenities |
Matriz de cadeia de caracteres |
Comodidades oferecidas pelo local. |
actions |
array de PlaceAction |
Ações associadas ao local. |
socialProfiles |
variedade de PlaceSocialProfile |
Perfis nas redes sociais associados ao local. |
LugarLocalização
Os seguintes nomes de campos são nomes de propriedades JSON devolvidos pela API.
| Field |
Tipo |
Description |
addressLine |
cadeia (de caracteres) |
Linha de endereço. |
city |
cadeia (de caracteres) |
Nome da cidade. |
region |
cadeia (de caracteres) |
Estado ou região. |
country |
cadeia (de caracteres) |
Nome do país ou da região. |
postalCode |
cadeia (de caracteres) |
Código postal ou CEP. |
latitude |
double |
Coordenada de latitude. |
longitude |
double |
Coordenada de longitude. |
PlaceReview
| Field |
Tipo |
Description |
ratingScore |
Duplo, opcional |
Pontuação agregada de classificação, variando de 1 a 5. É omitido quando o fornecedor não tem uma classificação agregada. |
ratingCount |
inteiro, opcional |
Número de audiências. É omitido quando o fornecedor não tem uma classificação agregada. |
reviewDetails |
array de PlaceReviewDetail |
Detalhes de avaliação individual do prestador. |
providerName |
cadeia (de caracteres) |
Nome do prestador. |
providerLogo |
cadeia (de caracteres) |
URL do logótipo do fornecedor. |
providerUrl |
cadeia (de caracteres) |
URL do site do fornecedor. |
LugarDetalheRevisão
| Field |
Tipo |
Description |
text |
cadeia (de caracteres) |
Texto da revisão. |
score |
double |
Pontuação da crítica. A escala depende do fornecedor da avaliação. |
PlacePhoto
| Field |
Tipo |
Description |
url |
cadeia (de caracteres) |
URL da foto. |
caption |
cadeia (de caracteres) |
Descrição da foto. |
thumbnailUrl |
cadeia (de caracteres) |
URL da imagem em miniatura. |
providerName |
cadeia (de caracteres) |
Nome do prestador. |
providerUrl |
cadeia (de caracteres) |
URL do site do fornecedor. |
PlaceOpenHour
| Field |
Tipo |
Description |
standard |
map<string, string[]> |
Mapa dos intervalos semanais padrão de horas de abertura codificados por dia (mon, tue, wed, thu, fri, sat, sun, ). Cada valor é um array de HH:mm-HH:mm intervalos. |
exceptions |
array de PlaceOpenHourException |
Horários de funcionamento ou encerramentos que se aplicam em datas específicas. |
PlaceOpenHourException
| Field |
Tipo |
Description |
date |
cadeia (de caracteres) |
A data em que a exceção se aplica. |
closed |
boolean |
Se o local está encerrado na data da exceção. |
hours |
Matriz de cadeia de caracteres |
Os intervalos de horas de abertura que se aplicam na data da exceção. |
PlaceAction
| Field |
Tipo |
Description |
actionType |
cadeia (de caracteres) |
O tipo de ação disponível na URL. |
url |
cadeia (de caracteres) |
O URL para realizar a ação. |
providerName |
cadeia (de caracteres) |
Nome do prestador. |
providerLogo |
cadeia (de caracteres) |
URL do logótipo do fornecedor. |
providerUrl |
cadeia (de caracteres) |
URL do site do fornecedor. |
Descrição do Lugar
| Field |
Tipo |
Description |
text |
cadeia (de caracteres) |
Uma descrição ou destaque do local. |
providerName |
cadeia (de caracteres) |
Nome do prestador. |
providerLogo |
cadeia (de caracteres) |
URL do logótipo do fornecedor. |
providerUrl |
cadeia (de caracteres) |
URL do site do fornecedor. |
LugarPerfilSocialT
| Field |
Tipo |
Description |
name |
cadeia (de caracteres) |
O nome da rede social ou do perfil. |
url |
cadeia (de caracteres) |
O URL do perfil social. |
logo |
cadeia (de caracteres) |
A URL do logótipo do perfil social. |
Passagem
| Field |
Tipo |
Description |
url |
cadeia (de caracteres) |
O URL da passagem. |
content |
cadeia (de caracteres) |
O conteúdo do texto da passagem. |
crawledAt |
cadeia (de caracteres) |
A data em que a passagem foi rastejada 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 Places MCP chama-se places. Aceita os mesmos parâmetros da API REST (ver Parâmetros) e devolve o mesmo objeto de resposta em structuredContent. Para configuração, veja 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 estado |
Categoria de Erro |
Description |
Causas Comuns |
| 200 |
Success |
O pedido foi bem-sucedido. |
- |
| 400 |
Pedido Incorreto |
Parâmetros de pedido inválidos. |
Campos obrigatórios em falta, valores de parâmetros inválidos, JSON mal formado |
| 401 |
Não autorizado |
Autenticação falhada ou em falta. |
Chave API inválida, falta do cabeçalho x-apikey |
| 403 |
Proibido |
Credenciais válidas mas permissões insuficientes. |
O AppID Web IQ que chama não está ativado para Lugares |
| 410 |
Desapareceu |
HTTPS necessário. |
Pedido feito por HTTP em vez de HTTPS |
| 415 |
Tipo de Media Não Suportado |
Tipo de conteúdo não suportado. |
Cabeçalho de tipo de conteúdo em falta ou incorreto |
| 429 |
Demasiados Pedidos |
Limite de taxa ultrapassado. |
Demasiados pedidos numa janela temporal |
| 500 |
Erro interno do servidor |
Falha do servidor ou do serviço a montante. |
Problema temporário no servidor, falha do serviço a montante ou timeout |
Para orientações detalhadas sobre o tratamento de erros, veja Gestão de erros.
Conteúdo relacionado