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

דף זה תורגם על ידי Cloud Translation API.

שימוש ב-Region Lookup API

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

כשמשתמשים בתכונה Region lookup, המערכת מחפשת אזור לפי שם המקום, קוד FIPS (מדינות ומחוזות בארה"ב בלבד) או קוד מדינה ISO-3166-1.
האפשרות חיפוש אזורים מחפשת את האזור שמכיל מיקום ספציפי, כפי שצוין בכתובת, LatLng או מזהה מקום.

סוגי מקומות נתמכים באזור

המערכת תומכת בסוגי המקומות הבאים באזורים הבאים: country, administrative_area_level_1, administrative_area_level_2, postal_code ו-locality.

התקנת הספרייה

כדי להשתמש ב-Region Lookup API, יש לפעול לפי השלבים הבאים:

מפעילים את Region Lookup API במסוף.
התקן את ספריית הקוד הפתוח: npm install @googlemaps/region-lookup

ייבוא יחסי תלות מהספרייה

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

לבקשות לחיפוש אזורים, צריך לייבא את הפרטים הבאים:

import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

לבקשות של חיפוש אזור בתמונה, צריך לייבא את הפרטים הבאים:

import {
  searchRegion,
  RegionSearchValue,
  SearchRegionRequestData,
  SearchRegionResponse
} from "@googlemaps/region-lookup";

בקשות לחיפוש אזורים

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

place או unit_code (חובה) שם האזור (place) או unit_code של המקום. unit_code יכול להיות קוד FIPS (מדינות ומחוזות בארה"ב בלבד), או קוד מדינה ISO-3166-1.
place_type (חובה) הערך של סוג המקום לסוג המקום שרוצים לחפש.
region_code קוד מדינה/אזור בן שתי אותיות לפי תקן ISO-3166 כדי שהמיקום יהיה תואם. הערך region_code הוא אופציונלי אם Place_type הוא COUNTRY.
language קוד השפה BCP-47, למשל "en-US" או "sr-Latn". אם לא מציינים שום דבר, ברירת המחדל היא en-US.

הדוגמה הבאה מציגה בקשת חיפוש עבור ניוארק, ניו ג'רזי.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};
const data: LookupRegionRequestData = {
  identifiers: [
    {
      "place": "newark",
      "place_type": "locality",
      "region_code": "us",
      "language": "en",
    },
  ],
};
const response: LookupRegionResponse = await RegionLookup.lookupRegion({ headers, data });

הפרמטר place או הפרמטר unit_code נדרשים. אם לא מציינים שום דבר, תוחזר שגיאה.

הפרמטר region_code נדרש, אלא אם הערך של place_type הוא COUNTRY.

place ו-unit_code מציינים מיקום שמתאים למזהה מקום. לדוגמה, אם הערך של place הוא "קליפורניה" ו-place_type הוא ADMINISTRATIVE_AREA_LEVEL_1, ה-API מחזיר את מזהה המקום עבור קליפורניה בתור matched_place_id:

place_type:‏ ADMINISTRATIVE_AREA_LEVEL_1

matched_place_id תוצאות: מזהה מקום בקליפורניה. כל שאר הסוגים הנתמכים לא מחזירים התאמה.

אם הערך של unit_code הוא '6' (קוד FIPS בקליפורניה), הערך של place_type הוא ADMINISTRATIVE_AREA_LEVEL_1 והערך של region_code הוא US, ה-API מחזיר את מזהה המקום של קליפורניה:

place_type:‏ ADMINISTRATIVE_AREA_LEVEL_1
region_code:‏ US

matched_place_id תוצאות: מזהה מקום בקליפורניה. כל שאר הסוגים הנתמכים לא מחזירים התאמה.

אם הערך של unit_code הוא "US", ה-API מחזיר את התוצאות הבאות כאשר מצוינים ערכי place_type הבאים:

place_type:‏ COUNTRY

matched_place_id תוצאות: מזהה מקום בארצות הברית. כל שאר הסוגים הנתמכים לא מחזירים התאמה.

אם לא נמצאה התאמה, הערך matched_place_id לא מוגדר.

המזהים של המקומות האפשריים מוחזרים במקרה של אי-בהירות. לדוגמה, אם המספר place הוא "מחוז סנטה קלרה" ו-place_type הוא LOCALITY, מזהה המקום של מחוז סנטה קלרה יוחזר כמועמד.

תגובה לחיפוש אזור

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

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

בקשות לחיפוש אזור בתמונה

על מנת למצוא אזור שמכיל מיקום ספציפי, צריך להפעיל את searchRegion ולציין SearchRegionRequestData עם הפרמטרים הבאים:

address או latlng או place_id (חובה) מכילים מחרוזת כתובת לא מובנית, latlng או מזהה מקום שמוגדרת לאזור (לדוגמה, נקודת עניין, בניין וכן הלאה). אם לא מציינים שום דבר, תוחזר שגיאה.
place_type (חובה) הערך של סוג המקום לסוג האזור שרוצים לחפש.
region_code קוד מדינה/אזור בן שתי אותיות לפי תקן ISO-3166 כדי שהמיקום יהיה תואם. אם צוין address, הפונקציה region_code נדרשת.
language קוד השפה BCP-47, למשל "en-US" או "sr-Latn". אם לא מציינים שום דבר, ברירת המחדל היא en-US.

בדוגמה הבאה מוצגת בקשת חיפוש ל-Burbank, CA.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};

const data: SearchRegionRequestData = {
  search_values: [
    {
      "address": "2627 N Hollywood Way, Burbank, CA" ,
      "place_type": "locality" as const,
      "region_code": "us"
    },
  ],
};
const response = await regionLookupClient.searchRegion({ headers, data });

תגובה של חיפוש אזור בתמונה

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

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

חומרי עזר

`LookupRegionRequestData` מזהים

שדה	סוג	תיאור
`place`	מחרוזת	שם האזור להתאמה למזהה מקום. משתמשים בשדה `place` בשילוב עם `place_type` כדי לחפש את מזהה המקום של האזור. לדוגמה, אם הערך של `place_type` הוא "locality", ערך תקין של `place` יכול להיות "Palo Alto, CA". אם `place_type` הוא 'POSTAL_CODE', 'שם_מקום' תקין יכול להיות "94109". אם הערך של `place_type` הוא 'COUNTRY', הערך של `place` יכול להיות ארצות הברית וכו'. אם מציינים את הערך `place`, צריך להזין את הערך `place`, אלא אם הערך של `place_type` הוא 'COUNTRY'.`region_code`
`unit_code`	מחרוזת	קודי המדינה (States) או קודי המחוז (בארה"ב בלבד) או קוד המדינה ISO-3166-1 להתאמה. השדה `unit_code` משמש בשילוב עם `place_type` כדי לחפש את מזהה המקום של האזור. לדוגמה: אם `place_type` הוא `COUNTRY`, ערך unit_code חוקי יכול להיות "US" (קוד ISO-3166-1 Alpha-2 עבור ארצות הברית) או "BR" (קוד ISO-3166-1 Alpha-2 עבור ברזיל). אם הערך של `place_type` הוא `ADMINISTRATIVE_AREA_LEVEL_1` (מדינה) וקוד האזור הוא "US", ערך unit_code תקף יכול להיות "6" (קוד FIP עבור קליפורניה) או "12"(קוד FIP עבור פלורידה). אם הפרמטר Place_type הוא `ADMINISTRATIVE_AREA_LEVEL_2` (מחוז) ו-region_code הוא US כאשר מציינים קוד FIP, יש צורך ב-`region_code`. קודי מדינות בפורמט ISO-3166-1 לא מובאים בחשבון `region_code`.
`place_type`	PlaceType	חובה. סוג האזור להתאמה.
`region_code`	מחרוזת	קוד מדינה/אזור בן שתי אותיות לפי תקן ISO-3166 של המיקום שאליו מנסים להתאים. קוד האזור הוא אופציונלי אם הערך של `place_type` הוא 'COUNTRY'.
`language_code`	מחרוזת	קוד השפה BCP-47, למשל "en-US" או "sr-Latn", שתואם לשפה שבה מבקשים את השם והכתובת של המקום. אם לא מבקשים, ברירת המחדל היא אנגלית.

`SearchRegionRequestData` מזהים

חובה: אחד מתוך address, latlng או place_id.

שדה	סוג	תיאור
`address`	מחרוזת	כתובת רחוב לא מובנית שנמצאת בתוך אזור להתאמה. אם צוין `address`, יש צורך ב-`region_code`.
`latlng`	LatLng	קווי האורך והרוחב שנמצאים בתוך אזור להתאמה.
`place_id`	מחרוזת	מזהה מקום שנמצא בתוך אזור הרלוונטי.
`place_type`	סוג המקום	חובה. סוג האזור להתאמה.
`language_code`	מחרוזת	קוד השפה BCP-47, למשל "en-US" או "sr-Latn", שתואם לשפה שבה השם והכתובת של המקום נדרשים. אם לא מבקשים, ברירת המחדל תהיה אנגלית.
`region_code`	מחרוזת	קוד מדינה/אזור בן שתי אותיות לפי תקן ISO-3166 של המיקום. כשהכתובת מצוינת, השדה `region_code` נדרש.

סוגי מקומות

תמורה לכסף	תיאור
`POSTAL_CODE`	מיקוד, המשמש לכתובת דואר במדינה.
`ADMINISTRATIVE_AREA_LEVEL_1`	ישות אזרחית מסדר ראשון מתחת לרמת המדינה. בארצות הברית, רמות הניהול האלה הן מדינות.
`ADMINISTRATIVE_AREA_LEVEL_2`	ישות אזרחית מסדר שני מתחת לרמת המדינה. בארצות הברית, הרמות המנהליות האלה הן מחוזות.
`LOCALITY`	ישות פוליטית מאוגדת של עיר או עיר.
`COUNTRY`	הישות הפוליטית הלאומית, בדרך כלל מהסוג הגבוה ביותר.

LatLng

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

שדה	סוג	תיאור
`latitude`	כפולה	קו הרוחב במעלות. הערך חייב להיות בטווח `[-90.0, +90.0]`. לדוגמה: `47.47583476464538`.
`longitude`	כפולה	קו האורך במעלות. הערך חייב להיות בטווח `[-180.0, +180.0]`. לדוגמה: `-121.73858779269906`.

קודי שגיאה

תמורה לכסף	תיאור
`UnknownError`	אירעה שגיאה לא ידועה.
`NoMatchFound`	הבקשה לא נמצאה התאמה. יש לבדוק את `candidate_place_ids` אם יש אפשרות כזו.
`AddressNotUnderstood`	הקידוד הגיאוגרפי נכשל עבור הכתובת שצוינה.
`PlaceTypeMismatch`	סוג המקום בתשובה לא תואם לסוג המקום של הבקשה. לדוגמה, נשלחה בקשה לסכום `locality` אבל הוחזרה `administrative_area_level_2`.
`MultipleCandidatesFound`	מספר מועמדים מתאימים הותאמו לקלט. כדאי לבדוק את `candidate_place_ids`. אם היא זמינה.
`PlaceNameNotUnderstood`	לא הצלחנו לתרגם את שם המקום שצוין לאזור.
`UnitCodeNotFound`	קוד היחידה לא נמצא. צריך לוודא שקוד היחידה תקין וסיפק בפורמט הנכון.
`PlaceTypeNotAllowed`	מזהה המקום התואם לא נמצא ברשימת ההיתרים של סוג המקום והמדינה.