Referência da API REST de Places

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.

Cabeçalhos de solicitação

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

Ferramenta MCP

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.