Metin Arama (Yeni)

Platform seçin: Android iOS JavaScript Web Hizmeti

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler

Giriş

Text Search (New), bir dizeye (ör. "New York'ta pizza", "Ottawa yakınlarındaki ayakkabı mağazaları" veya "123 Main Street") dayalı olarak bir dizi yer hakkında bilgi döndürür. Hizmet, metin dizesiyle ve ayarlanmış konum tercihiyle eşleşen yerlerin listesini döndürür.

Text Search (New), zorunlu parametrelerin yanı sıra daha iyi sonuçlar için isteğe bağlı parametreleri kullanarak sorguları hassaslaştırmayı destekler.

API Gezgini, API ve API seçeneklerini tanıyabilmeniz için canlı istekler göndermenize olanak tanır:

Text Search (New) istekleri

Text Search (New) isteği, aşağıdaki biçimde bir HTTP POST isteğidir:

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

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

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Text Search (New) yanıtları

Text Search (New), 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ı bilgi içerir.
  • İstekte iletilen FieldMask, Place nesnesinde döndürülen alanların listesini belirtir.
  • Döndürülen yer listesinin aynı istekler için tutarlı olacağı garanti edilmez.

JSON nesnesinin tamamı şu biçimdedir:

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

Gerekli parametreler

  • FieldMask

    Bir 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 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 sayede gereksiz işlem süresinden ve faturalandırma ücretlerinden kaçınabilirsiniz.

    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 * kullanın.

    X-Goog-FieldMask: *

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

    • Aşağıdaki alanlar Text Search Essentials ID Only SKU'yu tetikler:

      places.attributions
      places.id
      places.consumerAlert
      places.name*
      nextPageToken
      places.movedPlace
      places.movedPlaceId

      * places.name alanı, yer kaynak adını şu biçimde içerir: places/PLACE_ID. Yerin metin adına erişmek için Pro SKU'da places.displayName kullanın.

      Alanların ve ilişkili SKU'larının tam listesi için Yer Verileri Alanları (Yeni) başlıklı makaleyi inceleyin.

    • Aşağıdaki alanlar Text Search Pro SKU'sunu tetikler:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks
      places.googleMapsTypeLabel
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.location
      places.openingDate
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.searchUri
      places.subDestinations
      places.timeZone
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Adres tanımlayıcılar Hindistan'daki müşteriler için genel kullanıma sunulmuştur ve diğer ülkelerde deneme aşamasındadır.

      Alanların ve ilişkili SKU'larının tam listesi için Yer Verileri Alanları (Yeni) başlıklı makaleyi inceleyin.

    • Aşağıdaki alanlar Text Search Enterprise SKU'sunu tetikler:

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

      Alanların ve ilişkili SKU'larının tam listesi için Yer Verileri Alanları (Yeni) başlıklı makaleyi inceleyin.

    • Aşağıdaki alanlar Text Search Enterprise + Atmosphere SKU'sunu tetikler:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      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ında Arama

      Alanların ve ilişkili SKU'larının tam listesi için Yer Verileri Alanları (Yeni) başlıklı makaleyi inceleyin.

  • textQuery

    Aranacak metin dizesi. Örneğin, "restoran", "123 Main Street" veya "San Francisco'da ziyaret edilecek en iyi yer". API, bu dizeye göre eşleşme adaylarını döndürür ve sonuçları algılanan alaka düzeylerine göre sıralar.

    Text Search (New), aşağıdakiler de dahil olmak üzere belirsiz sorgular için tasarlanmamıştır:

    Sorgu türü Örnek
    Tek bir sorguda birden fazla yer, yol veya şehir adı gibi çok fazla kavram ya da kısıtlama "Market Street San Francisco San Jose Airport"
    Google Haritalar'da gösterilmeyen posta adresi öğeleri "C/O John Smith 123 Main Street"
    "P.O. Box 13 San Francisco"
    İşletme, zincir veya kategorilerin, bu varlıkların bulunmadığı konumlarla birleştirilmiş adları "Dallas, Teksas yakınlarındaki Tesco"
    Birden fazla yorumu olan belirsiz sorgular "Şarj cihazı bırakma"
    Artık kullanılmayan eski adlar "Middlesex Birleşik Krallık"
    Coğrafi olmayan öğeler veya niyet "Ventura Limanı'nda kaç tekne var?"
    Resmi olmayan veya özel adlar "The Jenga"
    "The Helter Skelter"
    Enlem ve boylam koordinatları "37.422131,-122.084801"

