Yakındaki Arama (Yeni)

Yakında Arama (Yeni) isteği bir veya daha fazla yer türünü alır ve belirtilen alandaki eşleşen yerlerin bir listesini döndürür. Bir veya daha fazla veri türü belirten bir alan maskesi gereklidir. Yakındaki Arama (Yeni) yalnızca POST isteklerini destekler.

API Explorer, API'yi ve API seçeneklerini tanımanız için canlı isteklerde bulunmanıza olanak tanır:

Deneyin.

Yakındaki Arama (Yeni) istekleri

Yakındaki Arama (Yeni) isteği, aşağıdaki biçimdeki bir URL'ye yapılan HTTP POST isteğidir:

https://places.googleapis.com/v1/places:searchNearby

Tüm parametreleri, JSON istek gövdesinde veya POST isteğinin bir parçası olarak başlıklarda geçirin. Örneğin:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Yakındaki Arama (Yeni) yanıtları

Yakındaki Arama (Yeni) yanıt olarak bir JSON nesnesi döndürür. Yanıtta:

  • places dizisi, eşleşen tüm yerleri içeriyor.
  • Dizideki her yer bir Place nesnesiyle temsil edilir. Place nesnesi, tek bir yer hakkında ayrıntılı bilgiler içerir.
  • İstekte iletilen FieldMask, Place nesnesinde döndürülen alanların listesini belirtir.

