Coloca referência à API REST

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.

Cabeçalhos de solicitação

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

Ferramenta MCP

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.