Tworzenie niestandardowego wyniku lokalizacji za pomocą interfejsu Places Aggregate API

Cel

Znalezienie idealnego miejsca, czy to hotelu na zbliżające się wakacje, czy apartamentu odpowiedniego dla rodziny, często wiąże się z frustrującym i czasochłonnym procesem porównywania wielu opcji. A gdyby tak ułatwić użytkownikom to zadanie, udostępniając im dostosowane dane, które pokazują, czy hotel jest odpowiedni dla turystów, lub rankingi ofert apartamentów na podstawie ich przyjazności dla rodzin, zamieniając żmudne zadanie w łatwą decyzję?

Z tego dokumentu dowiesz się, jak używać interfejsu Places Aggregate API do generowania dynamicznych, niestandardowych wyników lokalizacji na podstawie gęstości miejsc w określonym obszarze geograficznym. Wynik, czyli numeryczny ranking na podstawie określonych kryteriów, od razu pokaże, jak bardzo lokalizacja odpowiada potrzebom użytkownika.

Załóżmy, że promujesz hotele w mieście i chcesz wyróżnić te, które znajdują się w najbardziej atrakcyjnych turystycznie obszarach, tworząc ocenę przydatności dla turystów. Użyj interfejsu Places Aggregate API, aby zliczyć, ile odpowiednich typów miejsc znajduje się w pobliżu każdego hotelu. Na przykład wiesz, że Twoi klienci cenią hotele w lokalizacjach, które znajdują się w pobliżu:

• Restauracje i kawiarnie
• Parki i muzea
• Sklepy odzieżowe

Stosując wagi ważności do liczby wybranych typów miejsc, możesz obliczyć ogólny wynik dla każdej lokalizacji hotelu. Wynik odzwierciedla ogólną przydatność lokalizacji na podstawie miejsc w pobliżu. Wagi przypisane do każdego typu miejsca powinny być zgodne z Twoim konkretnym przypadkiem użycia i tym, co jest ważne dla Twoich odbiorców. W tym dokumencie jako głównego przykładu użyjemy oceny dobra dla turystów, ale Twoja ocena może być dostosowana do Twoich grup demograficznych i potrzeb użytkowników.

Wymagania wstępne

Zanim przeczytasz ten dokument, zapoznaj się z tymi materiałami:

• Dokumentacja dla programistów interfejsu Places Aggregate API, w której znajdziesz szczegóły techniczne i dostępne parametry.
• [Opcjonalnie] Dokumentacja interfejsu Gemini Developer API dla deweloperów, która zawiera informacje o tym, jak wywoływać Gemini za pomocą interfejsu API. W tym dokumencie jest ona używana jako opcja generowania niestandardowego wyniku lokalizacji.

Prezentacja

Ta wersja demonstracyjna pokazuje przykład działania niestandardowego wyniku lokalizacji. Wybierz miasto z menu i kliknij przycisk Oblicz niestandardowy wynik, aby wyświetlić niestandardowy wynik lokalizacji dla 5 wstępnie wypełnionych lokalizacji.

Wybierz odpowiednie typy miejsc

Pierwszym krokiem w budowaniu własnego wyniku lokalizacji jest wybranie typów miejsc, które są istotne dla Twoich klientów. Znajdziesz je w tabeli A. Tworzymy ocenę dobrą dla turystów, dlatego wybraliśmy te typy miejsc, w pobliżu których turyści będą chcieli się zatrzymać podczas pobytu:

• restauracja
• park
• clothing_store
• muzeum
• coffee_shop

Następnie przypisz wagę do każdego z tych typów miejsc, odzwierciedlającą jego względne znaczenie w wyniku końcowym. Wagi powinny być określane na podstawie tego, co jest najważniejsze w Twoim przypadku użycia i preferencjach użytkowników. W tym przykładzie skala ważenia będzie się mieścić w zakresie od 0 do 1:

Wywoływanie interfejsu Places Aggregate API

Gdy masz już listę typów miejsc, które Cię interesują, następnym krokiem jest wywołanie interfejsu Places Aggregate API.

Interfejs Places Aggregate API wymaga filtra lokalizacji. W tym przykładzie użyj circle, gdzie środek latLng to lokalizacja Twojego hotelu, a radius to 500 m. Ustaw też parametr ratingFilter, aby zwracać miejsca z oceną od 3,8 do 5, wykluczając z liczby miejsca z niższą oceną.

Eksperymentuj z różnymi ustawieniami filtra lokalizacji w swoim konkretnym przypadku użycia. Możesz na przykład zwiększyć wartość promienia, aby objąć miejsca w większej odległości od środkowych współrzędnych geograficznych. Możesz też użyć innej metody określania obszaru wyszukiwania, np. Region lub Obszar niestandardowy.

Zapoznaj się z sekcją filtra lokalizacji w dokumentacji interfejsu Places Aggregate API, aby dowiedzieć się więcej o dostępnych opcjach.

Wywołaj interfejs Places Aggregate API dla każdego typu miejsca i lokalizacji, dla których chcesz wygenerować niestandardowy wynik. Na przykład wywołaj typ miejsca restauracji dla jednego z Twoich hoteli:

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
        }
    }
}'

Po zakończeniu wszystkich wywołań interfejsu API będziesz mieć dane podobne do tych poniżej dla każdej lokalizacji:

Generowanie niestandardowego wyniku lokalizacji

