לחפש יעדים

מפתחים באזור הכלכלי האירופי (EEA)

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

ה-method‏ SearchDestinations של Geocoding API מאפשרת לאחזר מידע מפורט על יעדים שונים על סמך קריטריונים שונים של קלט, כמו כתובת, מזהה מקום או קואורדינטות של קו רוחב וקו אורך.

בקשה לחיפוש יעדים

בקשה לחיפוש יעדים היא בקשת POST לכתובת URL בפורמט הבא:

https://geocode.googleapis.com/v4/geocode/destinations

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

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

יש 3 דרכים לציין את המיקום שבו רוצים לחפש יעד:

  • כתובת
  • מזהה מקום
  • קואורדינטות של אורך ורוחב

חיפוש יעד לפי כתובת

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

סוג השאילתה דוגמה
קואורדינטות של קווי רוחב ואורך. במקום זאת, השתמשו בשאילתת מיקום. "37.422131,-122.084801"
יותר מדי מושגים או אילוצים, כמו שמות של כמה מקומות, כבישים או ערים בשאילתה אחת "Market Street San Francisco San Jose Airport"
רכיבים של כתובת דואר שלא מיוצגים במפות Google "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
שמות של עסקים, רשתות או קטגוריות בשילוב עם מיקומים שבהם הישויות האלה לא זמינות "Tesco near Dallas, Texas"
שאילתות מעורפלות עם כמה פרשנויות "החזרת מטען"
שמות היסטוריים שכבר לא בשימוש "Middlesex United Kingdom"
רכיבים או כוונה שאינם גיאו-מרחביים "כמה סירות יש בנמל ונטורה?"
שמות לא רשמיים או שמות מותאמים אישית "The Jenga"
"The Helter Skelter"
ישויות פוליטיות גדולות (ערים, מדינות, ארצות) "New York City"
"California"
"USA"
מסלולים בלי כתובות ספציפיות "1st Ave., NYC, NY"
"I-95" 
curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

או בתור postalAddress:

