שימוש ב-Region Lookup API

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

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

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

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

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

כדי להשתמש ב-Region Lookup API, צריך לבצע את השלבים הבאים:

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

ייבוא פריטים בקשרי תלות מהספרייה

ספריית הקוד הפתוח 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 results: מזהה המקום של קליפורניה. כל שאר הסוגים הנתמכים לא יחזירו התאמה.

אם 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 results: מזהה המקום של קליפורניה. כל שאר הסוגים הנתמכים לא יחזירו התאמה.

אם הערך של 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 למיקום שצריך להתאים. המאפיין region_code הוא מאפיין חובה אם מציינים את המאפיין address.
  • language קוד השפה BCP-47, כמו en-US או sr-Latn. אם לא מציינים ערך, ברירת המחדל היא en-US.

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

// 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 חוקי יכול להיות "United States" וכו'. חובה לציין את region_code אם מציינים את place, אלא אם place_type הוא `COUNTRY`.
unit_code מחרוזת קודי המדינה או המחוז של FIPs (בארה"ב בלבד) או קוד המדינה לפי תקן ISO-3166-1 שצריך להתאים. השדה unit_code משמש בשילוב עם place_type כדי לחפש את מזהה המקום של האזור. לדוגמה: אם place_type הוא COUNTRY, קוד יחידה תקין יכול להיות "US" (קוד ISO-3166-1 Alpha-2 לארצות הברית) או "BR" (קוד ISO-3166-1 Alpha-2 לברזיל). אם place_type הוא ADMINISTRATIVE_AREA_LEVEL_1 (מדינה) ו-region_code הוא US, ערך תקין של unit_code יכול להיות 6 (קוד FIPs לקליפורניה) או 12 (קוד FIPs לפלורידה). אם הערך של place_type הוא ADMINISTRATIVE_AREA_LEVEL_2 (מחוז) והערך של region_code הוא US, ערך תקין של unit_code יכול להיות 6001 (קוד FIPs של מחוז אלמידה בקליפורניה) או 12086 (קוד FIPs של מחוז מיאמי-דייד בפלורידה). חובה לציין את region_code כשמציינים קוד FIPs. המערכת מתעלמת מ-region_code כשמציינים קודי מדינה לפי תקן ISO-3166-1.
place_type PlaceType חובה. סוג האזור להתאמה.
region_code מחרוזת קוד מדינה או אזור בן שתי אותיות לפי תקן ISO-3166 למיקום שאתם מנסים להתאים. הפרמטר region_code הוא אופציונלי אם place_type הוא COUNTRY.
language_code מחרוזת קוד השפה BCP-47, כמו en-US או sr-Latn, שמתאים לשפה שבה מתבצעת הבקשה לשם ולכתובת של המקום. אם לא תצוין שפה, ברירת המחדל תהיה אנגלית.

SearchRegionRequestData מזהים

חובה: אחד מהערכים address, latlng או place_id.

שדה סוג תיאור
address מחרוזת כתובת רחוב לא מובנית שנמצאת בתוך אזור להתאמה. המאפיין region_code הוא מאפיין חובה אם מציינים את המאפיין address.
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 double קו הרוחב במעלות. הערך חייב להיות בטווח [-90.0, +90.0]. לדוגמה 47.47583476464538.
longitude double קו האורך במעלות. הערך חייב להיות בטווח [-180.0, +180.0]. לדוגמה -121.73858779269906.

קודי שגיאה

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