השלמה אוטומטית (חדשה)

בחירת פלטפורמה: Android iOS JavaScript Web Service

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

לדוגמה, אפשר להפעיל את ההשלמה האוטומטית באמצעות מחרוזת שמכילה קלט חלקי של משתמש, "Sicilian piz", כשאזור החיפוש מוגבל ל-San Francisco, CA. התשובה תכלול רשימה של תחזיות למקומות שתואמים למחרוזת החיפוש ולאזור החיפוש, כמו המסעדה 'Sicilian Pizza Kitchen'.

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

בקשות להשלמה אוטומטית (חדש)

כדי לקבל מה-API של ההשלמה האוטומטית רשימה של שמות של מקומות או כתובות חזויות, אפשר לבצע קריאה ל-PlacesClient.findAutocompletePredictions() ולהעביר אובייקט מסוג FindAutocompletePredictionsRequest. בדוגמה הבאה מוצגת קריאה מלאה ל-PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

תגובות שהושלמו אוטומטית (חדשות)

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

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

  • הפונקציה getFullText(CharacterStyle) מחזירה את הטקסט המלא של תיאור מקום. זהו שילוב של הטקסט הראשי והטקסט המשני. דוגמה: מגדל אייפל, שדרת Anatole France, פריז, צרפת. בנוסף, השיטה הזו מאפשרת להדגיש את החלקים בתיאור שתואמים לחיפוש בסגנון שבחרתם, באמצעות CharacterStyle. הפרמטר CharacterStyle הוא אופציונלי. אם אתם לא צריכים הדגשה, מגדירים את הערך כ-null.
  • getPrimaryText(CharacterStyle) מחזירה את הטקסט הראשי שמתאר מקום. בדרך כלל זהו שם המקום. דוגמאות: 'מגדל אייפל' ו'רחוב Pitt‏ 123'.
  • getSecondaryText(CharacterStyle) מחזירה את הטקסט המשני של תיאור מקום. לדוגמה, אפשר להשתמש בה כשורה שנייה כשמציגים חיזויים של השלמה אוטומטית. דוגמאות: Avenue Anatole France, Paris, France ו-Sydney, New South Wales.
  • getPlaceId() מחזירה את מזהה המקום של המקום החזוי. מזהה מקום הוא מזהה טקסט שמזהה באופן ייחודי מקום מסוים. אפשר להשתמש בו כדי לאחזר את האובייקט Place מאוחר יותר. מידע נוסף על מזהי מקומות בהשלמה האוטומטית זמין במאמר פרטי מקום (חדש). למידע כללי על מזהי מקומות, ראו סקירה כללית על מזהי מקומות.
  • הפונקציה getTypes() מחזירה את רשימת סוגי המקומות שמשויכים למקום הזה.
  • הפונקציה getDistanceMeters() מחזירה את המרחק בקו ישר, במטרים, בין המקום הזה לבין נקודת המוצא שצוינה בבקשה.

פרמטרים נדרשים

  • שאילתה

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

    כדי להגדיר את פרמטר השאילתה, צריך לבצע קריאה ל-method‏ setQuery() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

