Menggunakan Places Aggregate API untuk membuat skor lokasi kustom

Tujuan

Menemukan lokasi yang ideal, baik hotel untuk liburan mendatang atau apartemen yang cocok untuk keluarga, sering kali melibatkan proses yang melelahkan dan memakan waktu untuk membandingkan berbagai opsi. Bagaimana jika Anda dapat membantu mempermudah pengguna dengan menyediakan metrik yang disesuaikan yang mengungkapkan kesesuaian hotel untuk wisatawan atau memberi peringkat listingan apartemen berdasarkan keramahannya bagi keluarga, sehingga mengubah tugas yang melelahkan menjadi keputusan yang mudah.

Dokumen ini menguraikan cara menggunakan Places Aggregate API untuk menghasilkan skor lokasi kustom yang dinamis, berdasarkan kepadatan tempat dalam area geografis yang ditentukan. Skor, peringkat numerik berdasarkan kriteria yang Anda tentukan, akan langsung menyampaikan seberapa cocok lokasi tersebut untuk kebutuhan mereka.

Pertimbangkan skenario saat Anda mempromosikan hotel di kota dan ingin menyoroti hotel di area wisata yang paling menarik dengan membuat skor yang baik untuk wisatawan. Gunakan Places Aggregate API untuk menghitung jumlah jenis tempat yang relevan di dekat setiap hotel. Misalnya, Anda tahu bahwa pelanggan Anda menyukai hotel di lokasi yang dekat dengan beberapa hal berikut:

• Restoran & Kedai kopi
• Taman & Museum
• Toko pakaian

Dengan menerapkan bobot kepentingan pada jumlah jenis tempat yang dipilih ini, Anda dapat menghitung skor keseluruhan untuk setiap lokasi hotel. Skor ini mencerminkan kesesuaian lokasi secara keseluruhan, berdasarkan tempat-tempat terdekat. Bobot yang ditetapkan untuk setiap jenis tempat harus selaras dengan kasus penggunaan spesifik Anda dan hal yang penting bagi target audiens Anda. Dokumen ini akan menggunakan skor baik untuk wisatawan sebagai contoh utama, tetapi skor Anda dapat dibuat untuk mencerminkan demografi dan kebutuhan pengguna.

Prasyarat

Sebelum membaca dokumen ini, sebaiknya Anda memahami dokumentasi berikut:

• Dokumentasi developer Places Aggregate API untuk memahami detail teknis dan parameter yang tersedia.
• [Opsional] Dokumentasi developer Gemini Developer API untuk memahami cara memanggil Gemini menggunakan API dan digunakan dalam dokumen ini sebagai opsi untuk menghasilkan skor lokasi kustom.

Demo

Demo ini menunjukkan contoh cara kerja skor lokasi kustom. Pilih kota dari menu drop-down, lalu klik tombol Calculate Custom Score untuk menampilkan skor lokasi kustom untuk lima lokasi yang telah diisi otomatis.

Memilih jenis tempat yang relevan

Langkah pertama untuk membuat skor lokasi kustom adalah menentukan jenis tempat yang relevan bagi pelanggan Anda dari Tabel A. Saat membuat skor baik untuk wisatawan, kami telah memilih jenis tempat berikut yang ingin dijangkau wisatawan selama masa inap mereka:

• restoran
• taman
• clothing_store
• museum
• coffee_shop

Selanjutnya, tetapkan bobot untuk setiap jenis tempat ini, yang mencerminkan pentingnya jenis tempat tersebut dalam skor akhir. Bobot harus ditentukan berdasarkan hal yang paling penting untuk kasus penggunaan dan preferensi pengguna Anda. Untuk contoh ini, skala bobot akan berkisar antara 0 dan 1, sebagai berikut:

API Gabungan Places Panggilan

Setelah Anda memiliki daftar jenis tempat yang Anda minati, langkah berikutnya adalah memanggil Places Aggregate API.

Places Aggregate API memerlukan filter lokasi. Untuk contoh ini, gunakan circle, dengan latLng tengah sebagai lokasi hotel Anda, dan radius sebesar 500 m. Tetapkan juga ratingFilter untuk menampilkan tempat dengan rating antara 3,8 dan 5, yang mengecualikan tempat dengan rating lebih rendah dari jumlah.

