REST API başvurusunu yerleştirir

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.

İstek başlıkları

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

MCP aracı

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.