İsteğe bağlı parametreler

  • includeFutureOpeningBusinesses

    true ise gelecekte açılması beklenen işletmeleri döndürür. Varsayılan değer: false.

    İşletme durumunu almak için istek alan maskenize places.businessStatus değerini ekleyin. İşletmenin beklenen açılış tarihini almak için istek alan maskenize places.openingDate değerini ekleyin.

  • includedType

    Sonuçları, Tablo A'da tanımlanan belirtilen türle eşleşen yerlere yönlendirir. Yalnızca bir tür belirtebilirsiniz. Örneğin:

    • "includedType":"bar"
    • "includedType":"pharmacy"

    Text Search (New), uygulanabilirliğe bağlı olarak belirli sorgular için tür filtreleme uygular. Örneğin, belirli adreslere yönelik sorgulara ("123 Main Street") tür filtreleme uygulanmayabilir ancak kategorik sorgulara ("yakındaki mağazalar" veya "alışveriş merkezleri") neredeyse her zaman tür filtreleme uygulanır.

    Tür filtrelemeyi tüm sorgulara uygulamak için strictTypeFiltering değerini true olarak ayarlayın.

  • includePureServiceAreaBusinesses

    true olarak ayarlanırsa yanıt, müşterileri doğrudan ziyaret eden veya onlara teslimat yapan ancak fiziksel bir işletme konumu olmayan işletmeleri içerir. false olarak ayarlanırsa API yalnızca fiziksel işletme konumu olan işletmeleri döndürü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 kapsamlı 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 amaca ulaşmak için açık adresleri yerel dilde döndürür ve gerekirse tercih edilen dili dikkate alarak kullanıcı tarafından okunabilir bir alfabeye dönüştü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 dilde döndürülür.
    • Tercih edilen dilde bir ad yoksa API en yakın eşleşmeyi kullanır.
    • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi 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ı kelimeler buna dahildir.

  • locationBias

    Arama yapılacak alanı belirtir. Bu konum, bir ön yargı görevi görür. Yani belirtilen konumun çevresindeki sonuçlar (belirtilen alanın dışındaki sonuçlar dahil) döndürülebilir.

    locationRestriction veya locationBias değerini belirtebilirsiniz ancak ikisini birden belirtemezsiniz. locationRestriction, sonuçların içinde olması gereken bölgeyi belirtir. locationBias ise sonuçların muhtemelen içinde veya yakınında olacağı ancak dışında da olabileceği bölgeyi belirtir.

    Bölgeyi dikdörtgen görüntü alanı veya daire olarak belirtin.

    • Daire, merkez noktası ve metre cinsinden yarıçap ile tanımlanır. Yarıçap, 0,0 ile 50.000,0 arasında (bu değerler dahil) olmalıdır. Varsayılan yarıçap 0,0'dır. Örneğin:

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

    • Dikdörtgen, çapraz olarak karşılıklı iki alt ve üst nokta olarak temsil edilen bir enlem-boylam görüntü alanıdır. Düşük nokta, dikdörtgenin güneybatı köşesini, yüksek nokta ise dikdörtgenin kuzeydoğu köşesini temsil eder.

      Görüntü alanı, kapalı bir bölge olarak kabul edilir. Yani sınırını da içerir. Enlem sınırları -90 ile 90 derece arasında (bu değerler dahil), boylam sınırları ise -180 ile 180 derece arasında (bu değerler dahil) olmalıdır:

      • low = high ise görüntü alanı bu tek noktadan oluşur.
      • low.longitude > high.longitude ise boylam aralığı ters çevrilir (görüntü alanı 180 derece boylam çizgisini geçer).
      • low.longitude = -180 derece ve high.longitude = 180 derece ise görüntü alanı tüm boylamları içerir.
      • low.longitude = 180 derece ve high.longitude = -180 derece ise boylam aralığı boştur.
      • low.latitude > high.latitude ise enlem aralığı boştur.

      Hem düşük hem de yüksek değerler doldurulmalıdır ve temsil edilen kutu boş olamaz. Boş bir görüntü alanı hataya neden olur.

      Örneğin, bu görüntü alanı New York'u tamamen kapsar:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    Yalnızca kategorik sorgular için aranacak bir alan belirtir. Bu sorgular birden fazla yer döndürebilir (ör. "New York'taki restoranlar" veya "Alışveriş merkezleri"). Belirtilen alanın dışındaki sonuçlar döndürülmez.

    Bölgeyi dikdörtgen bir görüntü alanı olarak belirtin. Görüntü alanını tanımlama örneği için locationBias açıklamasına bakın.

    locationRestriction veya locationBias değerini belirtebilirsiniz ancak ikisini birden belirtemezsiniz. locationRestriction, sonuçların içinde olması gereken bölgeyi belirtir. locationBias ise sonuçların muhtemelen içinde veya yakınında olacağı ancak dışında da olabileceği bölgeyi belirtir.

  • evOptions

    Mevcut elektrikli araç şarj konnektörlerini ve şarj hızlarını tanımlamak için parametreleri belirtir.

    • connectorTypes

      Bir yerde bulunan elektrikli araç şarj konnektörü türüne göre filtreler. Konnektör türlerinden hiçbirini desteklemeyen yerler filtrelenir. Desteklenen EV şarj konnektörü türleri arasında birleşik (AC ve DC) EV şarj üniteleri, Tesla EV şarj üniteleri, GB/T uyumlu EV şarj üniteleri (Çin'de EV hızlı şarjı için) ve duvar prizi EV şarj üniteleri bulunur. Daha fazla bilgi için referans belgelerini inceleyin.

      • Sonuçları desteklenen belirli bir bağlayıcıya göre filtrelemek için connectorTypes değerini bu değere ayarlayın. Örneğin, J1772 tip 1 konnektörleri bulmak için connectorTypes değerini EV_CONNECTOR_TYPE_J1772 olarak ayarlayın.
      • Desteklenmeyen bağlayıcıların sonuçlarını filtrelemek için connectorTypes değerini EV_CONNECTOR_TYPE_OTHER olarak ayarlayın.
      • Sonuçları duvar prizi olan tüm konnektör türlerine göre filtrelemek için connectorTypes değerini EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET olarak ayarlayın.
      • Herhangi bir bağlayıcı türü için sonuçları filtrelemek istiyorsanız connectorTypes değerini EV_CONNECTOR_TYPE_UNSPECIFIED olarak ayarlayın veya connectorTypes için bir değer ayarlamayın.

    • minimumChargingRateKw

      Yerleri, kilovat (kW) cinsinden minimum EV şarj hızıyla filtreler. Şarj hızı, minimum şarj hızından düşük olan yerler filtrelenir. Örneğin, şarj hızı en az 10 kW olan EV şarj cihazlarını bulmak için bu parametreyi "10" olarak ayarlayabilirsiniz.

  • minRating

    Sonuçları, yalnızca ortalama kullanıcı puanı bu sınıra eşit veya bu sınırdan yüksek olanlarla kısıtlar. Değerler 0,0 ile 5,0 (başlangıç ve bitiş değerleri dahil) arasında olmalı ve 0,5'lik artışlarla yükselmelidir. Örneğin: 0, 0,5, 1,0, ... , 5,0 dahil. Değerler en yakın 0,5 değerine yuvarlanır. Örneğin, 0,6 değeri, derecelendirmesi 1,0'dan düşük olan tüm sonuçları eler.

  • openNow

    true ise yalnızca sorgunun gönderildiği sırada açık olan yerleri döndürür. false ise açık durumuna bakılmaksızın tüm işletmeleri döndür. Bu parametreyi false olarak ayarlarsanız Google Places veritabanında çalışma saatleri belirtilmeyen yerler döndürülür.

  • pageSize

    Her sayfada gösterilecek sonuç sayısını (1 ile 20 arasında) belirtir. Örneğin, pageSize değerini 5 olarak ayarlarsanız ilk sayfada en fazla 5 sonuç döndürülür. Sorgu daha fazla sonuç döndürebiliyorsa yanıt, sonraki sayfaya erişmek için sonraki bir istekte iletebileceğiniz bir nextPageToken içerir.

    Bu alan, desteği sonlandırılan maxResultCount alanının yerini alır. Hem pageSize hem de maxResultCount değerini belirtirseniz API, pageSize değerini kullanır ve maxResultCount değerini yoksayar.

  • pageToken

    Önceki sayfanın yanıt gövdesindeki nextPageToken değerini belirtir.

  • priceLevels

    Aramayı belirli fiyat seviyeleriyle işaretlenmiş yerlerle kısıtlayın. Varsayılan olarak tüm fiyat seviyeleri seçilir.

    Fiyat seviyeleri, aşağıdaki türlerdeki yerler için beklenebilir:

    priceLevels belirtilirse desteklenmeyen türdeki yerler yanıta dahil edilmez.

    PriceLevel tarafından tanımlanan bir veya daha fazla değerden oluşan bir dizi belirtin.

    Örneğin:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • rankPreference

    Sorgu türüne göre yanıttaki sonuçların nasıl sıralanacağını belirtir:

    • "New York'taki restoranlar" gibi kategorik bir sorgu için varsayılan değer RELEVANCE (sonuçları arama alaka düzeyine göre sırala) şeklindedir. rankPreference değerini RELEVANCE veya DISTANCE (sonuçları mesafeye göre sırala) olarak ayarlayabilirsiniz.
    • "Mountain View, CA" gibi kategorik olmayan bir sorgu için rankPreference parametresini ayarlamamanızı öneririz.

  • regionCode

    Yanıtı biçimlendirmek için kullanılan bölge kodu. İki karakterli CLDR kodu değeri olarak belirtilir. Bu parametre, arama sonuçları üzerinde yanlılık etkisi de gösterebilir. Varsayılan değer yoktur.

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

    Çoğu CLDR kodu, ISO 3166-1 kodlarıyla aynıdır ancak bazı önemli istisnalar vardı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.

  • strictTypeFiltering

    includedType parametresiyle kullanılır. true olarak ayarlandığında, yalnızca includedType tarafından belirtilen türlerle eşleşen yerler döndürülür. Varsayılan değer olan false olduğunda yanıt, belirtilen türlerle eşleşmeyen yerler içerebilir.

Text Search (New) örnekleri

Sorgu dizesine göre yer bulma

Aşağıdaki örnekte, "Sidney, Avustralya'da baharatlı vejetaryen yemekleri" için bir Text Search (Yeni) isteği gösterilmektedir:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

X-Goog-FieldMask başlığının, yanıtın şu veri alanlarını içerdiğini belirttiğini unutmayın: places.displayName,places.formattedAddress. Yanıt şu biçimde olur:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

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

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-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:searchText'

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

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Yerler fiyat düzeyine göre filtrelenir.

Sonuçları ucuz veya orta fiyatlı olarak tanımlanan restoranlara göre filtrelemek için priceLevel seçeneğini kullanın:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Bu örnekte, places.priceLevel veri alanını response'a eklemek için X-Goog-FieldMask başlığı da kullanılmıştır. Bu nedenle, şu biçimdedir:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Aramanızı hassaslaştırmak için includedType, minRating, rankPreference, openNow ve İsteğe bağlı parametreler bölümünde açıklanan diğer parametreler gibi ek seçenekler ekleyin.

Aramayı belirli bir alanla kısıtlama

Aramayı bir alanla kısıtlamak için locationRestriction veya locationBias kullanın ancak ikisini birden kullanmayın. locationRestriction parametresini, sonuçların içinde olması gereken bölgeyi belirtmek için, locationBias parametresini ise sonuçların yakınında olması gereken ancak bölgenin dışında olabileceği bölgeyi belirtmek için kullanabilirsiniz.

locationRestriction kullanarak alanı kısıtlama

Sorgu sonuçlarını belirli bir bölgeyle kısıtlamak için locationRestriction parametresini kullanın. İstek gövdenizde, bölge sınırını tanımlayan low ve high enlem ve boylam değerlerini belirtin.

Aşağıdaki örnekte, New York'ta "vejetaryen yemek" için yapılan bir Metin Arama (Yeni) isteği gösterilmektedir. Bu istek, yalnızca açık olan yerler için ilk 10 sonucu döndürür.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

locationBias kullanarak bir bölgeye yönlendirme

Aşağıdaki örnekte, San Francisco şehir merkezindeki bir noktanın 500 metre yakınındaki bir konuma göre ağırlıklandırılmış "vejetaryen yemek" için Metin Arama (Yeni) isteği gösterilmektedir. Bu istek, yalnızca açık olan yerler için ilk 10 sonucu döndürür.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "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' \
'https://places.googleapis.com/v1/places:searchText'

Minimum şarj hızına sahip EV şarj cihazlarını arama

Elektrikli aracınızla uyumlu şarj cihazlarının bulunduğu yerleri aramak için minimumChargingRateKw ve connectorTypes özelliklerini kullanın.

Aşağıdaki örnekte, Mountain View, Kaliforniya'da minimum şarj hızı 10 kW olan Tesla ve J1772 tip 1 elektrikli araç şarj konnektörleri için bir istek gösterilmektedir. Yalnızca dört sonuç döndürülür.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

İstek aşağıdaki yanıtı döndürür:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          ...
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    ...
  ]
}

