Mit der Places Aggregate API einen benutzerdefinierten Standortbewertungswert erstellen

Ziel

Die Suche nach der idealen Unterkunft, sei es ein Hotel für den nächsten Urlaub oder eine familienfreundliche Wohnung, ist oft frustrierend und zeitaufwendig, da zahlreiche Optionen verglichen werden müssen. Stellen Sie sich vor, Sie könnten Ihren Nutzern die Entscheidung erleichtern, indem Sie einen benutzerdefinierten Messwert bereitstellen, der die Eignung eines Hotels für Touristen aufzeigt, oder Apartmentangebote nach ihrer Familienfreundlichkeit einstufen. So wird eine mühsame Aufgabe zu einer mühelosen Entscheidung.

In diesem Dokument wird beschrieben, wie Sie mit der Places Aggregate API dynamische, benutzerdefinierte Standortbewertungen basierend auf der Dichte von Orten in einem definierten geografischen Gebiet generieren. Die Punktzahl, eine numerische Rangfolge anhand Ihrer angegebenen Kriterien, gibt sofort Aufschluss darüber, wie geeignet der Standort für ihre Anforderungen ist.

Angenommen, Sie bewerben Hotels in einer Stadt und möchten die Hotels in den attraktivsten Touristengebieten hervorheben. Dazu erstellen Sie einen Score für Touristen. Mit der Places Aggregate API können Sie zählen, wie viele relevante Ortsarten sich in der Nähe der einzelnen Hotels befinden. Sie wissen beispielsweise, dass Ihre Kunden Hotels in der Nähe der folgenden Orte schätzen:

• Restaurants und Cafés
• Parks und Museen
• Bekleidungsgeschäfte

Wenn Sie den Anzahlwerten dieser ausgewählten Ortstypen Gewichtungen zuweisen, können Sie eine Gesamtpunktzahl für jeden Hotelstandort berechnen. Die Punktzahl spiegelt die allgemeine Eignung des Standorts basierend auf den Orten in der Nähe wider. Die Gewichtungen, die den einzelnen Ortstypen zugewiesen werden, sollten auf Ihren spezifischen Anwendungsfall und die Interessen Ihrer Zielgruppe abgestimmt sein. In diesem Dokument wird der Wert Gut für Touristen als Hauptbeispiel verwendet. Ihr Wert kann jedoch so erstellt werden, dass er Ihre Nutzerdemografie und -anforderungen widerspiegelt.

Vorbereitung

Bevor Sie dieses Dokument lesen, sollten Sie sich mit der folgenden Dokumentation vertraut machen:

• Entwicklerdokumentation zur Places Aggregate API mit technischen Details und verfügbaren Parametern.
• [Optional] Gemini Developer API-Entwicklerdokumentation, um zu verstehen, wie Gemini über eine API aufgerufen wird. Sie wird in diesem Dokument als Option zum Generieren des benutzerdefinierten Standortscores verwendet.

Demo

In dieser Demo sehen Sie ein Beispiel für die benutzerdefinierte Standortbewertung in Aktion. Wählen Sie eine Stadt aus dem Drop-down-Menü aus und klicken Sie auf die Schaltfläche Benutzerdefinierten Score berechnen, um den benutzerdefinierten Standort-Score für fünf vorab ausgefüllte Standorte aufzurufen.

Relevante Ortstypen auswählen

Als Erstes müssen Sie die Orte aus Tabelle A auswählen, die für Ihre Kunden relevant sind. Da wir eine gut für Touristen-Bewertung erstellen, haben wir die folgenden Ortstypen ausgewählt, in deren Nähe sich Touristen während ihres Aufenthalts aufhalten möchten:

• Restaurant
• Park
• Bekleidungsgeschäft
• Museum
• coffee_shop

