שימוש ב-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 הוא "California" ו-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 הוא "Santa Clara County" ו-place_type הוא LOCALITY, מזהה המקום של Santa Clara County יוחזר כמועמד.

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

האובייקט 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, ערך תקין של place_name יכול להיות "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, ערך 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 של מחוז אלמדה בקליפורניה) או "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

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