Bereksperimenlah dengan mengubah setelan filter lokasi untuk kasus penggunaan tertentu. Misalnya, Anda mungkin ingin mengambil gambar tempat dalam radius yang lebih luas dari lintang dan bujur pusat dengan meningkatkan nilai radius. Atau, Anda dapat menggunakan metode lain untuk menetapkan area penelusuran, seperti Region atau Area kustom.

Pelajari bagian filter lokasi dalam dokumentasi Places Aggregate API untuk mempelajari opsi yang tersedia bagi Anda.

Panggil Places Aggregate API untuk setiap jenis tempat dan lokasi yang ingin Anda buat skor kustomnya. Misalnya, panggil Jenis Tempat restoran untuk salah satu hotel Anda:

curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
--header 'X-Goog-Api-Key: API_KEY \
--header 'Content-Type: application/json' \
--data '{
    "insights": [
        "INSIGHT_COUNT"
    ],
    "filter": {
        "locationFilter": {
            "circle": {
                "latLng": {
                    "latitude": 51.51611,
                    "longitude": -0.12726
                },
                "radius": 500
            }
        },
        "typeFilter": {
            "includedTypes": [
                "restaurant"
            ]
        },
        "ratingFilter": {
            "minRating": 3.8,
            "maxRating": 5
        }
    }
}'

Setelah semua panggilan ke API selesai, Anda memiliki data yang terlihat seperti ini untuk setiap lokasi:

Membuat skor lokasi kustom

Sekarang Anda memiliki jumlah tempat dan bobot untuk setiap jenis tempat untuk setiap lokasi, Anda kini dapat membuat skor lokasi kustom. Kita akan membahas dua opsi di bagian ini, menggunakan algoritma lokal, atau menggunakan Gemini Developer API.

Opsi 1: Menggunakan algoritma

Opsi pertama yang akan kita bahas adalah menggunakan algoritma lokal untuk menghasilkan skor menggunakan bobot dan jumlah untuk setiap Jenis Tempat. Normalisasi skor ini ke skala 0 hingga 5, dengan nilai yang lebih tinggi menunjukkan area yang lebih menarik berdasarkan kriteria Anda. Untuk contoh ini, buat dua objek JavaScript dari data di atas:

    {
      "restaurant": 56,
      "park": 3,
      "clothing_store": 32,
      "museum": 8,
      "coffee_shop": 41
    }
    

    {
      "restaurant": 0.8,
      "park": 0.6,
      "clothing_store": 0.3,
      "museum": 0.2,
      "coffee_shop": 0.5
    }
    

Buat skor dari jumlah dan bobot dengan mengalikan itemCounts dengan typeWeights, dan menambahkan hasilnya ke weightedCount secara keseluruhan:

let weightedCount = 0;
for (const itemType in itemCounts) {
  weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);

Untuk contoh ini, output langkah ini adalah: 78,3.

Sekarang Anda dapat menggunakan normalisasi logaritmik untuk menghasilkan skor akhir untuk lokasi ini pada skala antara 0 dan 5:

if (weightedCount === 0) {
   normalizedScore = 0;
} else {
   normalizedScore = Math.log(weightedCount + 1);
}

// Clamp between 0 and 5
normalizedScore = Math.max(0, Math.min(5, normalizedScore));

Untuk contoh ini, output skor akhir adalah: 4,36 (dibulatkan ke dua tempat desimal).

Opsi 2: Menggunakan Gemini Developer API

Sebagai alternatif penggunaan algoritma lokal, Gemini Developer API menawarkan cara yang efektif untuk menghitung skor lokasi kustom untuk semua lokasi. Cukup berikan data jumlah dan bobot dengan petunjuk sistem untuk semua lokasi hotel Anda.

Metode ini sangat berguna jika Anda memiliki informasi yang nuansanya ingin disertakan dalam penghitungan, seperti:

• Deskripsi teks untuk setiap lokasi hotel, misalnya: "Lokasi ini cocok untuk keluarga dan areanya tenang pada malam hari".
• Informasi tentang pengguna Anda, seperti: "Pengguna ini melakukan pemesanan untuk keluarga dan memilih area yang tenang di lokasi pusat".

