Rest-API-Referenz für Orte

Verwenden Sie die Microsoft Web IQ Places-API, um nach Orten zu suchen und strukturierte Informationen wie Adressen, Öffnungszeiten, Rezensionen und Fotos abzurufen. Endpunkt:POST https://api.microsoft.ai/v3/search/places

Für alle Anforderungen ist ein API-Schlüssel oder Microsoft Entra ID Zugriffstoken erforderlich. Anweisungen zum Einrichten finden Sie unter "Authentifizierung ".

Musteranforderung

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

Parameter

Parameter Required Typ Vorgabe Description
query Yes string - Eine Suchabfrage für Orte, popular restaurants in Seattle, WAz. B. . Die maximale Länge beträgt 1000 Zeichen.
maxResults No integer 10 Maximale Anzahl der zurückzugebenden Ergebnisse. Muss zwischen 1 und 10 sein; Out-of-Range-Werte geben einen Überprüfungsfehler zurück. Ausgelassen oder NULL verwendet 10. Weniger Ergebnisse können zurückgegeben werden, wenn weniger Orte verfügbar sind.
language No string „de“ Ein 2-Buchstaben-ISO 639-1-Sprachcode für die Schnittstellensprache in den Suchergebnissen. Die vollständige Liste finden Sie unter "Unterstützte Sprachen ".
region No string "US" Ein 2-Buchstaben-Länder-/Regionscode für den Ort, aus dem die Ergebnisse stammen sollen, z. B. "US", "JP" oder "FR". Die vollständige Liste finden Sie unter "Unterstützte Regionen ".
location No string - Standortinformationen im lat:<float>;long:<float> Format. Wenn nicht angegeben, verwendet der Dienst Standortinformationen aus der Abfrage.

Anfrage-Header

Feld Typ Description
host string Host für Microsoft AI-APIs: api.microsoft.ai.
x-apikey oder Autorisierung string Ihr API-Schlüssel oder Entra ID Zugriffstoken für die Authentifizierung.
Inhaltstyp string MIME-Typ des Anforderungstexts. Verwenden Sie application/json.

Antwort

Felder mit null oder leeren Zeichenfolgenwerten werden aus der Antwort weggelassen, und Listenfelder können leer ([]) oder nicht vorhanden sein. Behandeln Sie ein nicht vorhandenes Feld als nicht verfügbar und eine leere oder nicht vorhandene Liste, da keine Elemente vorhanden sind. Siehe Verstehen der Antwort.

PlacesResponse

Feld Typ Description
placeResults Array von PlaceResult Liste der Ortsergebnisse.
traceId string Ablaufverfolgungs-ID zum Debuggen und Nachverfolgen.

PlaceResult

Feld Typ Description
name string Der Name des Ortes.
category string Kategorie-Informationen.
phone string Telefonnummer des Kontakts.
businessUrl string Die Geschäfts-URL für den Ort.
location PlaceLocation Standortinformationen
timeZone string Der UTC-Offset des Orts, z. B UTC-08:00 . (8 Stunden hinter UTC, entspricht dem ISO 8601-Offset -08:00).
openHours PlaceOpenHour Öffnungszeiteninformationen.
closureState string Gibt an, ob der Ort dauerhaft oder vorübergehend geschlossen ist.
descriptions Array von PlaceDescription Beschreibungen oder Highlights des Ortes.
passages Array der Passage Liste der Passagen und Links im Zusammenhang mit der Abfrage.
reviews Array von PlaceReview Anbieterbewertungen und individuelle Überprüfungsdetails.
photos Array von PlacePhoto Liste der Fotos.
amenities Array von Strings Annehmlichkeiten, die vom Ort angeboten werden.
actions Array von PlaceAction Aktionen, die dem Ort zugeordnet sind.
socialProfiles Array von PlaceSocialProfile Profile sozialer Medien, die dem Ort zugeordnet sind.

PlaceLocation

Die folgenden Feldnamen sind JSON-Eigenschaftsnamen, die von der API zurückgegeben werden.

Feld Typ Description
addressLine string Adresszeile.
city string Ortsname.
region string Bundesland oder Region.
country string Name des Landes oder der Region.
postalCode string Postleitzahl oder PLZ.
latitude double Breitenkoordinate.
longitude double Längengradkoordinate.

