דף זה תורגם על ידי Cloud Translation API.

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

מטרה

תמונה

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

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

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

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

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

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

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

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

הדגמה (דמו)

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

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

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

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

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

סוג המקום	שקלול
מסעדה	0.8
פארק	0.6
clothing_store	0.3
מוזיאון	0.2
coffee_shop	0.5

Call Places Aggregate API

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

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

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

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

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

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, הנתונים בכל מיקום ייראו כך:

סוג המקום	שקלול	כמות
מסעדה	0.8	56
פארק	0.6	3
clothing_store	0.3	32
מוזיאון	0.2	8
coffee_shop	0.5	41

יצירת דירוג המיקום המותאם אישית

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

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

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

itemCounts	typeWeights
{ "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 מציע דרך יעילה לחשב את דירוג המיקום המותאם אישית לכל המיקומים. פשוט מספקים את נתוני המספר והמשקל עם הוראות למערכת לכל מיקומי המלונות.

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

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

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

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

מיקום	תיאור
51.49884, -0.17978	מיקום מרכזי קרוב למוזיאונים, שקט בלילה ומתאים למשפחות.
51.51750, -0.13065	מיקום מרכזי קרוב לברים ולמסעדות. מקום רועש ותוסס בלילה, מתאים לקבוצות.
51.45712, 0.01146	מיקום מגורים רחוק ממרכז העיר.
51.51271, -0.09933	מיקום מרכזי קרוב לנהר. שקט בלילה ומתאים למשפחות.
51.58502, -0.06445	מיקום מגורים רחוק ממרכז העיר.

אפשר לכלול את התיאורים האיכותיים האלה, יחד עם כל מידע או העדפות של משתמשים, בהנחיה ל-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