שימוש ב-Places Aggregate API כדי ליצור דירוג מיקום מותאם אישית

מטרה

למצוא את המיקום האידיאלי, בין אם זה מלון לחופשה הקרובה או דירה שמתאימה למשפחות, זה תהליך מייגע של השוואה בין אפשרויות רבות. מה אם הייתה לך אפשרות להקל על המשתמשים שלך באמצעות מדד מותאם אישית שמראה את מידת ההתאמה של מלון לתיירים, או לדרג רשימות של דירות לפי מידת ההתאמה שלהן למשפחות, וכך להפוך משימה מייגעת להחלטה פשוטה.

במסמך הזה מוסבר איך להשתמש ב-Places Aggregate API כדי ליצור ציוני מיקום דינמיים בהתאמה אישית, על סמך צפיפות המקומות באזור גיאוגרפי מוגדר. הציון, שהוא דירוג מספרי לפי הקריטריונים שציינתם, יציג באופן מיידי את מידת ההתאמה של המיקום לצרכים שלכם.

נניח שאתם מקדמים מלונות בעיר מסוימת ורוצים להבליט את המלונות שנמצאים באזורים התיירותיים האטרקטיביים ביותר. לשם כך, אתם יוצרים ציון של 'מתאים לתיירים'. משתמשים ב-Places Aggregate API כדי לספור כמה סוגי מקומות רלוונטיים נמצאים ליד כל מלון. לדוגמה, אתם יודעים שהלקוחות שלכם מעריכים מלונות במיקומים שקרובים למספר מקומות מהרשימה הבאה:

• מסעדות ובתי קפה
• פארקים ומוזיאונים
• חנויות בגדים

אפשר להחיל משקלים של חשיבות על ספירת סוגי המקומות שנבחרו, כדי לחשב ציון כולל לכל מיקום של מלון. הציון משקף את ההתאמה הכוללת של המיקום, על סמך המקומות הסמוכים. המשקלים שמוקצים לכל סוג מקום צריכים להתאים לתרחיש השימוש הספציפי שלכם ולמה שחשוב לקהל היעד שלכם. במסמך הזה נשתמש בציון מתאים לתיירים כדוגמה העיקרית, אבל אפשר ליצור ציון שישקף את הנתונים הדמוגרפיים והצרכים של המשתמשים שלכם.

דרישות מוקדמות

לפני שקוראים את המסמך הזה, מומלץ לקרוא את המאמרים הבאים:

• מסמכי התיעוד למפתחים של Places Aggregate API כדי להבין את הפרטים הטכניים ואת הפרמטרים הזמינים.
• [אופציונלי] מסמכי התיעוד למפתחים של Gemini Developer API כדי להבין איך קוראים ל-Gemini באמצעות API. ה-API הזה משמש במסמך הזה כאפשרות ליצירת ניקוד מותאם אישית למיקום.

הדגמה (דמו)

בהדגמה הזו מוצגת דוגמה לשימוש בציוני מיקום בהתאמה אישית. בוחרים עיר מהתפריט הנפתח ולוחצים על הלחצן חישוב ניקוד מותאם אישית כדי להציג את הניקוד המותאם אישית של חמישה מיקומים שאוכלסו מראש.

בחירה של סוגי מקומות רלוונטיים

השלב הראשון ביצירת ניקוד מיקום מותאם אישית הוא לבחור מתוך טבלה א' את סוגי המקומות שרלוונטיים ללקוחות שלכם. אנחנו יוצרים ציון מתאים לתיירים, ולכן בחרנו את סוגי המקומות הבאים שתיירים ירצו להיות בקרבתם במהלך השהייה שלהם:

• מסעדה
• פארק
• clothing_store
• מוזיאון
• coffee_shop

לאחר מכן, מקצים משקל לכל אחד מסוגי המקומות האלה, שמשקף את החשיבות היחסית שלו בציון הסופי. המשקלים צריכים להיקבע על סמך מה שהכי חשוב לתרחיש לדוגמה ולהעדפות של המשתמשים. בדוגמה הזו, סולם המשקלים יהיה בין 0 ל-1, באופן הבא:

קריאה ל-Places Aggregate API

אחרי שיש לכם רשימה של סוגי מקומות שמעניינים אתכם, השלב הבא הוא לשלוח קריאה ל-Places Aggregate API.

‫Places Aggregate API דורש מסנן מיקום. בדוגמה הזו, משתמשים ב-circle, עם המרכז latLng שהוא המיקום של המלון, ועם radius של 500 מ'. כדאי גם להגדיר את ratingFilter כך שיחזיר מקומות עם דירוג בין 3.8 ל-5, ולהחריג מהספירה מקומות עם דירוג נמוך יותר.

כדאי להתנסות בשינוי ההגדרות של מסנן המיקום בתרחיש הספציפי שלכם. לדוגמה, יכול להיות שתרצו להגדיל את הרדיוס כדי לכלול מקומות שנמצאים במרחק גדול יותר ממרכז קו הרוחב וקו האורך. אפשר גם להשתמש בשיטה אחרת להגדרת אזור החיפוש, למשל אזור או אזור מותאם אישית.

כדאי לעיין בקטע בנושא מסנן המיקומים במאמרי העזרה של Places Aggregate API כדי להכיר את האפשרויות הזמינות.

שולחים קריאה ל-Call Places Aggregate API לכל סוג מקום ומיקום שרוצים ליצור עבורם ניקוד מותאם אישית. לדוגמה, כדי להתקשר למסעדה מסוג Place Type באחד מהמלונות שלכם:

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

אחרי שכל הקריאות ל-API הושלמו, הנתונים שמתקבלים לגבי כל מיקום נראים כך:

יצירת ניקוד מותאם אישית למיקום