Gemini Developer API dapat memahami dan mempertimbangkan data kualitatif ini sehingga menghasilkan skor yang lebih canggih dan relevan di luar pendekatan matematis murni.

Dengan menggunakan Gemini Developer API, selain jenis tempat dan tabel bobot di atas, Anda dapat memiliki data deskripsi untuk setiap lokasi yang terlihat seperti ini:

Deskripsi kualitatif ini beserta informasi atau preferensi pengguna dapat disertakan dalam perintah Anda ke Gemini.

Petunjuk sistem

Gemini memerlukan petunjuk, bersama dengan data mentah, untuk mengetahui bahwa Gemini diharapkan menghasilkan skor untuk setiap lokasi, berdasarkan titik data yang diberikan. Contoh petunjuk sistem untuk mencapai hal ini dapat berupa:

You will be given a json file containing details about a number of locations grouped by their latitude and longitudes.

Within the location details is information about the count of places nearby the location that match a specific category, and the weighting of importance of that category, between 0 - 1.

You will also be given information about the user's preference, and a description of each location. Take this into consideration when generating scores.

Generate a location suitability score taking these into account for each location. The score should be between 1 - 5 inclusive, to two decimal places. The minimum score a location can receive is 1.

Output in JSON

Petunjuk sistem di atas memungkinkan Gemini mengetahui data yang diharapkan, dan output yang diharapkan dari model AI. Petunjuk ini juga meminta output dalam JSON.

Output terstruktur

Meskipun telah meminta Gemini untuk menghasilkan output dalam JSON, kita perlu lebih spesifik tentang struktur output, sehingga kita tahu apa yang akan terjadi saat membuat kueri dengan kode. Untuk ini, kita dapat menambahkan petunjuk output terstruktur tambahan ke permintaan, menggunakan kolom responseSchema di Gemini API. Ini menggunakan objek skema OpenAPI untuk membatasi output model.

Contoh:

{
  "type": "array",
  "description": "Array of location data with score",
  "items": {
    "type": "object",
    "properties": {
      "location": {
        "type": "object",
        "description": "Geographical coordinates of the location",
        "properties": {
          "latitude": {
            "type": "number",
            "format": "float",
            "description": "Latitude of the location"
          },
          "longitude": {
            "type": "number",
            "format": "float",
            "description": "Longitude of the location"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ]
      },
      "score": {
        "type": "string",
        "description": "A score associated with the location"
      }
    },
    "required": [
      "location",
      "score"
    ]
  }
}

Contoh ini meminta Gemini untuk menghasilkan array JavaScript dengan hal berikut:

• Lintang & bujur lokasi
• Skor lokasi kustom

Dengan menggunakan petunjuk sistem dan output terstruktur di atas, respons dari Gemini untuk satu lokasi akan terlihat seperti ini, dengan score sebagai skor lokasi kustom:

[
  {
    "location": {
      "latitude": 51.51611,
      "longitude": -0.12726
    },
    "score": "4.13"
  }
]

Menampilkan skor

Setelah Anda membuat skor lokasi kustom untuk setiap lokasi menggunakan salah satu metode yang dijelaskan, skor tersebut dapat ditampilkan bersama detail hotel Anda, atau digunakan sebagai opsi pemfilteran penelusuran. Misalnya, "tampilkan tempat dengan skor cocok untuk wisatawan yang tinggi". Hal ini akan memungkinkan pelanggan Anda mengambil keputusan berdasarkan data saat melakukan pemesanan.

Kesimpulan

Menggunakan skor lokasi kustom dapat menjadi alat yang efektif untuk memberikan ringkasan sekilas tentang kesesuaian suatu area kepada pengguna. Dokumen ini menunjukkan cara membuat skor lokasi kustom untuk berbagai lokasi menggunakan lima jenis tempat terpisah. Implementasi ini dapat diubah sesuai kebutuhan Anda, dan jenis tempat yang serupa dapat digabungkan menjadi satu permintaan, untuk menampilkan jumlah gabungan jenis tersebut, untuk diberikan ke solusi penskoran lokasi kustom Anda.

Coba Places Aggregate API sekarang untuk membuat skor lokasi yang bermanfaat guna membantu pelanggan Anda membuat keputusan berbasis lokasi yang tepat.

Kontributor

Henrik Valve | Engineer DevX