Halaman ini diterjemahkan oleh Cloud Translation API.

Nearby Search (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Permintaan Nearby Search (Baru) menggunakan satu atau beberapa jenis tempat, dan menampilkan daftar tempat yang cocok dalam area yang ditentukan. Mask kolom yang menentukan satu atau beberapa jenis data wajib diisi. Penelusuran Langsung (Baru) hanya mendukung permintaan POST.

API Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat memahami API dan opsi API:

Cobalah!

Coba demo interaktif untuk melihat hasil Penelusuran di Sekitar (Baru) yang ditampilkan di peta.

Permintaan Nearby Search (Baru)

Permintaan Nearby Search (Baru) adalah permintaan HTTP POST ke URL dalam bentuk:

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

Teruskan semua parameter dalam isi permintaan JSON atau dalam header sebagai bagian dari permintaan POST. Contoh:

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

Respons Nearby Search (Baru)

Penelusuran Langsung (Baru) menampilkan objek JSON sebagai respons. Dalam respons:

Array places berisi semua tempat yang cocok.
Setiap tempat dalam array direpresentasikan oleh objek Place. Objek Place berisi informasi mendetail tentang satu tempat.
FieldMask yang diteruskan dalam permintaan menentukan daftar kolom yang ditampilkan dalam objek Place.

Objek JSON lengkap dalam bentuk:

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

Parameter wajib

FieldMask

Tentukan daftar kolom yang akan ditampilkan dalam respons dengan membuat mask kolom respons. Teruskan mask kolom respons ke metode menggunakan parameter URL $fields atau fields, atau menggunakan header HTTP X-Goog-FieldMask. Tidak ada daftar default kolom yang ditampilkan dalam respons. Jika Anda menghapus mask kolom, metode akan menampilkan error.

Penyamaran kolom merupakan praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak diperlukan. Cara ini akan membantu Anda menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

Tentukan daftar yang dipisahkan koma untuk jenis data tempat yang akan ditampilkan. Misalnya, untuk mengambil nama tampilan dan alamat tempat.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Catatan: Spasi tidak diizinkan di mana pun dalam daftar kolom.

Gunakan * untuk mengambil semua kolom.
```
X-Goog-FieldMask: *
```
Karakter pengganti "*" memilih semua kolom. Namun, meskipun karakter pengganti tersebut boleh digunakan dalam pengembangan, Google tidak menyarankan penggunaan mask kolom respons karakter pengganti (*) dalam produksi karena banyaknya data yang dapat ditampilkan.

Panduan lebih lanjut untuk menggunakan places.iconMaskBaseUri dan places.iconBackgroundColor dapat ditemukan di bagian Ikon Tempat.

Tentukan satu atau beberapa kolom berikut:
- Kolom berikut memicu SKU Nearby Search (Basic):
  
  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
  
  ^* Kolom places.googleMapsLinks berada dalam tahap Pratinjau pra-GA dan tidak ada biaya, yang berarti penagihan adalah $0, untuk penggunaan selama Pratinjau.
  
  ^** Kolom places.name berisi nama resource tempat dalam bentuk: places/PLACE_ID. Gunakan places.displayName untuk mengakses nama tekstual tempat tersebut.
- Kolom berikut memicu SKU Nearby Search (Advanced):
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- Kolom berikut memicu SKU Nearby Search (Preferred):
  
  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
  
  ^* Penelusuran Teks dan Penelusuran Langsung saja
locationRestriction

Wilayah yang akan ditelusuri ditentukan sebagai lingkaran, yang ditentukan oleh titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Radius defaultnya adalah 0,0. Anda harus menetapkannya dalam permintaan ke nilai yang lebih besar dari 0,0.

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

Parameter opsional

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

Memungkinkan Anda menentukan daftar jenis dari jenis Tabel A yang digunakan untuk memfilter hasil penelusuran. Maksimal 50 jenis dapat ditentukan di setiap kategori batasan jenis.

Catatan: Nilai dalam Tabel B hanya ditampilkan dalam respons. Anda tidak dapat menggunakan nilai dalam Tabel B sebagai filter.

Tempat hanya dapat memiliki satu jenis utama dari jenis Tabel A yang terkait dengan tempat tersebut. Misalnya, jenis utama mungkin "mexican_restaurant" atau "steak_house". Gunakan includedPrimaryTypes dan excludedPrimaryTypes untuk memfilter hasil pada jenis utama tempat.

Tempat juga dapat memiliki beberapa nilai jenis dari jenis Tabel A yang terkait dengannya. Misalnya, restoran mungkin memiliki jenis berikut: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Gunakan includedTypes dan excludedTypes untuk memfilter hasil pada daftar jenis yang terkait dengan tempat.

Saat Anda menentukan jenis utama umum, seperti "restaurant" atau "hotel", respons dapat berisi tempat dengan jenis utama yang lebih spesifik daripada yang ditentukan. Misalnya, Anda menentukan untuk menyertakan jenis utama "restaurant". Respons kemudian dapat berisi tempat dengan jenis utama "restaurant", tetapi respons juga dapat berisi tempat dengan jenis utama yang lebih spesifik, seperti "chinese_restaurant" atau "seafood_restaurant".

Jika penelusuran ditentukan dengan beberapa batasan jenis, hanya tempat yang memenuhi semua batasan yang akan ditampilkan. Misalnya, jika Anda menentukan {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, tempat yang ditampilkan akan menyediakan layanan terkait "restaurant", tetapi tidak beroperasi terutama sebagai "steak_house".

Jika Anda menghapus includedTypes, excludedTypes, includedPrimaryTypes, dan excludedPrimaryTypes dari permintaan, penelusuran akan menampilkan tempat untuk semua jenis dari dalam batas pembatasan lokasi.

includedTypes

Daftar jenis tempat dari Tabel A yang akan ditelusuri, yang dipisahkan koma. Jika parameter ini dihilangkan, semua jenis tempat akan ditampilkan.

excludedTypes

Daftar jenis tempat yang dipisahkan koma dari Tabel A untuk dikecualikan dari penelusuran.

Jika Anda menentukan includedTypes ( seperti "school") dan excludedTypes (seperti "primary_school") dalam permintaan, respons akan menyertakan tempat yang dikategorikan sebagai "school", tetapi bukan sebagai "primary_school". Responsnya mencakup tempat yang cocok dengan setidaknya satu dari includedTypes dan tidak satu pun dari excludedTypes.

Jika ada jenis yang bertentangan, seperti jenis yang muncul di includedTypes dan excludedTypes, error INVALID_REQUEST akan ditampilkan.

includedPrimaryTypes

Daftar jenis tempat utama yang dipisahkan koma dari Tabel A untuk disertakan dalam penelusuran.

excludedPrimaryTypes

Daftar jenis tempat utama yang dipisahkan koma dari Tabel A yang akan dikecualikan dari penelusuran.

Jika ada jenis utama yang bertentangan, seperti jenis yang muncul di includedPrimaryTypes dan excludedPrimaryTypes, error INVALID_ARGUMENT akan ditampilkan.
languageCode

Bahasa yang digunakan untuk menampilkan hasil.
- Lihat daftar bahasa yang didukung. Google sering memperbarui bahasa yang didukung, sehingga daftar ini mungkin tidak lengkap.
- Jika languageCode tidak diberikan, API akan ditetapkan secara default ke en. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan error INVALID_ARGUMENT.
- API ini melakukan yang terbaik untuk menyediakan alamat yang dapat dibaca oleh pengguna dan pengguna lokal. Untuk mencapai tujuan tersebut, metode ini menampilkan alamat dalam bahasa lokal, yang ditransliterasi ke skrip yang dapat dibaca oleh pengguna jika perlu, dengan memperhatikan bahasa pilihan. Semua alamat lain dikembalikan dalam bahasa yang dipilih. Semua komponen alamat dikembalikan dalam bahasa yang sama, yang dipilih dari komponen pertama.
- Jika nama tidak tersedia dalam bahasa yang dipilih, API menggunakan bahasa terdekat yang sesuai.
- Bahasa yang dipilih berpengaruh kecil terhadap serangkaian hasil yang dipilih API untuk dikembalikan, dan urutan pengembaliannya. Geocoder menafsirkan singkatan secara berbeda bergantung pada bahasa, seperti singkatan untuk jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa tetapi tidak valid dalam bahasa lainnya.
maxResultCount

Menentukan jumlah maksimum hasil tempat yang akan ditampilkan. Harus antara 1 dan 20 (default) inklusif.
rankPreference

Jenis peringkat yang akan digunakan. Jika parameter ini dihilangkan, hasil akan diberi peringkat berdasarkan popularitas. Mungkin berupa salah satu dari hal berikut:
- POPULARITY (default) Mengurutkan hasil berdasarkan popularitasnya.
- DISTANCE Mengurutkan hasil dalam urutan menaik berdasarkan jaraknya dari lokasi yang ditentukan.
regionCode

Kode wilayah yang digunakan untuk memformat respons, yang ditentukan sebagai nilai kode CLDR dua karakter. Tidak ada nilai default.

Jika nama negara kolom formattedAddress dalam respons cocok dengan regionCode, kode negara akan dihilangkan dari formattedAddress. Parameter ini tidak berpengaruh pada adrFormatAddress, yang selalu menyertakan nama negara, atau pada shortFormattedAddress, yang tidak pernah menyertakannya.

Sebagian besar kode CLDR identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk), sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "Inggris Raya dan Irlandia Utara"). Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.

