Tworzenie niestandardowego wyniku lokalizacji za pomocą interfejsu Places Aggregate API

Cel

Znajdowanie idealnego miejsca, czy to hotelu na nadchodzące wakacje, czy mieszkania przystosowanego do potrzeb rodzin, często wiąże się z frustrującym i czasochłonnym procesem porównywania wielu opcji. Co jeśli ułatwisz to użytkownikom, udostępniając im niestandardowe dane, które pokazują, czy hotel jest odpowiedni dla turystów, lub oceniają apartamenty pod kątem przyjaznego dla rodzin charakteru, dzięki czemu żmudne zadanie staje się łatwym wyborem?

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. Ocena, czyli ranking liczbowy uwzględniający określone przez Ciebie kryteria, od razu poinformuje użytkowników, jak dobrze dana lokalizacja odpowiada ich potrzebom.

Wyobraź sobie, że promujesz hotele w mieście i chcesz wyróżnić te, które znajdują się w najbardziej atrakcyjnych miejscach turystycznych. Aby to zrobić, utwórz ocenę dla turystów. Użyj interfejsu Places Aggregate API, aby policzyć, ile odpowiednich typów miejsc znajduje się w pobliżu każdego hotelu. Możesz na przykład wiedzieć, że Twoi klienci cenią sobie hotele w lokalizacjach znajdujących 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ólną ocenę dla każdej lokalizacji hotelu. Wynik odzwierciedla ogólną przydatność lokalizacji na podstawie pobliskich miejsc. Wagi przypisane do poszczególnych typów miejsc powinny być dostosowane do konkretnego przypadku użycia i do tego, co jest ważne dla Twoich odbiorców docelowych. W tym dokumencie jako przykładu użyjemy oceny dobrej dla turystów, ale możesz utworzyć własną ocenę, która będzie odzwierciedlać demografię i potrzeby użytkowników.

Wymagania wstępne

Przed przeczytaniem tego dokumentu zalecamy zapoznanie się z tą dokumentacją:

• Zapoznaj się z dokumentacją dla programistów dotyczącą interfejsu Places Aggregate API, aby poznać szczegóły techniczne i dostępne parametry.
• [Opcjonalnie] Zapoznaj się z dokumentacją interfejsu API dla deweloperów Gemini, aby dowiedzieć się, jak wywoływać Gemini za pomocą interfejsu API. W tym dokumencie interfejs ten jest używany jako opcja generowania niestandardowego wyniku lokalizacji.

Prezentacja

Ten pokaz przedstawia przykład działania niestandardowego wyniku lokalizacji. W menu kliknij nazwę miasta i kliknij przycisk Oblicz wynik niestandardowy, aby wyświetlić wynik niestandardowej lokalizacji dla 5 wstępnie wypełnionych lokalizacji.

Wybierz odpowiednie typy miejsc

Pierwszym krokiem do utworzenia wyniku lokalizacji niestandardowej jest określenie typów miejsc, które są istotne dla Twoich klientów (patrz tabela A). Ponieważ tworzymy wynik doskonały dla turystów, wybraliśmy te typy miejsc, w pobliżu których turyści chcą się zatrzymać podczas pobytu:

• restauracja
• park
• clothing_store
• muzeum
• coffee_shop

Następnie przypisz wagę każdemu z tych typów miejsc, odzwierciedlającą ich względną ważność w ogólnej ocenie. Wagi należy określić na podstawie tego, co jest najważniejsze w przypadku danego zastosowania i preferencji użytkownika. W tym przykładzie skala wagowa będzie się mieścić w zakresie od 0 do 1:

Wywoływanie interfejsu Places Aggregate API

Gdy już masz listę interesujących Cię typów miejsc, 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 punkt centralny latLng to lokalizacja 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 o niższej ocenie.

Eksperymentuj z różnymi ustawieniami filtra lokalizacji w przypadku konkretnego przypadku użycia. Możesz na przykład uwzględnić miejsca w większym promieniu od współrzędnych geograficznych centrum, zwiększając wartość promienia. Możesz też użyć innej metody do ustawienia obszaru wyszukiwania, takiej jak Region lub Niestandardowy.

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

Wywołaj interfejs Places Aggregate API w przypadku każdego typu miejsca i lokalizacji, dla których chcesz wygenerować niestandardową ocenę. 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 masz dane o każdej lokalizacji w takim formacie:

Generowanie niestandardowego wyniku lokalizacji

