Yakındaki Arama (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

Yakında Arama (Yeni) isteği bir veya daha fazla yer türü alır ve belirtilen bölgedeki 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 ve API seçenekleri hakkında bilgi edinebilmeniz için canlı istekler yapmanıza olanak tanır:

Deneyin.

Yakındaki Arama (Yeni) sonuçlarını haritada görmek için etkileşimli demoyu deneyin.

Yakındaki Arama (Yeni) istekleri

Yakındaki Arama (Yeni) isteği, formdaki bir URL'ye yapılan HTTP POST isteğidir:

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

JSON isteği gövdesindeki veya başlıklardaki tüm parametreleri, POST isteğinin bir parçası olarak iletin. Ö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çerir.
  • 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ı aşağıdaki 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 varsayılan bir döndürülen alan listesi yok. Alan maskesini çıkarırsanız yöntem 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. Bu da gereksiz işleme süresi ve faturalandırma ücretlerinin önlenmesine yardımcı olur.

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

    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.attributions, 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 içinde places.primaryTypeDisplayName, places.subDestinations, places.subDestinations, places.subDestinations, places.subDestinations biçiminde places.subDestinations, places.subDestinations, places.subDestinations, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location places.nameplaces.typesplaces.utcOffsetMinutesplaces.viewport

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

    • Aşağıdaki alanlar Yakında 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.reviews, places.servesBeer, places.servesBrunch, {29, places.servesBeer, places.servesBeerplaces.servesBreakfastplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • locationRestriction

    Merkez noktası ve metre cinsinden yarıçapla tanımlanan, çember şeklinde belirtilen, aranacak bölge. Yarıçap, 0,0 ile 50.000,0 (her ikisi de dahil) arasında olmalıdır. Varsayılan yarıçap 0,0'dır. İsteğinizde bu değeri 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

  • includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

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

    Bir yerin kendisiyle ilişkili tek bir birincil türü olabilir Tablo A. Ö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 özelliklerini kullanın.

    Bir yer, kendisiyle ilişkili Tablo A türlerinden birden fazla tür değere sahip 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 özelliklerini kullanın.

    Bir arama birden çok 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"]} özelliğini belirtirseniz döndürülen yerler "restaurant" ile ilgili hizmetler sağlar ancak birincil olarak "steak_house" olarak çalışmaz.

    includedTypes

    Tablo A'dan aranacak yer türlerinin virgülle ayrılmış listesi. Bu parametre eklenmezse her türden yer döndürülür.

    excludedTypes

    Aramadan hariç tutulacak Tablo A'daki yer türlerinin virgülle ayrılmış listesi.

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

    Çakışan türler varsa (ör. hem includedTypes hem de excludedTypes'da görünen bir tür) INVALID_REQUEST hatası döndürülür.

    includedPrimaryTypes

    Aramaya dahil edilecek Tablo A'daki birincil yer türlerinin virgülle ayrılmış listesi.

    excludedPrimaryTypes

    Aramadan hariç tutulacak Tablo A'daki 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 kapsamlı olmayabilir.
    • languageCode sağlanmazsa 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 bölge sakinlerinin okuyabileceği bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için yerel dildeki açık adresleri, gerekirse kullanıcı tarafından okunabilecek bir alfabeye dönüştürülerek tercih edilen dile uyarlar. 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ç kümesi ve 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ürlerinin kısaltmaları ya da bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlı kelimeler olabilir.

  • maxResultCount

    Döndürülecek maksimum yer sonucu sayısını belirtir. 1-20 (varsayılan) dahil bu değerler arasında olmalıdır.

  • rankPreference

    Kullanılacak sıralama türü. Bu parametre eklenmezse 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 konuma olan mesafelerine göre artan düzende sıralar.

  • regionCode

    Yanıtı biçimlendirmek için kullanılan bölge kodu. İki karakterli CLDR kodu değeri olarak belirtilir. Varsayılan bir değer yok.

    Yanıttaki formattedAddress alanının ülke adı regionCode ile eşleşirse ülke kodu formattedAddress öğesinden çıkarılır. Bu parametrenin, her zaman ülke adını 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 "gb" (teknik olarak "Büyük Britanya ve Kuzey İrlanda'daki Birleşik Krallık'a" ait tüzel kişi için) "gb" şeklindedir. Parametre, geçerli yasalara göre sonuçları etkileyebilir.

Yakındaki Arama (Yeni) örnekleri

Belirli türdeki yerleri bulma

Aşağıdaki örnekte, 500 metrelik yarıçap içindeki tüm restoranların görünen adları için circle tarafından tanımlanan bir 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. Bu durumda yanıt şu biçimde olur:

{
  "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, yanıta restoranın adresini, türünü ve web adresini dahil etmek için places.formattedAddress,places.types,places.websiteUri 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çimde:

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

Farklı türde yerler bulun

Aşağıdaki örnekte, belirtilen circle bölgesinin 1.000 metrelik yarıçapı dahilindeki tüm marketlerin ve içki mağazalarının görünen adları için Yakınlarda 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 eklenerek yanıtın her bir yer hakkında tür bilgisi içermesi, sonuçlardan uygun yerin seçilmesini kolaylaştırır.

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

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

Bir bölgenin yakınındaki tüm yerleri arama (mesafeye göre sıralama)

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

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 Gezgini, API ve API seçeneklerini tanıyabilmeniz için örnek isteklerde bulunmanıza olanak tanır.

  1. Sayfanın sağ tarafındaki API simgesini (API Gezgini'ni genişletin.) seçin.
  2. İsteğe bağlı olarak Standart parametreleri göster seçeneğini genişletin ve fields parametresini alan maskesi olarak ayarlayın.
  3. İsteğe bağlı olarak İstek gövdesini düzenleyin.
  4. Yürüt düğmesini seçin. Pop-up pencerede, istekte bulunmak için kullanmak istediğiniz hesabı seçin.

  5. API Gezgini panelinde genişletme simgesini (API Gezgini'ni genişletin.) seçerek API Gezgini penceresini genişletin.