Weisen Sie als Nächstes jedem dieser Ortstypen eine Gewichtung zu, die seine relative Bedeutung für die endgültige Punktzahl widerspiegelt. Die Gewichtungen sollten auf Grundlage dessen festgelegt werden, was für Ihren Anwendungsfall und die Präferenzen Ihrer Nutzer am wichtigsten ist. In diesem Beispiel liegt die Gewichtungsskala zwischen 0 und 1:

Places Aggregate API aufrufen

Nachdem Sie eine Liste der gewünschten Ortstypen haben, rufen Sie als Nächstes die Places Aggregate API auf.

Für die Places Aggregate API ist ein Standortfilter erforderlich. Verwenden Sie für dieses Beispiel circle, wobei der Mittelpunkt latLng der Standort Ihres Hotels und radius 500 m ist. Legen Sie außerdem ratingFilter fest, um Orte mit einer Bewertung zwischen 3,8 und 5 zurückzugeben.Orte mit einer niedrigeren Bewertung werden nicht berücksichtigt.

Experimentieren Sie mit verschiedenen Einstellungen des Standortfilters für Ihren spezifischen Anwendungsfall. Wenn Sie beispielsweise Orte in einem größeren Umkreis um Ihren Mittelpunkt erfassen möchten, können Sie den Wert für „radius“ erhöhen. Alternativ können Sie auch eine andere Methode zum Festlegen des Suchbereichs verwenden, z. B. Region oder Benutzerdefinierter Bereich.

Machen Sie sich mit dem Abschnitt zum Standortfilter in der Dokumentation zur Places Aggregate API vertraut, um mehr über die verfügbaren Optionen zu erfahren.

Rufen Sie die Places Aggregate API für jeden Ortstyp und jeden Standort auf, für den Sie eine benutzerdefinierte Punktzahl generieren möchten. Rufen Sie beispielsweise den Ortstyp für eines Ihrer Hotels ab:

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

Nachdem alle API-Aufrufe abgeschlossen sind, haben Sie für jeden Standort Daten, die so aussehen:

Benutzerdefinierten Standort-Score erstellen

Nachdem Sie die Anzahl der Orte und die Gewichtung für jeden Ortstyp für jeden Standort haben, können Sie jetzt den benutzerdefinierten Standort-Score generieren. In diesem Abschnitt werden zwei Optionen behandelt: die Verwendung eines lokalen Algorithmus oder die Verwendung der Gemini Developer API.

Option 1: Algorithmus verwenden

Die erste Option, die wir uns ansehen, ist die Verwendung eines lokalen Algorithmus, um anhand der Gewichtungen und Anzahl für jeden Ortstyp einen Wert zu generieren. Normalisieren Sie diesen Wert auf eine Skala von 0 bis 5, wobei höhere Werte auf ein attraktiveres Gebiet basierend auf Ihren Kriterien hinweisen. Generieren Sie für dieses Beispiel zwei JavaScript-Objekte aus den obigen Daten:

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

Erstellen Sie einen Wert aus den Zählungen und Gewichtungen, indem Sie die itemCounts mit der typeWeights multiplizieren und die Ergebnisse zu einem Gesamtwert weightedCount addieren:

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

In diesem Beispiel ist die Ausgabe dieses Schritts: 78, 3.

Jetzt können Sie die logarithmische Normalisierung verwenden, um die endgültige Punktzahl für diesen Standort auf einer Skala zwischen 0 und 5 zu berechnen:

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

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

In diesem Beispiel ist die endgültige Punktzahl 4, 36 (auf zwei Dezimalstellen gerundet).

Option 2: Gemini Developer API verwenden

Als Alternative zur Verwendung eines lokalen Algorithmus bietet die Gemini Developer API eine leistungsstarke Möglichkeit, den benutzerdefinierten Standort-Score für alle Standorte zu berechnen. Geben Sie einfach die Anzahl und die Gewichtungsdaten mit Systemanweisungen für alle Ihre Hotelstandorte an.

