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