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 membuat frustrasi dan memakan waktu untuk membandingkan berbagai opsi. Bagaimana jika Anda dapat mempermudah hal ini bagi pengguna dengan memberikan metrik yang disesuaikan yang mengungkapkan kesesuaian hotel untuk turis atau memberi peringkat listingan apartemen berdasarkan kesesuaiannya untuk keluarga, sehingga mengubah tugas yang membosankan menjadi keputusan yang mudah.

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

Bayangkan Anda mempromosikan hotel di suatu kota dan ingin menandai hotel yang berada di area wisata paling menarik dengan membuat skor bagus untuk turis. Gunakan Places Aggregate API untuk menghitung jumlah jenis tempat yang relevan di dekat setiap hotel. Misalnya, Anda tahu bahwa pelanggan Anda menghargai hotel di lokasi yang dekat dengan sejumlah tempat berikut:

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

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

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 membuat skor lokasi kustom.

Demo

Demo ini menunjukkan contoh skor lokasi kustom yang sedang digunakan. Pilih kota dari drop-down, lalu klik tombol Hitung Skor Kustom untuk menampilkan skor lokasi kustom untuk lima lokasi yang telah diisi sebelumnya.

Pilih jenis tempat yang relevan

Langkah pertama untuk membuat skor lokasi kustom adalah menentukan jenis tempat yang relevan bagi pelanggan Anda dari Tabel A. Karena kami membuat skor cocok untuk turis, kami telah memilih jenis tempat berikut yang ingin dikunjungi turis selama menginap:

• restoran
• taman
• clothing_store
• museum
• coffee_shop

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

Panggil Places Aggregate API

Setelah 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 titik tengah latLng sebagai lokasi hotel Anda, dan radius sebesar 500 m. Tetapkan juga ratingFilter untuk menampilkan tempat dengan rating antara 3,8 dan 5, dengan mengecualikan tempat dengan rating lebih rendah dari jumlah.

Bereksperimenlah dengan memvariasikan setelan filter lokasi untuk kasus penggunaan spesifik Anda. Misalnya, Anda mungkin ingin mengambil tempat dalam radius yang lebih luas dari lintang dan bujur pusat Anda 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 akan memiliki data yang terlihat seperti ini untuk setiap lokasi:

Membuat skor lokasi kustom

Setelah memiliki jumlah tempat dan pembobotan untuk setiap jenis tempat di setiap lokasi, Anda kini dapat membuat skor lokasi kustom. Kita akan membahas dua opsi di bagian ini, yaitu 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 pembobotan dan jumlah untuk setiap Jenis Tempat. Normalisasikan 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 pembobotan dengan mengalikan itemCounts dengan typeWeights, dan menambahkan hasilnya ke weightedCount 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 membuat skor akhir lokasi ini dalam 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 menjadi dua tempat desimal).

Opsi 2: Menggunakan Gemini Developer API

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

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

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

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

Dengan menggunakan Gemini Developer API, selain jenis tempat dan tabel pembobotan 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, beserta data mentah, untuk mengetahui bahwa Gemini diharapkan membuat skor untuk setiap lokasi, berdasarkan titik data yang diberikan. Contoh petunjuk sistem untuk mencapai hal ini dapat berupa sebagai berikut:

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 memberi tahu Gemini data apa yang diharapkan, dan apa output yang diharapkan dari model AI. Petunjuk ini juga meminta output dalam JSON.

Output terstruktur

Meskipun kita telah meminta Gemini untuk menampilkan hasil dalam JSON, kita perlu lebih spesifik tentang struktur output, sehingga kita tahu apa yang diharapkan saat kita mengirimkan kueri dengan kode. Untuk itu, kita dapat menambahkan instruksi output terstruktur tambahan ke permintaan, menggunakan kolom responseSchema di Gemini API. Hal 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:

• 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, "tunjukkan tempat dengan skor cocok untuk turis yang tinggi". Hal ini akan memungkinkan pelanggan Anda membuat keputusan berdasarkan data saat melakukan pemesanan.

Kesimpulan

Penggunaan skor lokasi kustom dapat menjadi alat yang efektif untuk memberikan ringkasan sekilas kepada pengguna tentang kesesuaian suatu area. 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, yang akan diberikan ke solusi pemberian skor lokasi kustom Anda.

Coba Places Aggregate API hari ini untuk membuat skor lokasi yang berwawasan luas guna membantu pelanggan Anda membuat keputusan berbasis lokasi yang tepat.

Kontributor

Henrik Valve | DevX Engineer