Teraz, gdy masz liczbę miejsc i wagę dla każdego typu miejsca w przypadku każdej lokalizacji, możesz wygenerować niestandardową ocenę lokalizacji. W tej sekcji omówimy 2 opcje: korzystanie z lokalnego algorytmu lub z interfejsu API dla programistów Gemini.

Opcja 1. Użyj algorytmu

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

    {
      "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 wynik tego kroku to 78, 3.

Teraz możesz użyć normalizacji logarytmicznej, aby wygenerować ostateczną ocenę dla tej lokalizacji na 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ąglone do 2 miejsc po przecinku).

Opcja 2. Użyj interfejsu Gemini Developer API

Jako alternatywę dla algorytmu lokalnego Gemini Developer API oferuje skuteczny sposób na obliczenie niestandardowej oceny lokalizacji dla wszystkich lokalizacji. Wystarczy, że podasz liczbę i dane dotyczące wag wraz z instrukcjami systemu dla wszystkich lokalizacji hoteli.

Ta metoda jest szczególnie przydatna, jeśli masz do uwzględnienia w obliczeniach informacje o różnym stopniu szczegółowości, np.:

• Opis tekstowy każdego hotelu, np. „Ta lokalizacja jest odpowiednia dla rodzin, a w nocy panuje w niej cisza”.
• informacje o użytkowniku, np.: „Ten użytkownik rezerwuje pokój dla rodziny i preferuje spokojną okolicę w centrum miasta”;

Interfejs API dla deweloperów Gemini może analizować te dane jakościowe i uwzględniać je w wycenie, co pozwala uzyskać bardziej zaawansowany i trafny wynik niż w przypadku podejścia czysto matematycznego.

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

Te jakościowe opisy wraz z informacjami o użytkownikach lub preferencjami mogą być uwzględnione w promptach dla Gemini.

Instrukcje systemowe

Gemini wymaga instrukcji wraz z danymi nieprzetworzonymi, aby wiedzieć, że ma generować wynik dla każdej lokalizacji na podstawie podanych punktów danych. Przykładowe instrukcje systemu umożliwiające wykonanie tej czynności:

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 systemu pozwalają Gemini wiedzieć, jakich danych się spodziewać i jakie dane wyjściowe oczekuje od modelu AI. System prosi też o dane wyjściowe w formacie JSON.

Uporządkowane dane wyjściowe

Chociaż poprosiliśmy Gemini o wydanie wyniku w formacie JSON, musimy bardziej sprecyzować strukturę danych wyjściowych, aby wiedzieć, czego się spodziewać, gdy wyślemy zapytanie za pomocą kodu. W tym celu możemy dodać do żądania dodatkowe instrukcje dotyczące ustrukturyzowanego responseSchema w interfejsie Gemini API. Do ograniczania danych wyjściowych modelu używa się obiektu schematu OpenAPI.

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 żądamy, aby Gemini zwrócił tablicę JavaScript z tymi elementami:

• Szerokość i długość geograficzna lokalizacji
• Wynik lokalizacji niestandardowej

Na podstawie powyższych instrukcji systemowych i ustrukturyzowanego wyjścia odpowiedź Gemini dla jednej lokalizacji wyglądałaby tak: score to niestandardowa ocena lokalizacji:

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

Wyświetlanie wyniku

Po wygenerowaniu niestandardowej oceny lokalizacji dla każdej lokalizacji za pomocą jednej z opisanych metod możesz wyświetlać ją obok informacji o hotelu lub używać jako opcji filtrowania wyszukiwania. Na przykład „pokaż miejsca z wysokim wynikiem dla turystów”. Dzięki temu Twoi klienci będą mogli podejmować decyzje dotyczące rezerwacji na podstawie danych.

Podsumowanie

Oceny niestandardowych lokalizacji mogą być przydatnym narzędziem, które pozwala użytkownikom szybko sprawdzić, czy dana lokalizacja jest odpowiednia. W tym dokumencie pokazano, jak generować własne wyniki lokalizacji dla różnych lokalizacji za pomocą 5 oddzielnych typów miejsc. To rozwiązanie można zmodyfikować, aby dostosować je do swoich potrzeb. Podobne typy miejsc można połączyć w jednym żądaniu, aby zwrócić ich łączną liczbę i przekazać je do niestandardowego rozwiązania do obliczania oceny lokalizacji.

Wypróbuj interfejs Places Aggregate API, aby generować przydatne wyniki dotyczące lokalizacji, które pomogą Twoim klientom podejmować świadome decyzje dotyczące lokalizacji.

Współtwórcy

Henrik Valve | DevX Inżynier