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

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

לחפש יעדים

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

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

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

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

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

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

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

שימוש ב-Places API Autocomplete (חדש) עם 'חיפוש יעדים'

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

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

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

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

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

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

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

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

`primary`

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

`containingPlaces`

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

`subDestinations`

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

`entrances`

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

location

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

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

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

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

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

`structureType`

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

POINT

מיקום נקודתי.
SECTION

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

מבנה.
GROUNDS

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

`navigationPoints`

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

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

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

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

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

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

`landmarks`

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

`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

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

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

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

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

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

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

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

שימוש ב-Places API Autocomplete (חדש) עם 'חיפוש יעדים'

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

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

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

primary

containingPlaces

subDestinations

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

פורמט התשובה

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

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

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