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

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

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

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

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

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

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

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

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

בקשת השלמה אוטומטית (חדשה) היא בקשת 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

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

Places API תומך בממשקי ה-API הקיימים של השלמה אוטומטית והשלמה אוטומטית של שאילתות. אם אתם מכירים את ממשקי ה-API האלה, גרסת Preview של השלמה אוטומטית (חדש) מבצעת את השינויים הבאים:

  • ההשלמה האוטומטית החדשה משתמשת בבקשות HTTP POST. העברת פרמטרים בגוף הבקשה או בכותרות כחלק מבקשת HTTP POST. לעומת זאת, בממשקי ה-API הקיימים מעבירים פרמטרים של כתובות אתרים באמצעות בקשת HTTP GET.
  • התכונה החדשה של השלמה אוטומטית תומכת גם במפתחות API וגם באסימוני OAuth כמנגנון האימות.
  • תכונת ההשלמה האוטומטית החדשה תומכת רק ב-JSON כפורמט תגובה.

בטבלה הבאה מפורטים פרמטרים בממשקי ה-API הקיימים להשלמה אוטומטית ולהשלמה אוטומטית של שאילתות, ששמם או השתנה עבור 'השלמה אוטומטית' החדשה, או פרמטרים שכבר לא נתמכים.

הפרמטר הנוכחי פרמטר חדש הערות
components includedRegionCodes
language languageCode
location locationBias
ipbias אם משמיטים את locationBias וגם את locationRestriction, ה-API משתמש בתעדוף לפי IP כברירת מחדל.
offset inputOffset
radius locationBias או locationRestriction
region regionCode
stricbounds locationRestriction
sessiontoken sessionToken
types includedPrimaryTypes

מגבלות שימוש

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

אפשרויות תמיכה לגרסאות טרום-השקה

למרות ש-Google לא מחויבת לספק תמיכה בגרסאות טרום-השקה, בתכונות או בפונקציונליות של השירותים, נשקול את הבקשות בשלבי הפיתוח האלה על בסיס כל מקרה לגופו.

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

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

אם יש לך שאלות נוספות בנוגע לתכונות, ניתן לשלוח אימייל לכתובת newplacesapi@google.com.

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

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

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

אובייקט ה-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
            }]
        },
        ...
    }
  ...]
}

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

  • קלט

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

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

  • includedPrimaryTypes

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

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

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

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

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

  • includeQueryPredictions

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

  • includedRegionCodes

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

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

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

  • inputOffset

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

  • languageCode

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

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

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

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

    • locationBias

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

    • locationRestriction

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

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

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

      למשל:

      "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

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

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

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

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

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

שימוש במקור

בדוגמה הזו יש לכלול בבקשה את 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
      }
    }
  ]
}