Hizmet bölgesi işletmelerini arama

Fiziksel hizmet adresi olmayan işletmeleri (ör. mobil temizlik hizmeti veya seyyar yemek arabası) aramak için includePureServiceAreaBusinesses parametresini kullanın.

Aşağıdaki örnekte, İstanbul'daki tesisatçılar için bir istek gösterilmektedir:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Fiziksel hizmet adresi olmayan işletmeler, yanıtta formattedAddress alanını içermez:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Sayfa başına döndürülecek sonuç sayısını belirtme

Sayfa başına döndürülecek sonuç sayısını belirtmek için pageSize parametresini kullanın. Yanıt gövdesindeki nextPageToken parametresi, sonuçların sonraki sayfasına erişmek için sonraki çağrılarda kullanılabilecek bir jeton sağlar.

Aşağıdaki örnekte, sayfa başına 5 sonuçla sınırlı "New York'ta pizza" isteği gösterilmektedir:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    ...
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Sonraki sonuç sayfasına erişmek için istek gövdesinde nextPageToken değerini iletmek üzere pageToken kullanın:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    ...
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

Adres tanımlayıcıları alma

Adres tanımlayıcılar, yakındaki önemli noktalar ve kapsayıcı alanlar dahil olmak üzere bir yerin konumu hakkında ilişkisel bilgiler sağlar.

