Nearby Search (Baru)

Pilih platform: Android iOS JavaScript Layanan Web
Developer Wilayah Ekonomi Eropa (EEA)

Pengantar

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 diperlukan. Nearby Search (Baru) hanya mendukung permintaan POST.

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

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

Permintaan Nearby Search (Baru)

Permintaan Penelusuran di Sekitar (Baru) adalah permintaan POST HTTP ke URL dalam bentuk:

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

Teruskan semua parameter di isi permintaan JSON atau di 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)

Nearby Search (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 lengkapnya berbentuk:

{
  "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 kolom yang ditampilkan secara default 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, sehingga membantu menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

    Tentukan daftar jenis data tempat yang dipisahkan koma yang akan ditampilkan. Misalnya, untuk mengambil nama tampilan dan alamat tempat.

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

    Gunakan * untuk mengambil semua kolom.

    X-Goog-FieldMask: *

    Tentukan satu atau beberapa kolom berikut:

    • Kolom berikut memicu SKU Nearby Search Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      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.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Deskripsi alamat umumnya tersedia untuk pelanggan di India dan bersifat eksperimental di tempat lain.

      ** 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 Enterprise:

      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 Enterprise + Atmosphere:

      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

      * Hanya Penelusuran Teks dan Penelusuran di Sekitar

  • locationRestriction

    Region 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 dalam setiap kategori pembatasan jenis.

    Tempat hanya dapat memiliki satu jenis utama dari jenis Tabel A yang terkait dengan tempat tersebut. Misalnya, jenis utama dapat berupa "mexican_restaurant" atau "steak_house". Gunakan includedPrimaryTypes dan excludedPrimaryTypes untuk memfilter hasil berdasarkan jenis utama suatu 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 suatu 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 menyediakan layanan terkait "restaurant", tetapi tidak beroperasi terutama sebagai "steak_house".

    includedTypes

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

    excludedTypes

    Daftar jenis tempat yang dipisahkan koma dari Tabel A yang akan 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 tidak sebagai "primary_school". Respons mencakup tempat yang cocok dengan setidaknya satu dari includedTypes dan tidak ada 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 tidak disertakan 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 menggunakan en sebagai default. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan error INVALID_ARGUMENT.
    • API ini berupaya sebaik mungkin untuk memberikan alamat jalan yang dapat dibaca oleh pengguna dan penduduk setempat. Untuk mencapai tujuan tersebut, API ini menampilkan alamat jalan 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 ditampilkan dalam bahasa yang sama, yang dipilih dari komponen pertama.
    • Jika nama tidak tersedia dalam bahasa yang dipilih, API menggunakan bahasa terdekat yang sesuai.
    • Bahasa pilihan memiliki sedikit pengaruh pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan hasil tersebut ditampilkan. Geocoder menafsirkan singkatan secara berbeda bergantung pada bahasa, seperti singkatan untuk jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa, tetapi tidak dalam bahasa lain.

  • 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 tidak disertakan, hasil akan diberi peringkat berdasarkan popularitas. Dapat berupa salah satu dari berikut ini:

    • 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, ditentukan sebagai nilai kode CLDR dua karakter. Tidak ada nilai default.

    Jika nama negara di kolom formattedAddress dalam respons cocok dengan regionCode, kode negara akan dihapus 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 "The United Kingdom of Great Britain and Northern Ireland"). Parameter dapat memengaruhi hasil berdasarkan hukum yang berlaku.

Contoh Nearby Search (Baru)

Menemukan tempat dengan 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 menentukan bahwa respons berisi kolom data berikut: places.displayName. response 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 berbagai jenis

Contoh berikut menunjukkan permintaan Nearby Search (Baru) untuk nama tampilan semua toko serba ada 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 respons menyertakan informasi jenis tentang setiap tempat, sehingga memudahkan pemilihan tempat yang sesuai dari hasil.

Contoh berikut menunjukkan permintaan Nearby Search (Baru) untuk semua tempat berjenis "school", tidak termasuk semua tempat berjenis "primary_school", mengurutkan 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 suatu area, mengurutkan berdasarkan jarak

Contoh berikut menunjukkan permintaan Nearby Search (Baru) untuk tempat di dekat suatu titik di pusat kota San Francisco. Dalam contoh ini, Anda menyertakan parameter rankPreference untuk memberi peringkat hasil menurut 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

Mendapatkan deskriptor alamat

Deskripsi alamat memberikan informasi relasional tentang lokasi suatu tempat, termasuk bangunan terkenal di sekitar dan area yang mencakupnya.

Contoh berikut menunjukkan permintaan Penelusuran di Sekitar (Baru) untuk tempat di dekat mal di San Jose. Dalam contoh ini, Anda menyertakan addressDescriptors dalam mask kolom:

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-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:searchNearby

Respons mencakup tempat yang ditentukan dalam permintaan, daftar landmark terdekat dan jaraknya dari tempat tersebut, serta daftar area dan hubungan penampungannya dengan tempat tersebut:

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "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": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "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"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

Cobalah!

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

  1. Pilih ikon API api di sisi kanan halaman.

  2. Edit parameter permintaan secara opsional.

  3. Pilih tombol Execute. Dalam dialog, pilih akun yang ingin Anda gunakan untuk membuat permintaan.

  4. Di panel APIs Explorer, pilih ikon layar penuh fullscreen untuk meluaskan jendela APIs Explorer.