Contoh Nearby Search (Baru)

Menemukan tempat dari satu jenis

Contoh berikut menunjukkan permintaan Nearby Search (Baru) untuk nama tampilan semua restoran dalam radius 500 meter, yang ditentukan oleh circle:

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

Perhatikan bahwa header X-Goog-FieldMask menetapkan bahwa respons berisi kolom data berikut: places.displayName. Respons kemudian dalam bentuk:

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

Tambahkan lebih banyak jenis data ke mask kolom untuk menampilkan informasi tambahan. Misalnya, tambahkan places.formattedAddress,places.types,places.websiteUri untuk menyertakan alamat, jenis, dan alamat Web restoran dalam respons:

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

Respons sekarang dalam bentuk:

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

Menemukan tempat dari beberapa jenis

Contoh berikut menunjukkan permintaan Penelusuran Langsung (Baru) untuk nama tampilan semua minimarket dan toko minuman keras dalam radius 1.000 meter dari circle yang ditentukan:

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

Contoh ini menambahkan places.primaryType dan places.types ke mask kolom sehingga responsnya menyertakan informasi jenis tentang setiap tempat, sehingga memudahkan Anda memilih tempat yang sesuai dari hasil.

Mengecualikan jenis tempat dari penelusuran

Contoh berikut menunjukkan permintaan Penelusuran Langsung (Baru) untuk semua tempat berjenis "school", yang mengecualikan semua tempat berjenis "primary_school", yang memberi peringkat hasil berdasarkan jarak:

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

