שימוש ב-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 (חובה) הערך של 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 (חובה) הערך של place type לסוג האזור שרוצים לחפש.
  • region_code קוד מדינה או אזור בן שתי אותיות לפי תקן ISO-3166 של המיקום שרוצים להתאים. השדה region_code הוא שדה חובה כשמציינים את השדה address.
  • 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, הערך החוקי של place_name יכול להיות 94109. אם place_type הוא 'COUNTRY', ערך חוקי של place יכול להיות 'ישראל' וכו'. השדה region_code נדרש כאשר place מצוין, אלא אם place_type הוא 'COUNTRY'.
unit_code מחרוזת קודי המדינה או המחוז של FIP (בארה"ב בלבד) או קוד המדינה לפי תקן 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 (מדינה) והערך של region_code הוא 'US', הערך החוקי של unit_code יכול להיות '6' (קוד FIPs של קליפורניה) או '12'(קוד FIPs של פלורידה). אם הערך של place_type הוא ADMINISTRATIVE_AREA_LEVEL_2 (מחוז) והערך של region_code הוא 'US', הערך החוקי של unit_code יכול להיות '6001' (קוד FIPs של מחוז Alameda בקליפורניה) או '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

אובייקט שמייצג צמד קואורדינטות של רוחב וקו אורך. הוא מופיע כצמד של מספרים שלמים (double) שמייצגים את מעלות קו הרוחב ואת מעלות קו האורך. אלא אם צוין אחרת, האובייקט הזה חייב לעמוד בתקן 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 מזהה המקום התואם לא נמצא ברשימת ההיתרים של סוג המקום והמדינה.