לשיטות של 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`

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

`addressComponents`

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

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

‫types[] הוא מערך שמציין את סוג רכיב הכתובת. כאן אפשר לעיין ברשימת הסוגים הנתמכים.
‫longText הוא התיאור המלא של רכיב הכתובת או השם שלו, כפי שמוחזר על ידי הגיאוקודר.
‫shortText הוא שם טקסטואלי מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של מדינת אלסקה יכול לכלול longText עם הערך Alaska ו-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`

השדה 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)‏ או המרה של מקום לקואורדינטות ‏(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

addressComponents

containingPlaces

subDestinations

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

פורמט התשובה

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

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

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