Yerleri aramak ve adresler, açılış saatleri, incelemeler ve fotoğraflar gibi yapılandırılmış bilgileri almak için Microsoft Web IQ Yerleri API'sini kullanın.
Uç nokta:POST https://api.microsoft.ai/v3/search/places
Tüm istekler için bir API anahtarı veya Microsoft Entra ID erişim belirteci gerekir. Kurulum yönergeleri için bkz. Kimlik doğrulaması .
Numune isteği
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
| Parametre |
Required |
Type |
Default |
Description |
query |
Yes |
string |
- |
Yerler için arama sorgusu, örneğin, popular restaurants in Seattle, WA. Uzunluk üst sınırı 1000 karakterdir. |
maxResults |
Hayır |
integer |
10 |
Döndürülecek en fazla sonuç sayısı. 1 ile 10 arasında olmalıdır; aralık dışı değerler doğrulama hatası döndürür. Atlandı veya null 10 kullanır. Daha az yer olduğunda daha az sonuç döndürülebilir. |
language |
Hayır |
string |
"en" |
Arama sonuçlarında arabirim dili için 2 harfli ISO 639-1 dil kodu. Tam liste için desteklenen diller bölümüne bakın. |
region |
Hayır |
string |
"US" |
Sonuçların nereden gelmesi gerektiği için 2 harfli bir ülke/bölge kodu, örneğin, "US", "JP" veya "FR". Tam liste için bkz. Desteklenen bölgeler . |
location |
Hayır |
string |
- |
Konum bilgileri biçimindedir lat:<float>;long:<float> . Belirtilmezse, hizmet sorgudaki konum bilgilerini kullanır. |
| Alan |
Type |
Description |
| host |
string |
Microsoft AI API'leri için konak: api.microsoft.ai. |
| x-apikey veya Yetkilendirme |
string |
Kimlik doğrulaması için API anahtarınız veya Entra ID erişim belirteciniz. |
| içerik türü |
string |
İstek gövdesinin MIME türü.
application/json adresini kullanın. |
Response
Dize değerleri veya boş olan null alanlar yanıttan atlanır ve liste alanları boş ([]) veya eksik olabilir. Eksik bir alanı kullanılamıyor ve boş veya eksik bir liste öğe içermiyor olarak değerlendirin. Bkz. Yanıtı anlama.
PlacesResponse
| Alan |
Type |
Description |
placeResults |
PlaceResult dizisi |
Yer sonuçlarının listesi. |
traceId |
string |
Hata ayıklama ve izleme için izleme kimliği. |
PlaceResult
| Alan |
Type |
Description |
name |
string |
Yerin adı. |
category |
string |
Kategori bilgisi. |
phone |
string |
İletişim telefon numarası. |
businessUrl |
string |
Yer için iş URL'si. |
location |
PlaceLocation |
Konum bilgileri. |
timeZone |
string |
Örneğin, yerin UTC uzaklığı UTC-08:00 (ISO 8601 uzaklığıyla -08:00eşdeğer, UTC'nin 8 saat gerisinde). |
openHours |
PlaceOpenHour |
Açılış saatleri bilgileri. |
closureState |
string |
Yerin kalıcı olarak mı yoksa geçici olarak mı kapatılıp kapatılamadığını gösterir. |
descriptions |
PlaceDescription dizisi |
Yerin açıklamaları veya vurguları. |
passages |
Passage dizisi |
Sorguyla ilgili bölümlerin ve bağlantıların listesi. |
reviews |
PlaceReview dizisi |
Sağlayıcı derecelendirmeleri ve bireysel gözden geçirme ayrıntıları. |
photos |
PlacePhoto dizisi |
Fotoğraf listesi. |
amenities |
dize dizisi |
Yer tarafından sunulan olanaklar. |
actions |
PlaceAction dizisi |
Yerle ilişkili eylemler. |
socialProfiles |
PlaceSocialProfile dizisi |
Yerle ilişkili sosyal medya profilleri. |
PlaceLocation
Aşağıdaki alan adları API tarafından döndürülen JSON özellik adlarıdır.
| Alan |
Type |
Description |
addressLine |
string |
Adres satırı. |
city |
string |
Şehir adı. |
region |
string |
Durum veya bölge. |
country |
string |
Ülke veya bölge adı. |
postalCode |
string |
Posta veya posta kodu. |
latitude |
double |
Enlem koordinatı. |
longitude |
double |
Boylam koordinatı. |
PlaceReview
| Alan |
Type |
Description |
ratingScore |
double, isteğe bağlı |
1 ile 5 arasında değişen toplu derecelendirme puanı. Sağlayıcının toplam derecelendirmesi olmadığında atlanır. |
ratingCount |
integer, isteğe bağlı |
Derecelendirme sayısı. Sağlayıcının toplam derecelendirmesi olmadığında atlanır. |
reviewDetails |
PlaceReviewDetail dizisi |
Sağlayıcıdan tek tek gözden geçirme ayrıntıları. |
providerName |
string |
Sağlayıcının adı. |
providerLogo |
string |
Sağlayıcının logo URL'si. |
providerUrl |
string |
Sağlayıcının web sitesi URL'si. |
PlaceReviewDetail
| Alan |
Type |
Description |
text |
string |
Metni gözden geçirin. |
score |
double |
Puanı gözden geçirin. Ölçek, gözden geçirme sağlayıcısına bağlıdır. |
PlacePhoto
| Alan |
Type |
Description |
url |
string |
Fotoğraf URL'si. |
caption |
string |
Fotoğrafın açıklaması. |
thumbnailUrl |
string |
Küçük resim resmi URL'si. |
providerName |
string |
Sağlayıcının adı. |
providerUrl |
string |
Sağlayıcının web sitesi URL'si. |
PlaceOpenHour
| Alan |
Type |
Description |
standard |
map<string, string[]> |
Güne (mon, , tue, , thuwed, fri, , sat, ) sungöre anahtarlanmış standart haftalık açık saat aralıklarının haritası. Her değer bir aralık dizisidir HH:mm-HH:mm . |
exceptions |
PlaceOpenHourException dizisi |
Belirli tarihlerde geçerli olan açılış saatleri veya kapanışlar. |
PlaceOpenHourException
| Alan |
Type |
Description |
date |
string |
Özel durumun geçerli olduğu tarih. |
closed |
boolean |
Özel durum tarihinde yerin kapalı olup olmadığı. |
hours |
dize dizisi |
Özel durum tarihinde geçerli olan açılış saati aralıkları. |
PlaceAction
| Alan |
Type |
Description |
actionType |
string |
URL'de kullanılabilen eylem türü. |
url |
string |
Eylemi gerçekleştirmek için URL. |
providerName |
string |
Sağlayıcının adı. |
providerLogo |
string |
Sağlayıcının logo URL'si. |
providerUrl |
string |
Sağlayıcının web sitesi URL'si. |
PlaceDescription
| Alan |
Type |
Description |
text |
string |
Yer için bir açıklama veya vurgu. |
providerName |
string |
Sağlayıcının adı. |
providerLogo |
string |
Sağlayıcının logo URL'si. |
providerUrl |
string |
Sağlayıcının web sitesi URL'si. |
PlaceSocialProfile
| Alan |
Type |
Description |
name |
string |
Sosyal ağın veya profilin adı. |
url |
string |
Sosyal profilin URL'si. |
logo |
string |
Sosyal profil logosunun URL'si. |
Pasaj
| Alan |
Type |
Description |
url |
string |
Geçişin URL'si. |
content |
string |
Metnin içeriği. |
crawledAt |
string |
Geçişin en son gezinildiği tarih. |
Örnek yanıt
{
"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"
}
Yerler MCP aracı olarak adlandırılır places. REST API ile aynı parametreleri kabul eder (bkz . Parametreler) ve içinde structuredContentaynı yanıt nesnesini döndürür. Kurulum için bkz. 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
}
Hata kodları
| Durum Kodu |
Hata Kategorisi |
Description |
Olası Nedenler |
| 200 |
Success |
İstek başarılı oldu. |
- |
| 400 |
Hatalı İstek |
Geçersiz istek parametreleri. |
Eksik gerekli alanlar, geçersiz parametre değerleri, hatalı biçimlendirilmiş JSON |
| 401 |
Yetkisiz |
Kimlik doğrulaması başarısız oldu veya eksik. |
Geçersiz API anahtarı, eksik x-apikey üst bilgisi |
| 403 |
Yasak |
Geçerli kimlik bilgileri ancak izinler yetersiz. |
Çağrı yapan Web IQ AppID, Yerler için etkin değil |
| 410 |
Gitti |
HTTPS gereklidir. |
İSTEK HTTPS yerine HTTP üzerinden yapıldı |
| 415 |
Desteklenmeyen Medya Türü |
İçerik türü desteklenmiyor. |
Eksik veya yanlış içerik türü üst bilgisi |
| 429 |
Çok Fazla İstek Var |
Hız sınırı aşıldı. |
Zaman penceresinde çok fazla istek var |
| 500 |
İç Sunucu Hatası |
Sunucu veya yukarı akış hizmeti hatası. |
Geçici sunucu sorunu, yukarı akış hizmeti hatası veya zaman aşımı |
Ayrıntılı hata işleme kılavuzu için bkz. Hata işleme.
İlgili içerik