לחפש יעדים

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

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

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

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

בקשה לחיפוש יעדים היא בקשת POST HTTP לכתובת 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"
שאילתות דו-משמעיות עם כמה פרשנויות "Charger drop-off"
שמות היסטוריים שכבר לא בשימוש "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 כדי לשלוח בקשה

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

  • https://www.googleapis.com/auth/maps-platform.geocode ‫— לשימוש בכל ה-methods של 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[] כוללים את השדות הבאים:

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

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