JSON nesnesinin tamamı şu biçimdedir:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Gerekli parametreler

  • FieldMask

    Yanıt alanı maskesi oluşturarak yanıtta döndürülecek alanların listesini belirtin. $fields veya fields URL parametresini ya da X-Goog-FieldMask HTTP üst bilgisini kullanarak yanıt alanı maskesini yönteme iletin. Yanıtta döndürülen alanların varsayılan bir listesi yoktur. Alan maskesini çıkarırsanız yöntem bir hata döndürür.

    Alan maskeleme, gereksiz veri isteğinde bulunmadığınızdan emin olmak için iyi bir tasarım uygulamasıdır. Böylece gereksiz işleme süresi ve faturalandırma ücretlerinin önüne geçilir.

    Döndürülecek yer verisi türlerinin virgülle ayrılmış listesini belirtin. Örneğin, görünen adı ve yerin adresini alabilirsiniz.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Tüm alanları almak için * öğesini kullanın.

    X-Goog-FieldMask: *

    Aşağıdaki alanlardan birini veya daha fazlasını belirtin:

    • Aşağıdaki alanlar Yakındaki Arama (Temel) SKU'sunu tetikler:

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, {2, , {2. , {18//}{18//}places.subDestinations alanı {2. alanı, places.subDestinationsplaces.nameplaces.typesplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID Yerin metin adına erişmek için places.displayName öğesini kullanın.

    • Aşağıdaki alanlar Yakındaki Arama (Gelişmiş) SKU'sunu tetikler:

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri

    • Aşağıdaki alanlar Yakındaki Arama (Tercih Edilen) SKU'sunu tetikler:

      places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom places.reservable, places.restroom places.reviews, places.curbsidePickup places.reviews, places.curbsidePickup places.reviewsplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • locationRestriction

    Merkez noktası ve yarıçapla tanımlanan, metre cinsinden daire olarak belirtilmiş, aranacak bölge. Yarıçap 0,0 ile 50000,0 (her ikisi de dahil) arasında olmalıdır. Varsayılan yarıçap 0,0'dır. Bu değeri isteğinizde 0,0'dan büyük bir değere ayarlamanız gerekir.

    Örneğin:

    "locationRestriction": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

İsteğe bağlı parametreler

  • includes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

    Arama sonuçlarını filtrelemek için kullanılan Tablo A türlerinden bir tür listesi belirtebilmenizi sağlar. Her tür kısıtlama kategorisinde en fazla 50 tür belirtilebilir.

    Bir yerin yalnızca kendisiyle ilişkili Tablo A türlerindeki tek bir birincil türü olabilir. Örneğin, birincil tür "mexican_restaurant" veya "steak_house" olabilir. Sonuçları bir yerin birincil türüne göre filtrelemek için includedPrimaryTypes ve excludedPrimaryTypes öğelerini kullanın.

    Bir yerin kendisiyle ilişkili Tablo A türlerinden birden çok tür değeri de olabilir. Örneğin bir restoran şu türlere sahip olabilir: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Bir yerle ilişkili türler listesindeki sonuçları filtrelemek için includedTypes ve excludedTypes kullanın.

    Bir arama birden fazla tür kısıtlamasıyla belirtilirse yalnızca tüm kısıtlamaları karşılayan yerler döndürülür. Örneğin, {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} değerini belirtirseniz döndürülen yerler "restaurant" ile ilgili hizmetler sağlar ancak esasen "steak_house" olarak çalışmaz.

    includedTypes

    A Tablosu'nda aranacak yer türlerinin virgülle ayrılmış listesi. Bu parametre atlanırsa, her türden yer döndürülür.

    excludedTypes

    Aramadan hariç tutmak için A Tablosu'ndaki yer türlerinin virgülle ayrılmış listesi.

    İstekte hem includedTypes ( "school" gibi) hem de excludedTypes ("primary_school" gibi) belirtirseniz yanıt, "school" olarak sınıflandırılan ancak "primary_school" olarak kategorize edilmeyen yerleri içerir. Yanıt, includedTypes öğelerinden en az biriyle ve excludedTypes öğelerinden hiçbiri ile eşleşen yerleri içerir.

    Hem includedTypes hem de excludedTypes içinde görünen bir tür gibi çakışan türler varsa INVALID_REQUEST hatası döndürülür.

    includedPrimaryTypes

    Bir aramaya dahil edilecek birincil yer türlerinin virgülle ayrılmış listesi A'dan.

    excludedPrimaryTypes

    Aramadan hariç tutmak için A Tablosu'ndaki birincil yer türlerinin virgülle ayrılmış listesi.

    Hem includedPrimaryTypes hem de excludedPrimaryTypes içinde görünen bir tür gibi çakışan birincil türler varsa INVALID_ARGUMENT hatası döndürülür.

  • languageCode

    Sonuçların döndürüleceği dil.

    • Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sık sık güncellediğinden bu liste tam olmayabilir.
    • languageCode belirtilmezse API varsayılan olarak en olur. Geçersiz bir dil kodu belirtirseniz API INVALID_ARGUMENT hatası döndürür.
    • API, hem kullanıcı hem de yerel kullanıcılar tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için yerel dildeki açık adresleri, gerektiğinde kullanıcı tarafından okunabilecek bir alfabeye çevrilmiş olarak, tercih edilen dili gözeterek döndürür. Diğer tüm adresler tercih edilen dilde döndürülür. Adres bileşenlerinin tümü, ilk bileşenden seçilen aynı dilde döndürülür.
    • Bir ad, tercih edilen dilde sunulmuyorsa API en yakın eşleşmeyi kullanır.
    • Tercih edilen dilin, API'nin döndürmeyi seçtiği sonuç grubu ve bunların döndürülme sırası üzerinde küçük bir etkisi vardır. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türleri için kısaltmalar veya bir dilde geçerli olup bir başka dilde geçerli olmayan eş anlamlılar.
  • maxResultCount

    Döndürülecek maksimum yer sonucu sayısını belirtir. 1 ile 20 (varsayılan) arasında olmalıdır.

  • rankPreference

    Kullanılacak sıralama türüdür. Bu parametre atlanırsa sonuçlar popülerliğe göre sıralanır. Aşağıdakilerden biri olabilir:

    • POPULARITY (varsayılan) Sonuçları popülerliklerine göre sıralar.
    • DISTANCE Sonuçları, belirtilen konumdan uzaklığına göre artan düzende sıralar.
  • regionCode

    Yanıtı biçimlendirmek için kullanılan, iki karakterli CLDR kodu değeri olarak belirtilen bölge kodu. Varsayılan değer yoktur.

    Yanıttaki formattedAddress alanının ülke adı regionCode ile eşleşirse ülke kodu formattedAddress öğesinden çıkarılır. Bu parametrenin, ülke adını her zaman içeren adrFormatAddress veya hiçbir zaman içermeyen shortFormattedAddress üzerinde etkisi yoktur.

    Çoğu CLDR kodu, bazı önemli istisnalar dışında ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk), ISO 3166-1 kodu ise "gb"'dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallık'ı" için kullanılır). Parametre, geçerli yasalara göre sonuçları etkileyebilir.

Yakındaki Arama (Yeni) örnekleri

Belirli bir türdeki yerleri bulma

Aşağıdaki örnekte, 500 metrelik bir yarıçap içinde bulunan ve circle ile tanımlanan tüm restoranların görünen adları için Yakındaki Arama (Yeni) isteği gösterilmektedir:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

X-Goog-FieldMask üstbilgisinin, yanıtın şu veri alanlarını içerdiğini belirttiğini unutmayın: places.displayName. Ardından yanıt şu biçimdedir:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Ek bilgiler döndürmek için alan maskesine daha fazla veri türü ekleyin. Örneğin, restoran adresini, türünü ve web adresini yanıta eklemek için places.formattedAddress,places.types,places.websiteUri ifadesini ekleyin:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

Yanıt artık şu biçimdedir:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Birden fazla türde yerleri bulma

Aşağıdaki örnekte, belirtilen circle çevresinde 1.000 metre yarıçapındaki tüm market ve içki mağazalarının görünen adları için Yakındaki Arama (Yeni) isteği gösterilmektedir:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
Bu örnekte, alan maskesine places.primaryType ve places.types eklenmiştir. Böylece yanıt, her bir yerle ilgili tür bilgilerini içerecek ve sonuçlar arasından uygun yeri seçmeyi kolaylaştıracaktır.

Aşağıdaki örnekte "school" türündeki tüm yerler için "primary_school" türündeki tüm yerler hariç, sonuçları mesafeye göre sıralayan bir Yakındaki Arama (Yeni) isteği gösterilmektedir:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Mesafeye göre sıralamada, bir bölgenin yakınındaki tüm yerleri arama

Aşağıdaki örnekte, San Francisco şehir merkezinde bir noktanın yakınındaki yerler için bir Yakındaki Arama (Yeni) isteği gösterilmektedir. Bu örnekte, sonuçları mesafeye göre sıralamak için rankPreference parametresini ekliyorsunuz:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Deneyin.

API Explorer, API'yi ve API seçeneklerini tanımanız için örnek isteklerde bulunmanıza olanak tanır.

  1. İsteğe bağlı olarak Standart parametreleri göster'i genişletin ve fields parametresini alan maskesine ayarlayın.
  2. İsteğe bağlı olarak İstek gövdesi'ni düzenleyin.
  3. Yürüt düğmesini seçin. Pop-up pencerede, istekte bulunurken kullanmak istediğiniz hesabı seçin.