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

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

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

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

• שאילתה

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

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

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

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

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

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

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

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

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

• מדינות

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

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

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

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

• קוד אזור

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

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

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

• אסימון הסשן

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

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

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

  מידע נוסף זמין במאמר הבא: אסימונים של סשן.

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

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

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

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

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