Yakındaki Arama (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

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

API Gezgini, API'ye ve API seçeneklerine aşina olabilmeniz için canlı istek göndermenize olanak tanır:

Deneyin.

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

Yakında Arama (Yeni) istekleri

Yakındakiler araması (yeni) isteği, aşağıdaki biçimdeki bir URL'ye gönderilen bir 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 üstbilgilerde 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ında 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 nesnesi ile temsil edilir. Place nesnesi, tek bir yerle ilgili ayrıntılı bilgileri içerir.
  • İstekte iletilen FieldMask, Place nesnesinde döndürülen alanların listesini belirtir.

JSON nesnesinin tamamı şu şekildedir:

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

Gerekli parametreler

  • FieldMask

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

    Alan maskeleme, gereksiz veri istememenizi sağlayan iyi bir tasarım uygulamasıdır. Bu uygulama, gereksiz işlem süresinden ve faturalandırma ücretlerinden kaçınmanıza yardımcı olur.

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

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

    Tüm alanları almak için * değerini kullanın.

    X-Goog-FieldMask: *

    Aşağıdaki alanlardan en az birini belirtin:

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

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport

      * places.googleMapsLinks alanı GA öncesi önizleme aşamasındadır ve önizleme sırasında kullanım için ücret alınmaz. Yani faturalandırma 0 ABD dolarıdır.

      ** places.name alanı, places/PLACE_ID biçiminde kaynak adını içerir. Yerin metin adına erişmek için places.displayName seçeneğini kullanın.

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

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, 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.routingSummaries,* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout

      * Yalnızca metin arama ve yakınlarda arama

  • locationRestriction

    Merkez noktası ve yarıçapı metre cinsinden tanımlanan, daire olarak belirtilen arama bölgesi. Yarıçap 0,0 ile 50000,0 arasında (bu değerler dahil) 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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

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

    Bir mekan, ilişkili Tablo A türleri arasından yalnızca tek bir birincil türe sahip 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 değerlerini kullanın.

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

    "restaurant" veya "hotel" gibi genel bir birincil tür belirttiğinizde yanıt, belirtilenden daha spesifik bir birincil türe sahip yerler içerebilir. Örneğin, birincil "restaurant" türünü eklemeyi belirtirsiniz. Yanıt, birincil türü "restaurant" olan yerleri içerebilir ancak "chinese_restaurant" veya "seafood_restaurant" gibi daha spesifik birincil türe sahip yerleri de içerebilir.

    Birden fazla tür kısıtlaması içeren bir arama yapılırsa 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 sunar ancak birincil olarak "steak_house" olarak faaliyet göstermez.

    includedTypes

    A Tablosu'ndaki aranacak yer türlerinin virgülle ayrılmış listesi. Bu parametre atlanırsa tüm türde yerler döndürülür.

    excludedTypes

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

    İstekte hem includedTypes ( ör. "school") hem de excludedTypes (ör. "primary_school") parametresini belirtirseniz yanıt, "school" olarak sınıflandırılan ancak "primary_school" olarak sınıflandırılmayan yerleri içerir. Yanıt, includedTypes ile en az bir, excludedTypes ile ise hiçbir eşleşmeyen yerleri içerir.

    Hem includedTypes hem de excludedTypes'te görünen bir tür gibi çelişen tür varsa 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'te görünen bir tür gibi birbiriyle çelişen 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 sağlanmazsa API varsayılan olarak en değerini kullanır. Geçersiz bir dil kodu belirtirseniz API INVALID_ARGUMENT hatası döndürür.
    • API, hem kullanıcı hem de yerel halk tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için sokak adreslerini yerel dilde döndürür. Gerekirse tercih edilen dile göre, kullanıcı tarafından okunabilir bir yazım sistemine dönüştürülü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.
    • Tercih edilen dilde bulunmayan bir ad varsa API en yakın eşlemeyi kullanır.
    • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç grubu ve bu sonuçların döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlayıcı, kısaltmaları dile göre farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları veya bir dilde geçerli olup başka bir 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ü. 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 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 değer yoktur.

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

    CLDR kodlarının çoğu, 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) iken ISO 3166-1 kodu "gb"dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" tüzel kişiliği için). Parametre, geçerli yasaya göre sonuçları etkileyebilir.

Yakında Arama (Yeni) örnekleri

Aynı türden yerleri bulma

Aşağıdaki örnekte, circle tarafından tanımlanan 500 metre yarıçapındaki tüm restoranların görünen adları için 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 başlığının, yanıtın aşağıdaki veri alanlarını içerdiğini belirttiğini unutmayın: places.displayName. Yanıt şu şekildedir:

{
  "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 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 formdadır:

{
  "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 yer bulma

Aşağıdaki örnekte, belirtilen circle noktasının 1.000 metre yarıçapındaki tüm marketlerin ve içki mağazalarının görünen adları için bir Yakındakileri Ara (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, yanıtın her yerle ilgili tür bilgilerini içermesi için alan maskesine places.primaryType ve places.types eklenmiştir. Bu sayede, sonuçlardan uygun yeri seçmek daha kolay olur.

Aşağıdaki örnekte, "primary_school" türündeki tüm yerler hariç "school" türündeki tüm yerler için bir Yakındakiler Arama (Yeni) isteği gösterilmektedir. Sonuçlar mesafeye göre sıralanı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 mesafeye göre sıralayarak arama

Aşağıdaki örnekte, San Francisco şehir merkezindeki bir noktanın yakınındaki yerler için Yakındakileri Ara (Yeni) isteği gösterilmektedir. Bu örnekte, sonuçları uzaklığa 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'ye ve API seçeneklerine aşina olabilmeniz için örnek istekler göndermenize 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'i genişletin ve fields parametresini alan maskesine ayarlayın.
  3. İsteğe bağlı olarak İstek gövdesini düzenleyin.
  4. Yürüt düğmesini seçin. Pop-up'ta, isteği göndermek için kullanmak istediğiniz hesabı seçin.

  5. API Gezgini panelinde, API Gezgini penceresini genişletmek için genişlet simgesini API Gezgini'ni genişletin. seçin.