עכשיו יש לכם את מספר המקומות ואת המשקל של כל סוג מקום בכל מיקום, ואתם יכולים ליצור את ציון המיקום המותאם אישית. בקטע הזה נדון בשתי אפשרויות: שימוש באלגוריתם מקומי או שימוש ב-Gemini Developer API.

אפשרות 1: שימוש באלגוריתם

האפשרות הראשונה שנסביר עליה היא שימוש באלגוריתם מקומי כדי ליצור ציון על סמך המשקלים והספירות של כל סוג מקום. נרמול הציון הזה לסולם של 0 עד 5, שבו ערכים גבוהים יותר מציינים אזור אטרקטיבי יותר על סמך הקריטריונים שלכם. בדוגמה הזו, צריך ליצור שני אובייקטים של 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
    }
    

כדי ליצור ניקוד מהספירות ומהמשקלים, מכפילים את itemCounts ב-typeWeights ומוסיפים את התוצאות לניקוד הכולל weightedCount:

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

בדוגמה הזו, הפלט של השלב הזה הוא: 78.3.

עכשיו אפשר להשתמש בנרמול לוגריתמי כדי ליצור את הציון הסופי של המיקום הזה בסולם שבין 0 ל-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));

בדוגמה הזו, הפלט של הניקוד הסופי הוא: 4.36 (מעוגל לשני מקומות אחרי הנקודה העשרונית).

אפשרות 2: שימוש ב-Gemini Developer API

במקום להשתמש באלגוריתם מקומי, אפשר להשתמש ב-Gemini Developer API כדי לחשב את ציון המיקום המותאם אישית לכל המיקומים. פשוט מספקים את נתוני הספירה והמשקל עם הוראות למערכת לגבי כל המיקומים של המלונות.

השיטה הזו שימושית במיוחד אם יש לכם מידע מדויק שאתם רוצים לכלול בחישוב, כמו:

• תיאורי טקסט לכל מיקום של מלון, למשל: "המיקום הזה מתאים למשפחות, ובלילה האזור שקט".
• מידע על המשתמש, כמו: "המשתמש הזה מזמין בשביל המשפחה שלו והוא מעדיף אזור שקט במיקום מרכזי".

‫Gemini Developer API יכול להבין את הנתונים האיכותיים האלה ולכלול אותם בחישוב, וכך להפיק ציון מתוחכם ורלוונטי יותר מאשר ציון שמבוסס על גישה מתמטית בלבד.

באמצעות Gemini Developer API, בנוסף לטבלת סוג המקום והמשקלים שלמעלה, אפשר לקבל נתוני תיאור לכל מיקום שנראים כך:

אפשר לכלול בהנחיה ל-Gemini את התיאורים האיכותיים האלה, יחד עם פרטי המשתמש או ההעדפות שלו.

הוראות מערכת

כדי ש-Gemini יידע שהוא צריך ליצור ניקוד לכל מיקום על סמך נקודות הנתונים שסיפקתם, אתם צריכים לתת לו הוראות ולספק לו את הנתונים הגולמיים. דוגמה להוראת מערכת להשגת המטרה הזו:

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

ההוראות למערכת שלמעלה מאפשרות ל-Gemini לדעת אילו נתונים צפויים, ומה הפלט הצפוי ממודל ה-AI. ההוראות כוללות גם בקשה לפלט בפורמט JSON.

פלט מובנה

ביקשנו מ-Gemini להציג את התוצאה בפורמט JSON, אבל אנחנו צריכים להיות יותר ספציפיים לגבי מבנה הפלט, כדי לדעת למה לצפות כשנשאל אותו שאילתה באמצעות קוד. לשם כך, אפשר להוסיף לבקשה הוראה נוספת של פלט מובנה באמצעות השדה responseSchema ב-Gemini API. הוא משתמש באובייקט סכימה של OpenAPI כדי להגביל את פלט המודל.

לדוגמה:

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

בדוגמה הזו, מבקשים מ-Gemini ליצור מערך JavaScript עם הנתונים הבאים:

• קו רוחב וקו אורך של המיקום
• ציון המיקום המותאם אישית

בהתאם להוראות המערכת ולפלט המובנה שלמעלה, התשובה מ-Gemini לגבי מיקום אחד תיראה כך, כאשר score הוא ציון המיקום המותאם אישית:

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

הצגת הציון

אחרי שיוצרים את ציון המיקום המותאם אישית לכל מיקום באמצעות אחת מהשיטות שמתוארות כאן, אפשר להציג אותו לצד פרטי המלון או להשתמש בו כאפשרות סינון בחיפוש. לדוגמה, "show me places with a high good for tourists score" (הצגת מקומות עם ציון גבוה של מתאים לתיירים). כך הלקוחות יוכלו לקבל החלטות שמבוססות על נתונים כשהם מזמינים.

סיכום

שימוש בציונים מותאמים אישית של מיקומים יכול להיות כלי יעיל שיאפשר למשתמשים לקבל סקירה מהירה של מידת ההתאמה של אזור מסוים. במסמך הזה הדגמנו איך ליצור ציוני מיקום מותאמים אישית למיקומים שונים באמצעות חמישה סוגים נפרדים של מקומות. אפשר לשנות את ההטמעה הזו בהתאם לצרכים שלכם, ואפשר לשלב סוגים דומים של מקומות בבקשה אחת כדי לקבל את הספירה המצטברת של הסוגים האלה, ולספק אותה לפתרון המותאם אישית שלכם לדירוג מיקומים.

כדאי לנסות כבר היום את Places Aggregate API כדי ליצור ציוני מיקום שיעזרו ללקוחות שלכם לקבל החלטות מושכלות לגבי מיקומים.

תורמים

Henrik Valve | DevX Engineer