PlaceReview

Feld Typ Description
ratingScore double, optional Aggregierte Bewertungsbewertung zwischen 1 und 5. Wird weggelassen, wenn der Anbieter keine aggregierte Bewertung aufweist.
ratingCount ganze Zahl, optional Anzahl der Bewertungen. Wird weggelassen, wenn der Anbieter keine aggregierte Bewertung aufweist.
reviewDetails Array von PlaceReviewDetail Individuelle Überprüfungsdetails des Anbieters.
providerName string Name des Anbieters.
providerLogo string Logo-URL des Anbieters.
providerUrl string Website-URL des Anbieters.

PlaceReviewDetail

Feld Typ Description
text string Text überprüfen.
score double Bewertungsbewertung. Die Skalierung hängt vom Prüfanbieter ab.

PlacePhoto

Feld Typ Description
url string Foto-URL.
caption string Beschreibung des Fotos.
thumbnailUrl string URL des Miniaturbilds.
providerName string Name des Anbieters.
providerUrl string Website-URL des Anbieters.

PlaceOpenHour

Feld Typ Description
standard map<string, string[]> Karte der standardmäßigen wöchentlichen Offenstundenbereiche nach Tag (mon, , , wedthu, fri, , sat). suntue Jeder Wert ist ein Array von HH:mm-HH:mm Bereichen.
exceptions Array von PlaceOpenHourException Öffnungszeiten oder Schließungen, die an bestimmten Terminen gelten.

PlaceOpenHourException

Feld Typ Description
date string Das Datum, an dem die Ausnahme gilt.
closed boolean Gibt an, ob der Ort am Ausnahmedatum geschlossen ist.
hours Array von Strings Die Öffnungszeitenbereiche, die für das Ausnahmedatum gelten.

PlaceAction

Feld Typ Description
actionType string Der Aktionstyp, der unter der URL verfügbar ist.
url string Die URL zum Ausführen der Aktion.
providerName string Name des Anbieters.
providerLogo string Logo-URL des Anbieters.
providerUrl string Website-URL des Anbieters.

PlaceDescription

Feld Typ Description
text string Eine Beschreibung oder Hervorhebung für den Ort.
providerName string Name des Anbieters.
providerLogo string Logo-URL des Anbieters.
providerUrl string Website-URL des Anbieters.

PlaceSocialProfile

Feld Typ Description
name string Der Name des sozialen Netzwerks oder Profils.
url string Die URL des profils für soziale Netzwerke.
logo string Die URL des Logos des sozialen Profils.

Abschnitt

Feld Typ Description
url string Die URL der Passage.
content string Der Textinhalt der Passage.
crawledAt string Das Datum, an dem die Passage zuletzt durchforstet wurde.

Beispielantwort

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

MCP-Tool

Das McP-Tool "Orte" heißt places. Sie akzeptiert dieselben Parameter wie die REST-API (siehe Parameter) und gibt dasselbe Antwortobjekt in structuredContent. Informationen zum Einrichten finden Sie unter 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
}

Fehlercodes

Statuscode Fehlerkategorie Description Häufige Ursachen
200 Success Die Anfrage war erfolgreich. -
400 Ungültige Anforderung Ungültige Anforderungsparameter. Fehlende erforderliche Felder, ungültige Parameterwerte, falsch formatierter JSON-Code
401 Unauthorized Fehler bei der Authentifizierung oder fehlender Authentifizierung. Ungültiger API-Schlüssel, fehlender x-apikey-Header
403 Verboten Gültige Anmeldeinformationen, aber unzureichende Berechtigungen. Die aufrufende Web IQ AppID ist für Orte nicht aktiviert.
410 Nicht vorhanden (Gone) HTTPS erforderlich. Anforderung über HTTP anstelle von HTTPS
415 Nicht unterstützter Medientyp Der Inhaltstyp wird nicht unterstützt. Fehlender oder falscher Inhaltstypheader
429 Zu viele Anforderungen Das Ratenlimit wurde überschritten. Zu viele Anforderungen im Zeitfenster
500 Interner Serverfehler Server- oder Upstreamdienstfehler. Temporäres Serverproblem, Upstreamdienstfehler oder Timeout

Ausführliche Anleitungen zur Fehlerbehandlung finden Sie unter "Fehlerbehandlung".