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. |
| 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"
}
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".
Verwandte Inhalte