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

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

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

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

• מדינות

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

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

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

• היסט קלט

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

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

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

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

  • הטיית מיקום

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

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

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

  כדי להגדיר את הפרמטר של קידומת האזור, צריך לקרוא לפרמטר 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());
        })
    );

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

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

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