Aşağıdaki örnekte, San Jose'deki bir alışveriş merkezinin yakınındaki yerler için Metin Arama (Yeni) isteği gösterilmektedir. Bu örnekte, alan maskesine addressDescriptors değerini eklersiniz:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

Yanıtta, istekte belirtilen yer, yakındaki önemli noktaların listesi ve bunların yere olan mesafesi, ayrıca bölgelerin listesi ve bunların yerle olan kapsama ilişkisi yer alır:

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          ...
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          ...
        ]
      }
    },
    ...
  ]
}

İleride açılacak işletmeleri bulma

Aşağıdaki örnekte, New Meadows, Idaho'da gelecekte açılacak işletmeler için bir Text Search (Yeni) isteği gösterilmektedir:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

Yanıt, gelecekte açılacak işletmeleri, işletme durumlarını ve beklenen açılış tarihlerini içerir:

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

Toplu taşıma istasyonu bilgilerini alma

Toplu taşıma istasyonlarını bulmak için Text Search'ü (Yeni) kullanabilirsiniz. Yanıt gövdesi; istasyon adı, bağlı transit operatörleri ve istasyona hizmet veren toplu taşıma hatları dahil olmak üzere istasyonla ilgili bilgileri içerir. Ayrıca yanıtta, toplu taşıma istasyonu bilgilerini görüntülemek için kullanabileceğiniz bir araç simgesi ve renkler de yer alır.