curl -X POST -d '{
  "addressQuery": {
    "address": {
      "addressLines": ["601 S Bernardo Ave"],
      "locality": "Sunnyvale",
      "postalCode": "94087",
      "administrativeArea": "CA",
      "regionCode": "US"
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

בדרך כלל משתמשים בפורמט postalAddress כשמעבדים רכיבי כתובת שמתועדים בטופס HTML.

חיפוש יעד לפי מזהה מקום

כדי לאחזר יעד, אפשר לספק מזהה מקום:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

מזהי מקומות נתמכים

השיטה Search Destinations פועלת בצורה הטובה ביותר עם מזהי מקומות שמייצגים יעדים ספציפיים שאפשר לנווט אליהם. בדרך כלל יש תמיכה במזהי מקומות מסוגים כמו establishment,‏ point_of_interest,‏ premise,‏ street_address ו-subpremise. אין תמיכה במזהי מקומות שלא מייצגים מיקומים נפרדים, כמו אלה שנובעים מטווחים של כתובות (לדוגמה, "רחוב הרצל 10-20"), קטעים של מסלול בלי מספר ספציפי או Plus Codes. בנוסף, אין תמיכה במזהי מקומות של תוצאות שהשטח שלהן גדול מדי (לדוגמה, "האוקיינוס השקט").

שימוש בהשלמה אוטומטית (חדשה) עם חיפוש יעדים

כדי לוודא תאימות, צריך להשתמש ב-Autocomplete (חדש) כדי למצוא מזהי מקומות לשימוש עם Search Destinations. כשמשתמשים בהשלמה אוטומטית (חדשה), צריך לסנן את התוצאות לפי סוג באמצעות הפרמטר includedPrimaryTypes. התכונה "חיפוש יעדים" תומכת במזהי מקומות שמוחזרים על ידי ההשלמה האוטומטית (חדש) באמצעות המסנן המומלץ הבא:

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

בנוסף, לא צריך להגדיר את הדגל include_pure_service_area_businesses לערך true בבקשה של ההשלמה האוטומטית (חדש).

חיפוש יעד לפי מיקום

אפשר לחפש יעדים עם קואורדינטות של קו אורך וקו רוחב:

curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4/geocode/destinations

שימוש ב-OAuth כדי לשלוח בקשה

גרסה 4 של Geocoding API תומכת ב-OAuth 2.0 לאימות. כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לטוקן OAuth את ההיקף הנכון. ‫Geocoding API תומך בהיקפי ההרשאות הבאים לשימוש עם השיטה Destinations:

  • https://www.googleapis.com/auth/maps-platform.geocode — משתמשים בכל השיטות של Geocoding API.

אפשר גם להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform לכל השיטות של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח, אבל לא בסביבת הייצור, כי הוא היקף כללי שמאפשר גישה לכל השיטות.

מידע נוסף ודוגמאות זמינים במאמר שימוש ב-OAuth.

תגובה של חיפוש יעדים

התגובה של Search Destinations מספקת הקשר עשיר וממוקד לקהילה לגבי המיקום.

האובייקטים PlaceView בתגובה של Search Destinations (כמו primary, פריטים ב-containingPlaces ו-landmarks) משתמשים בשדות כדי לציין את סוג המקום:

  • ‫types: מערך של מחרוזות שמציינות את סוגי המקומות.
  • ‫primaryType: מחרוזת שמציינת את הסוג הראשי של המקום.

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

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

primary

המקום העיקרי שזוהה על ידי השאילתה בבקשה.

addressComponents

מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.

כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:

  • ‫types[] הוא מערך שמציין את סוג רכיב הכתובת. לרשימת הסוגים הנתמכים
  • ‫longText הוא תיאור הטקסט המלא או השם של רכיב הכתובת, כפי שהוחזר על ידי הכלי להמרת כתובות לקואורדינטות (geocoder).
  • ‫shortText הוא שם טקסטואלי מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של מדינת אלסקה יכול לכלול longText של "אלסקה" ו-shortText של "AK" באמצעות קיצור הדואר בן שתי האותיות.
  • ‫languageCode היא השפה שבה נעשה שימוש כדי לעצב את הרכיב הזה, בסימון CLDR.

containingPlaces

ישויות גדולות יותר שהיעד הראשי הוא חלק מהן (לדוגמה, קניון שמכיל חנות).

subDestinations

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

entrances

האובייקטים במערך entrances[] כוללים את השדות הבאים:

  • displayName

    אובייקט LocalizedText שמכיל שם קריא לאנשים של הכניסה (לדוגמה, "South Bernardo Avenue" או "5th Avenue"), אם הוא זמין.

  • location

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

  • entrance_tags[]

    מערך של תגי כניסה שמתארים את מאפייני הכניסה. הערך הבא נתמך:

    • "PREFERRED"

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

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

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

  • streetViewThumbnail וגם streetViewAnnotation

    פרמטרים ל-Street View Static API, שמאפשרים להציג תמונות רלוונטיות למיקומים האלה. מידע נוסף על השדות האלה

structureType

סוג המבנה שהמקום הזה מייצג.

  • POINT

    מיקום של נקודה.

  • SECTION

    חלק משנה של בניין.

  • BUILDING

    בניין.

  • GROUNDS

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

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

כל נקודת ניווט מכילה את הערכים הבאים:

  • ‫navigationPointToken הוא אסימון שמכיל את המידע על ההקשר בשדה navigationPoints. אתם יכולים לשלוח את הטוקן הזה לממשקי API של ניתוב וניווט כדי לשפר את חוויית הניתוב והנהיגה באפליקציה. מידע נוסף זמין במאמר ניתוב באמצעות טוקנים של נקודות ניווט.
  • השדה location מכיל את ערכי קו הרוחב וקו האורך של נקודת הניווט. המיקום הזה תמיד יהיה קרוב מאוד לרשת הכבישים, והוא מייצג נקודת עצירה או התחלה אידיאלית לניווט אל מקום מסוים וממנו. הנקודה מוסטת בכוונה מעט מקו האמצע של הכביש כדי לסמן בבירור את הצד של הכביש שבו המקום נמצא.
  • ‫travelModes היא רשימה של אמצעי הגעה שאפשר להגיע איתם לנקודת הניווט:
    • ‫"DRIVE" הוא אמצעי התחבורה שמתאים למסלול נסיעה.
    • ‫"WALK" הוא אמצעי ההגעה שמתאים למסלול הליכה.
  • ‫usages היא רשימה של שימושים שנתמכים בנקודת הניווט. השימושים יכולים להיות:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

לאיסוף ולהורדה, צריך להשתמש בנקודת הניווט שבה מצב הנסיעה הוא DRIVE והשימוש הוא PICKUP או DROPOFF. אם אין נקודות איסוף או הורדה, צריך להשתמש בנקודת הניווט העליונה ברכב.

  • השדה altitude_meters מכיל את הגובה של נקודת הניווט במטרים ביחס לאליפסואיד WGS-84. במקרים שבהם יש מקטעי כביש שנערמים אנכית, משתמשים בשדה altitude_meters כדי לבחור את מקטע הכביש הטוב ביותר שהמערכת תנווט אליו.

landmarks

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

כל נקודת ציון מכילה את השדות הבאים:

  • ‫place הוא האובייקט PlaceView שמייצג את נקודת הציון הזו.
  • ‫relationalDescription הוא תיאור קריא לאנשים של הקשר בין היעד לציון הדרך, למשל "ליד בניין האמפייר סטייט" או "מול הבית הלבן".
  • ‫tags[] הוא מערך של תגים שמתארים איך אפשר להשתמש בציון הדרך בהקשר של היעד:
    • "ADDRESS": מקום בולט באזור שאפשר להשתמש בו כדי לזהות את המיקום הכללי של היעד.
    • ‫"ARRIVAL": מקום שיכול לעזור להגיע ליעד, שימושי לניווט כשמתקרבים ליעד.
  • ‫straightLineDistanceMeters הוא המרחק בקו ישר מהציון הדרך הזה ליעד, במטרים.
  • ‫travelDistanceMeters הוא מרחק ההליכה במטרים מנקודת הציון הזו אל היעד.

arrivalSummary

תובנות מבוססות-AI שיעזרו לכם להגיע ליעד. סיכומים מבוססי-AI

parkingOptions

מידע מפורט על החניה.

פורמט התשובה

הפונקציה SearchDestinations מחזירה SearchDestinationsResponse בפורמט ה-JSON הבא:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }
      },
      "containingPlaces": [
        {
          "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw",
          "displayName": {
            "text": "Cherry Chase Shopping Center",
            "languageCode": "en"
          },
          "primaryType": "shopping_mall",
          "types": [
            "shopping_mall",
            "point_of_interest",
            "establishment"
          ],
          "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA",
          "postalAddress": {
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94087-1020",
            "administrativeArea": "CA",
            "locality": "Sunnyvale",
            "addressLines": [
              "663 S Bernardo Ave"
            ]
          },
          "structureType": "GROUNDS",
          "location": {
            "latitude": 37.3731231,
            "longitude": -122.0578211
          },
          "displayPolygon": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -122.057112227103,
                  37.3714618008523
                ],
                [
                  -122.057076849821,
                  37.3715743611411
                ],
                [
                  -122.056963607756,
                  37.3719081793948
                ],
                [
                  -122.056865279559,
                  37.3722026053835
                ],
                [
                  -122.056687872374,
                  37.3727258358476
                ],
                [
                  -122.056580005889,
                  37.3730511370747
                ],
                [
                  -122.056498845827,
                  37.3732994782583
                ],
                [
                  -122.056338259713,
                  37.3737878663325
                ],
                [
                  -122.056618678291,
                  37.373887693582
                ],
                [
                  -122.056912102521,
                  37.3740010327191
                ],
                [
                  -122.057532418159,
                  37.3742476426462
                ],
                [
                  -122.057673926626,
                  37.3742441740031
                ],
                [
                  -122.057735663106,
                  37.3742328516943
                ],
                [
                  -122.057766531332,
                  37.3742220604378
                ],
                [
                  -122.057797572967,
                  37.37420520725
                ],
                [
                  -122.057828267759,
                  37.3741852342085
                ],
                [
                  -122.058060299297,
                  37.3740060842535
                ],
                [
                  -122.058199726081,
                  37.3737861673422
                ],
                [
                  -122.05836707267,
                  37.373524542556
                ],
                [
                  -122.058569622393,
                  37.3732018598683
                ],
                [
                  -122.0587638478,
                  37.3728890198039
                ],
                [
                  -122.058934661823,
                  37.3726036257774
                ],
                [
                  -122.059164956851,
                  37.3722498383629
                ],
                [
                  -122.058997784906,
                  37.3721804442035
                ],
                [
                  -122.057936479838,
                  37.3717605636234
                ],
                [
                  -122.057495827092,
                  37.3715860151634
                ],
                [
                  -122.057112227103,
                  37.3714618008523
                ]
              ]
            ]
          }
        }
      ],
      "landmarks": [
        {
          "place": {
            "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg",
            "displayName": {
              "text": "Chase Bank",
              "languageCode": "en"
            },
            "primaryType": "bank",
            "types": [
              "bank",
              "atm",
              "finance",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1234 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.373579,
              "longitude": -122.05752700000001
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "639 S Bernardo Ave"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3727912,
              "longitude": -122.0581172
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "fast_food_restaurant",
              "restaurant",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1028",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1241 W El Camino Real"
              ]
            },
            "structureType": "BUILDING",
            "location": {
              "latitude": 37.3746764,
              "longitude": -122.05708860000001
            },
            "displayPolygon": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "displayName": {
            "text": "South Bernardo Avenue",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

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

  • אחד מ-3 הפרמטרים הבאים חייב להיות בבקשת ה-API, שמציינת את הכתובת, המקום או המיקום לחיפוש יעד:
    • ‫addressQuery – הכתובת שרוצים לחפש.
    • ‫place – מזהה המקום של המקום שרוצים לחפש.
    • ‫locationQuery – הקואורדינטות של קווי הרוחב והאורך של המיקום שרוצים לחפש.

  • FieldMask

    כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדות תגובה. מעבירים את מסכת השדות של התגובה ל-method באמצעות הפרמטר של כתובת ה-URL‏ $fields או fields, או באמצעות כותרת ה-HTTP‏ X-Goog-FieldMask. לדוגמה, הבקשה הבאה תחזיר רק את הכניסות, נקודות הניווט ומזהה המקום של היעד הראשי.

      curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
    -H "X-Goog-Api-Key: API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
    https://geocode.googleapis.com/v4/geocode/destinations

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

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

  • travelModes

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

  • languageCode

    השפה שבה התוצאות יוחזרו.

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

  • regionCode

    קוד האזור, שמוגדר כערך קוד CLDR באורך שני תווים. אין ערך ברירת מחדל. רוב קודי ה-CLDR זהים לקודי ISO 3166-1.

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

  • placeFilter

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

    סינון לפי רמת הפירוט של המבנה

    המסנן structureType מאפשר לציין את סוג המבנים שמוחזרים על ידי השאילתה:

    • בידוד מבנים: אפשר להשתמש ב-"structureType": "BUILDING" כדי להציג קווי מתאר של מבנים במפה או לקבל פרטים על מבנה ספציפי.
    • הבנת מתחמים: משתמשים ב-"structureType": "GROUNDS" כדי לוודא שהתוצאה הראשית היא המתחם כולו. האפשרות הזו שימושית כששולחים שאילתות לגבי אזורים גדולים יותר, כמו קמפוסים של אוניברסיטאות או קניונים.
    • התמקדות ביחידות או באגפים: משתמשים ב-"structureType": "SECTION" כדי לזהות אגפים בתוך מבנה.

    הכתובות צריכות להיות שימושיות

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

    • דרישה לכתובת ראשית ברורה: כדי להבטיח שלתוצאת היעד הראשית תמיד תהיה כתובת או שם ברמת הרחוב, משתמשים ב-"addressability": "PRIMARY". האפשרות הזו שימושית למטרות ניווט או תצוגה, שבהן חשוב מאוד שהכתובת תהיה ברורה.
    • Allow Addresses in Sub-Destinations: במקרים שבהם למקום הראשי אין כתובת, אבל ליחידות שבתוכו יש (כמו דירות בבניין), "addressability": "WEAK" מוודא שלפחות למקום הראשי או לאחד מיעדי המשנה שלו יש כתובת.
    • כל תוצאה: אם נוכחות הכתובת לא רלוונטית לתרחיש לדוגמה, משתמשים ב-"addressability": "ANY". מומלץ מאוד להשתמש באפשרות הזו כשצריך רק מאפיינים גיאומטריים כמו קווי מתאר של מבנים ונקודות ניווט, כי היא משפרת את הדיוק של התוצאות האלה.
    דוגמה: סינון לפי בניינים שניתן להציג בהם מודעות 
    curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4/geocode/destinations

  • מאמץ

    ניסיוני: הפרמטר effort הוא ניסיוני. יצירת בקשות HTTP באמצעות הערוץ /v4alpha/. מידע נוסף על ערוצים של שלבי השקה

    מציין את כמות העיבוד Effort שצריך להחיל כשפותרים את שאילתת היעד (משפיע בעיקר על addressQuery רזולוציה):

    • ‫EFFORT_UNSPECIFIED – ערך ברירת המחדל. ההתנהגות זהה לזו של המאמץ LOW.
    • ‫LOW – אופטימיזציה לזמני התגובה המהירים ביותר. לא מבצע חיפוש מורחב או הפגת עמימות של כתובות מורכבות.
    • ‫MEDIUM – איזון בין מהירות לדיוק. רוב הבקשות מוחזרות עם זמן אחזור נמוך רגיל. אם הכתובות לא ברורות או קשות, השירות מבצע עיבוד נוסף כדי לשפר את הדיוק, וזה יכול להימשך עד כמה שניות. מומלץ לתהליכי עבודה אינטראקטיביים שבהם המשתמשים יכולים להמתין זמן קצר.
    • HIGH – משפר את הדיוק של זיהוי הכתובות במקרה של כתובות חלקיות, לא רשמיות או מורכבות. זמני התגובה עשויים להיות ארוכים משמעותית. מומלץ לתהליכי עבודה של שליחה ברקע, באצווה או בלוגיסטיקה.

    לדוגמה, בבקשה הבאה נעשה שימוש ב-"effort": "HIGH" כדי לפתור שאילתה של כתובת יעד:

    curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

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