Teraz masz liczbę miejsc i wagi dla każdego typu miejsca w każdej lokalizacji, więc możesz wygenerować niestandardowy wynik lokalizacji. W tej sekcji omówimy 2 opcje: użycie algorytmu lokalnego lub interfejsu Gemini Developer API.

Opcja 1. Użyj algorytmu

Pierwsza opcja, którą omówimy, to użycie algorytmu lokalnego do wygenerowania wyniku na podstawie wag i liczby każdego typu miejsca. Znormalizuj ten wynik do skali od 0 do 5, gdzie wyższe wartości oznaczają bardziej atrakcyjny obszar na podstawie Twoich kryteriów. W tym przykładzie wygeneruj z powyższych danych 2 obiekty JavaScript:

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

Wygeneruj wynik na podstawie liczby i wag, mnożąc itemCounts przez typeWeights i dodając wyniki do ogólnego weightedCount:

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

W tym przykładzie wynikiem tego kroku jest 78, 3.

Teraz możesz użyć normalizacji logarytmicznej, aby wygenerować ostateczny wynik dla tej lokalizacji w skali od 0 do 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));

W tym przykładzie wynik końcowy to 4, 36 (zaokrąglony do 2 miejsc po przecinku).

Opcja 2. Użyj interfejsu Gemini Developer API

Interfejs Gemini Developer API to alternatywa dla algorytmu lokalnego. Umożliwia on obliczanie niestandardowego wyniku lokalizacji dla wszystkich lokalizacji. Wystarczy podać dane o liczbie i wadze wraz z instrukcjami systemowymi dla wszystkich lokalizacji hoteli.

Ta metoda jest szczególnie przydatna, jeśli chcesz uwzględnić w obliczeniach szczegółowe informacje, takie jak:

• Opisy tekstowe każdej lokalizacji hotelu, np. „Ta lokalizacja jest odpowiednia dla rodzin, a w nocy jest tu cicho”.
• Informacje o użytkowniku, np. „Ten użytkownik rezerwuje pobyt dla rodziny i woli cichą okolicę w centralnej lokalizacji”.

Interfejs Gemini Developer API może rozumieć te dane jakościowe i brać je pod uwagę, co pozwala uzyskać bardziej zaawansowany i trafny wynik niż w przypadku czysto matematycznego podejścia.

Korzystając z interfejsu Gemini Developer API, oprócz typu miejsca i tabeli wag podanej powyżej możesz uzyskać dane opisowe dla każdej lokalizacji, które wyglądają tak:

Te opisy jakościowe wraz z informacjami o użytkowniku lub jego preferencjami można uwzględnić w prompcie do Gemini.

Instrukcje systemowe

Aby Gemini wiedział, że ma wygenerować wynik dla każdej lokalizacji na podstawie podanych punktów danych, musisz podać mu instrukcje wraz z danymi pierwotnymi. Przykładowa instrukcja systemowa, która pozwoli to osiągnąć, może wyglądać tak:

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

Powyższe instrukcje systemowe informują Gemini, jakich danych oczekiwać i jakie są oczekiwane dane wyjściowe modelu AI. Zawierają też prośbę o wygenerowanie danych wyjściowych w formacie JSON.

Uporządkowane dane wyjściowe

Poprosiliśmy Gemini o wygenerowanie wyniku w formacie JSON, ale musimy dokładniej określić strukturę danych wyjściowych, aby wiedzieć, czego się spodziewać, gdy będziemy wysyłać do niego zapytania za pomocą kodu. W tym celu możemy dodać do żądania dodatkową instrukcję danych wyjściowych w formacie strukturalnym, korzystając z pola responseSchema w interfejsie Gemini API. Używa obiektu schematu OpenAPI, aby ograniczyć dane wyjściowe modelu.

Na przykład:

{
  "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"
    ]
  }
}

W tym przykładzie prosisz Gemini o wygenerowanie tablicy JavaScript zawierającej:

• Szerokość i długość geograficzna lokalizacji
• Niestandardowy wynik lokalizacji

Korzystając z powyższych instrukcji systemowych i danych wyjściowych w formie strukturalnej, odpowiedź Gemini dla jednej lokalizacji wyglądałaby tak, gdzie score to niestandardowy wynik lokalizacji:

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

Wyświetlanie wyniku

Po wygenerowaniu niestandardowego wyniku lokalizacji dla każdego miejsca za pomocą jednej z opisanych metod można go wyświetlać obok szczegółów hotelu lub używać jako opcji filtrowania wyszukiwania. Na przykład „pokaż miejsca z wysoką oceną dla turystów”. Umożliwi to klientom podejmowanie decyzji dotyczących rezerwacji na podstawie danych.

Podsumowanie

Korzystanie z ocen lokalizacji niestandardowych może być przydatnym narzędziem, które pozwala użytkownikom szybko ocenić przydatność danego obszaru. W tym dokumencie pokazaliśmy, jak generować niestandardowe oceny lokalizacji dla różnych miejsc przy użyciu 5 osobnych typów miejsc. Tę implementację można zmodyfikować zgodnie z potrzebami. Podobne typy miejsc można połączyć w jednym żądaniu, aby uzyskać zagregowaną liczbę tych typów i przekazać ją do niestandardowego rozwiązania do oceny lokalizacji.

Wypróbuj już dziś interfejs Places Aggregate API, aby generować przydatne wyniki lokalizacji, które pomogą Twoim klientom podejmować świadome decyzje oparte na lokalizacji.

Współtwórcy

Henrik Valve | Inżynier DevX