פרמטרים אופציונליים

  • סוגים ראשיים

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

    למקום יכול להיות רק סוג ראשי אחד מהסוגים טבלה א' או טבלה ב שמשויכים אליו. לדוגמה, הסוג הראשי יכול להיות "mexican_restaurant" או "steak_house".

    הבקשה תידחה עם השגיאה INVALID_REQUEST אם:

    • צוינו יותר מחמישה סוגים.
    • כל סוגי הנתונים שלא מזוהים יצוינו.

    כדי להגדיר את הפרמטר של הסוגים הראשיים, צריך לבצע קריאה ל-method‏ setTypesFilter() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

  • מדינות

    הכלל הזה מאפשר לכלול רק תוצאות מרשימת המדינות שצוינו, כרשימה של עד 15 ערכים של ccTLD ('דומיין ברמה עליונה') בת שני תווים. אם השדה הזה לא יצוין, לא יחולו הגבלות על התגובה. לדוגמה, כדי להגביל את האזורים לגרמניה ולצרפת:

    אם מציינים גם את locationRestriction וגם את includedRegionCodes, התוצאות נמצאות באזור החיתוך של שתי ההגדרות.

    כדי להגדיר את הפרמטר countries, צריך לבצע קריאה ל-method‏ setCountries() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

  • היסט קלט

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

    כדי להגדיר את הפרמטר של הזזת הקלט, צריך לבצע קריאה ל-method‏ setInputOffset() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

  • הטיה לפי מיקום או הגבלת מיקום

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

    • הטיה לפי מיקום

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

      כדי להגדיר את הפרמטר של הטיית המיקום, צריך לבצע קריאה ל-method‏ setLocationBias() כשמגדירים את האובייקט FindAutocompletePredictionsRequest.

    • הגבלת מיקום

      מציין אזור לחיפוש. לא יוצגו תוצאות מחוץ לאזור שצוין.

      כדי להגדיר את הפרמטר של הגבלת המיקום, צריך לבצע קריאה ל-method‏ setLocationRestriction() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

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

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

    • מלבן הוא חלון תצוגה לפי קו הרוחב והאורך, שמיוצג על ידי שתי נקודות low ו-high שנמצאות באלכסון זו מול זו. אזור תצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבול שלו. גבולות קו הרוחב חייבים להיות בין 90 מעלות ל-90 מעלות, וגבולות קו האורך חייבים להיות בין 180 מעלות ל-180 מעלות:

      • אם low = high, אזור התצוגה מורכב מנקודה אחת.
      • אם low.longitude > high.longitude, טווח קו האורך הפוך (אזור התצוגה חוצה את קו האורך של 180 מעלות).
      • אם low.longitude = -180 מעלות ו-high.longitude = 180 מעלות, חלון התצוגה כולל את כל קוי האורך.
      • אם low.longitude = 180 מעלות ו-high.longitude = -180 מעלות, טווח קו האורך ריק.

      צריך לאכלס את השדות low ו-high, והתיבה המיוצגת לא יכולה להיות ריקה. תצוגת חלון ריקה גורמת לשגיאה.

  • מקור

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

    כדי להגדיר את פרמטר המקור, צריך לבצע קריאה ל-method‏ setOrigin() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

  • קוד אזור

    קוד האזור שמשמש לעיצוב התשובה, כולל עיצוב הכתובת, שצוין בתור ערך בן שני תווים של ccTLD ('דומיין ברמה עליונה'). רוב הקודים של TLD ברמת המדינה זהים לקודי ISO 3166-1, מלבד כמה יוצאים מן הכלל. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא ‎"uk" (‎.co.uk), והקוד שלו לפי תקן ISO 3166-1 הוא ‎"gb" (טכנית, הישות של 'בריטניה הגדולה וצפון אירלנד').

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

    כדי להגדיר את הפרמטר של קוד האזור, צריך לבצע קריאה ל-method‏ setRegionCode() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

  • טוקן לסשן

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

    המילוי האוטומטי משתמש ב-AutocompleteSessionToken כדי לזהות כל סשן. האפליקציה צריכה להעביר אסימון סשן חדש בתחילת כל סשן חדש, ואז להעביר את אותו אסימון, יחד עם מזהה מקום, בקריאה הבאה ל-fetchPlace() כדי לאחזר את פרטי המקום של המקום שבחר המשתמש.

    כדי להגדיר את הפרמטר של אסימון הסשן, צריך לבצע קריאה ל-method‏ setSessionToken() בזמן היצירה של האובייקט FindAutocompletePredictionsRequest.

    למידע נוסף, תוכלו לקרוא את המאמר אסימוני סשן.

דוגמאות להשלמה אוטומטית (חדש)

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

בהשלמה האוטומטית (החדשה) נעשה שימוש בהטיה לפי כתובת IP כברירת מחדל כדי לשלוט באזור החיפוש. כשמשתמשים בהטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות. אפשר להשתמש בהגבלת מיקום או בהטיה לפי מיקום, אבל לא בשניהם, כדי לציין אזור לחיפוש.

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

שימוש בסוגי נתונים ראשיים

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

בדוגמה הבאה מצוין מחרוזת שאילתה של 'כדורגל', והפרמטר primary types משמש להגבלת התוצאות למקומות מסוג "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

אם משמיטים את הפרמטר primary types, התוצאות יכולות לכלול מוסדות מסוג שאולי לא רוצים, כמו "athletic_field".

שימוש במקור

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

שיוכים

אפשר להשתמש בתכונה 'השלמה אוטומטית' (חדשה) גם בלי מפה. אם אתם רוצים להציג מפה, היא חייבת להיות מפות Google. כשמציגים תחזיות מהשירות 'השלמה אוטומטית (חדש)' בלי מפה, צריך לכלול את הלוגו של Google שמוצג בשורה אחת עם שדה החיפוש או התוצאות. למידע נוסף, ראו הצגת הלוגו של Google והשיוכים.