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

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

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

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

• שאילתה

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

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

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

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

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

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

  הבקשה נדחית עם שגיאה מסוג INVALID_REQUEST אם:

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

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

• מדינות

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

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

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

• היסט קלט

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

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

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

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

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

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

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

  • הגבלת מיקום

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

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

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

• קוד אזור

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

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

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

בדוגמה הבאה מצוין מחרוזת שאילתה של 'Soccer', והיא משתמשת בפרמטר 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 והשיוכים.