Menelusuri semua tempat di dekat area, yang diberi peringkat berdasarkan jarak

Contoh berikut menampilkan permintaan Nearby Search (Baru) untuk tempat-tempat yang dekat dengan titik di pusat kota San Francisco. Dalam contoh ini, Anda menyertakan parameter rankPreference untuk memberi peringkat hasil berdasarkan jarak:

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

Cobalah!

API Explorer memungkinkan Anda membuat permintaan contoh sehingga Anda dapat memahami API dan opsi API.

Pilih ikon API, , di sisi kanan halaman.
Jika ingin, luaskan Show standard variables dan tetapkan parameter fields ke field mask.
Jika ingin, edit Isi permintaan.
Pilih tombol Execute. Di jendela pop-up, pilih akun yang ingin digunakan untuk membuat permintaan.
Di panel API Explorer, pilih ikon luaskan, , untuk meluaskan jendela API Explorer.

Nearby Search (Baru)

Permintaan Nearby Search (Baru)

Respons Nearby Search (Baru)

Parameter wajib

FieldMask

locationRestriction

Parameter opsional

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode

Contoh Nearby Search (Baru)

Menemukan tempat dari satu jenis

Menemukan tempat dari beberapa jenis

Mengecualikan jenis tempat dari penelusuran

Menelusuri semua tempat di dekat area, yang diberi peringkat berdasarkan jarak

Cobalah!