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

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

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

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

• שאילתה

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

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

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

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

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

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

  הבקשה נדחית ותוצג השגיאה INVALID_REQUEST אם:

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

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

• מדינות

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

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

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

• היסט קלט

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

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

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

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

  • הטיית מיקום

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

    כדי להגדיר את הפרמטר של הטיית המיקום, קוראים לשיטה setLocationBias() כשמפתחים את האובייקט FindAutocompletePredictionsRequest.

  • הגבלת מיקום

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

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

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

  • מעגל מוגדר לפי נקודת המרכז והרדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50,000.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 ("דומיין ברמה העליונה"). רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא 'uk' (.co.uk) ואילו קוד ISO 3166-1 הוא 'gb' (טכנית לישות 'בריטניה וצפון אירלנד').

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

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

• אסימון הסשן

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

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

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

הדוגמה הבאה מציינת את מחרוזת השאילתה "Soccer" ומשתמשת בפרמטר של הסוגים הראשיים כדי להגביל את התוצאות למקומות מסוג "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());
        })
    );

אם משמיטים את הפרמטר הראשי של הסוגים, התוצאות עשויות לכלול ישויות מסוג שאתם לא רוצים לכלול, כמו "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 וייחוסים.