Aşağıdaki örnekte "Grand Central Station" için bir istek gösterilmektedir:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

Yanıt gövdesi, yarıçap içindeki her istasyon, istasyonun hizmet verdiği hatlar, toplu taşıma kurumları tarafından bu durakta yayınlanan uyarılar ve kalkış bilgileri hakkında bilgi içerir:

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

Girişleri ve navigasyon noktalarını alma

Bir hedef için giriş ve navigasyon noktaları isteyebilirsiniz. Girişler, bir yerin giriş ve çıkış noktalarını tanımlar (örneğin, bir havaalanı veya alışveriş merkezindeki farklı kapılar). Navigasyon noktaları, navigasyonun sona ermesi gereken yol kenarı konumlarını tanımlar. Bu, kullanıcıları yolun doğru tarafına veya belirli bir bırakma noktasına yönlendirmek için kullanışlıdır.

Gezinme noktaları navigationPointToken döndürür. Sürücüleri belirli bir konuma yönlendirmek için bu jetonu Navigasyon SDK'sına (Android veya iOS için kullanılabilir) ya da Routes API'ye iletebilirsiniz. Daha fazla bilgi için Navigasyon noktası jetonları başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, alan maskesinde entrances ve navigationPoints içeren "San Francisco Uluslararası Havalimanı" için bir Text Search (New) isteği gösterilmektedir:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

Yanıtta, yerin girişleri ve navigasyon noktaları yer alır:

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

Deneyin.

API Gezgini, API ve API seçeneklerini tanıyabilmeniz için örnek istekler göndermenize olanak tanır.

  1. Sayfanın sağ tarafındaki API simgesini api seçin.

  2. İsterseniz istek parametrelerini düzenleyebilirsiniz.

  3. Execute (Yürüt) düğmesini seçin. İletişim kutusunda, isteği göndermek için kullanmak istediğiniz hesabı seçin.

  4. API Gezgini panelinde, API Gezgini penceresini genişletmek için tam ekran simgesini fullscreen seçin.