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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

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

התגובה מ-API להשלמה אוטומטית (חדש) יכולה להכיל שני סוגים של החיזויים:

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

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

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

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

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

API Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות API:

רוצים לנסות?

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

בקשת השלמה אוטומטית (חדש) היא בקשת HTTP POST לכתובת URL ב- הטופס:

https://places.googleapis.com/v1/places:autocomplete

העברה של כל הפרמטרים בגוף הבקשה של JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

מידע על התשובה

השלמה אוטומטית (חדש) מחזירה אובייקט JSON כתגובה. בתשובה:

• מערך suggestions מכיל את כל המקומות והשאילתות החזויים לפי הסדר על סמך מידת הרלוונטיות שבה הם נתפסו. כל מקום מיוצג על ידי השדה placePrediction וכל שאילתה מיוצגת בשדה queryPrediction.
• שדה placePrediction מכיל מידע מפורט על חיזוי של מקום, כולל מזהה המקום ותיאור טקסט.
• שדה queryPrediction מכיל מידע מפורט על נוכל לחזות את השאילתה.

הערה: ההשלמה האוטומטית (חדש) מחזירה חמישה חיזויים בסך הכול, בתור placePredictions, queryPredictions, או שילוב של שניהם, בהתאם לבקשה. לדוגמה, אם הבקשה כוללת לא מוגדר includeQueryPredictions, גוף התגובה כולל עד חמש placePredictions. אם הבקשה מגדירה את הערך includeQueryPredictions, גוף התשובה כולל עד חמישה חיזויים בשילוב של placePredictions ו-queryPredictions.

אובייקט ה-JSON המלא מופיע בתבנית:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

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

• קלט

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

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

• includedPrimaryTypes

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

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

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

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

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

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

• includeQueryPredictions

  אם הערך שלו הוא true, התשובה תכלול גם חיזויים של מקומות וגם של שאילתות. ברירת המחדל הוא false, כלומר התשובה כוללת רק חיזויים לגבי מקומות.

• includedRegionCodes

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

      "includedRegionCodes": ["de", "fr"]

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

• inputOffset

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

  הערה: בגרסה הראשונית של 'תצוגה מקדימה פרטית' נקרא הנכס predictionTermOffset.

• languageCode

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

  • צריך להשתמש ב-IETF קודי שפה מסוג BCP-47 כדי לציין את השפה המועדפת.
  • אם לא תספקו את languageCode, ה-API ישתמש בערך שצוין הכותרת Accept-Language. אם לא צוין אף אחד מהם, ברירת המחדל היא en אם מציינים קוד שפה לא חוקי, ה-API יחזיר קוד שפה לא חוקי. שגיאה אחת (INVALID_ARGUMENT).
  • לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות ה-API בוחר להחזיר, ואת הסדר שבו הן מוחזרות. תהיה לכך גם השפעה על היכולת של ה-API לתקן שגיאות איות.
  • ממשק ה-API מנסה לספק כתובת רחוב שניתנת לקריאה גם עבור המשתמש וגם עבור האוכלוסייה המקומית, ובמקביל לשקף את הקלט של המשתמשים. חיזויים לגבי מקומות בפורמט שונה בהתאם לקלט של המשתמשים בכל בקשה.
    • קודם כל צריך לבחור מונחים תואמים בפרמטר input, כשהשמות יהיו מיושרים עם העדפת השפה שצוינה בפרמטר languageCode, זמין, ובמקרים אחרים משתמשים בשמות שהכי מתאימים לקלט של המשתמש.
    • כתובות של רחובות מעוצבות בשפה המקומית, בסקריפט שהמשתמש יכול לקרוא כשהדבר אפשרי, רק לאחר שנבחרו המונחים התואמים את המונחים הפרמטר input.
    • כל שאר הכתובות מוחזרות בשפה המועדפת, לאחר שהמונחים התואמים נבחר להתאים למונחים בפרמטר input. אם אין שם בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.

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

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

  הערה: אם משמיטים גם את locationBias וגם את locationRestriction, ה-API משתמש בהטיה של כתובות IP כברירת מחדל. בעזרת הטיית IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.

  • locationBias

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

  • locationRestriction

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

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

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

    לדוגמה:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

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

    לדוגמה, אזור התצוגה הזה כולל את כל העיר תל אביב:

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

• מקור

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

  "origin": {
      "latitude": 40.477398,
      "longitude": -74.259087
  }

• regionCode

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

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

• sessionToken

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

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

שימוש בהגבלת מיקום וב-locationBias

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

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

curl -X POST -d '{
  "input": "Amoeba",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

כל התוצאות מתוך האזורים שצוינו כלולות במערך suggestions:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

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

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

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

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

שימוש ב-includePrimaryTypes

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

בדוגמה הבאה מציינים את המחרוזת input של 'כדורגל' ולהשתמש בפרמטר includedPrimaryTypes כדי להגביל את התוצאות ל- מוסדות מסוג "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

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

בקשת חיזויים של שאילתות

כברירת מחדל, שאילתות החיפוש החזויות לא מוחזרות. שימוש בincludeQueryPredictions של הבקשה להוסיף חיזויים של שאילתות לתשובה. לדוגמה:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

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

הערה: שאילתות חזויות לא מוחזרות כאשר הוגדר הפרמטר includedRegionCodes.

שימוש במקור

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

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

התגובה כוללת עכשיו distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

נסה בעצמך!

API Explorer מאפשר לכם לשלוח בקשות לדוגמה שתכירו את ה-API ואת האפשרויות של ה-API.

1. לוחצים על סמל ה-API, , בצד שמאל של הדף.
2. אפשר להרחיב את הקטע הצגת פרמטרים רגילים ולהגדיר הפרמטר fields ל-field mask.
3. אפשר לערוך את גוף הבקשה.
4. לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לשליחת הבקשה.

5. בחלונית של API Explorer לוחצים על סמל ההרחבה. , כדי להרחיב את החלון של API Explorer.