Yakındaki Arama (Yeni)

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ü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:

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ı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 nesnesi ile 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 ş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 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 * değerini kullanın.

  X-Goog-FieldMask: *

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

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

    places.accessibilityOptionsplaces.addressComponentsplaces.adrFormatAddressplaces.attributionsplaces.businessStatusplaces.containingPlacesplaces.displayNameplaces.formattedAddressplaces.googleMapsLinksplaces.googleMapsLinksplaces.googleMapsUriplaces.iconBackgroundColorplaces.iconMaskBaseUriplaces.idplaces.locationplaces.nameplaces.photosplaces.plusCodeplaces.primaryTypeplaces.primaryTypeDisplayNameplaces.pureServiceAreaBusinessplaces.shortFormattedAddressplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport
    
    
    
    ^** places.name alanı, places/PLACE_ID biçiminde kaynak adını içerir. Yerin metin adına erişmek için places.displayName 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.allowsDogsplaces.curbsidePickupplaces.deliveryplaces.dineInplaces.editorialSummaryplaces.evChargeOptionsplaces.fuelOptionsplaces.goodForChildrenplaces.goodForGroupsplaces.goodForWatchingSportsplaces.liveMusicplaces.menuForChildrenplaces.parkingOptionsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.reviewsplaces.routingSummariesplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
    
    

• locationRestriction

  Daire olarak belirtilen, merkez noktası ve yarıçapı metre cinsinden tanımlanan arama bölgesi. Yarıçap, 0,0 ile 50000,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

• 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, kendisiyle ilişkili Tablo A türlerinden 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ürler listesindeki sonuçları filtrelemek için includedTypes ve excludedTypes özelliklerini 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 tür olarak "restaurant" değerini belirtebilirsiniz. Bu durumda yanıt, birincil türü "restaurant" olan yerler içerebilir, ancak yanıt "chinese_restaurant" veya "seafood_restaurant" gibi daha spesifik bir birincil türe sahip yerler 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

  Tablo A'dan 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çeriyor.

  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 A Tablosu'ndaki 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 bölge sakinlerinin okuyabileceği 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.
  • Bir ad, tercih edilen dilde sunulmuyorsa API en yakın eşleşmeyi 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 öğesinden çıkarılır. Bu parametrenin, ülke adını her zaman içeren adrFormatAddress veya 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. 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"
      }
    },
...
}

Birden fazla türde yer bulma

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

Bir yer türünü aramadan hariç tutma

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

1. Sayfanın sağ tarafındaki API simgesini 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 seçin.