שימוש ב-Region Lookup API

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

  • החיפוש של אזור מאפשר לחפש אזור לפי שם מקום, קוד 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 identifiers

שדה סוג תיאור
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 identifiers

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