Diese Methode ist besonders nützlich, wenn Sie detaillierte Informationen in die Berechnung einbeziehen möchten, z. B.:

• Textbeschreibungen für jede Hoteladresse, z. B. „Dieser Ort ist für Familien geeignet und die Gegend ist nachts ruhig.“
• Informationen zu Ihrem Gast, z. B.: „Dieser Gast bucht für eine Familie und bevorzugt eine ruhige Gegend in zentraler Lage.“

Die Gemini Developer API kann diese qualitativen Daten verstehen und berücksichtigen, was zu einer anspruchsvolleren und relevanteren Punktzahl führt, die über einen rein mathematischen Ansatz hinausgeht.

Wenn Sie die Gemini Developer API verwenden, können Sie zusätzlich zur oben stehenden Tabelle mit Ortstypen und Gewichtungen Beschreibungsdaten für jeden Ort abrufen, die so aussehen:

Diese qualitativen Beschreibungen können zusammen mit Nutzerinformationen oder ‑einstellungen in Ihren Prompt an Gemini aufgenommen werden.

Systemanweisungen

Gemini benötigt neben den Rohdaten auch Anweisungen, um zu wissen, dass für jeden Standort auf Grundlage der bereitgestellten Datenpunkte eine Punktzahl generiert werden soll. Eine Beispiel-Systemanweisung, um dies zu erreichen, könnte so aussehen:

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

Mit den oben genannten Systemanweisungen wird Gemini mitgeteilt, welche Daten erwartet werden und welche Ausgabe vom KI-Modell erwartet wird. Außerdem wird die Ausgabe im JSON-Format angefordert.

Strukturierte Ausgabe

Wir haben Gemini zwar gebeten, das Ergebnis in JSON auszugeben, müssen aber genauer auf die Struktur der Ausgabe eingehen, damit wir wissen, was wir erwarten können, wenn wir es mit Code abfragen. Dazu können wir der Anfrage mit dem Feld responseSchema in der Gemini API eine zusätzliche structured output-Anweisung hinzufügen. Dazu wird ein OpenAPI-Schemaobjekt verwendet, um die Modellausgabe einzuschränken.

Beispiel:

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

In diesem Beispiel wird Gemini aufgefordert, ein JavaScript-Array mit Folgendem auszugeben:

• Breiten- und Längengrad des Standorts
• Bewertung des benutzerdefinierten Standorts

Mit den oben genannten Systemanweisungen und der strukturierten Ausgabe würde die Antwort von Gemini für einen Standort so aussehen, wobei score die benutzerdefinierte Standortbewertung ist:

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

Ergebnis anzeigen

Nachdem Sie den benutzerdefinierten Standort-Score für jeden Standort mit einer der beschriebenen Methoden generiert haben, kann er neben den Details Ihres Hotels angezeigt oder als Suchfilteroption verwendet werden. Sagen Sie beispielsweise: „Zeig mir Orte mit einer hohen Punktzahl für gut für Touristen.“ So können Ihre Kunden datenbasierte Entscheidungen bei der Buchung treffen.

Fazit

Mit benutzerdefinierten Standortbewertungen können Sie Ihren Nutzern auf einen Blick einen Überblick über die Eignung eines Gebiets geben. In diesem Dokument wurde gezeigt, wie benutzerdefinierte Standortbewertungen für verschiedene Standorte mit fünf separaten Ortstypen generiert werden. Diese Implementierung kann an Ihre Anforderungen angepasst werden. Ähnliche Ortstypen können in einer Anfrage kombiniert werden, um die aggregierte Anzahl dieser Typen zurückzugeben, die Sie dann für Ihre benutzerdefinierte Lösung zur Standortbewertung verwenden können.

Testen Sie noch heute die Places Aggregate API, um aussagekräftige Standortbewertungen zu generieren, die Ihren Kunden helfen, fundierte standortbezogene Entscheidungen zu treffen.

Beitragende

Henrik Valve | DevX Engineer