استخدام واجهة برمجة التطبيقات 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". إذا لم يتم تحديد أي لغة، سيتم استخدام اللغة الإنجليزية (الولايات المتحدة) كلغة تلقائية.

يعرض المثال التالي طلب بحث عن مدينة نيوارك في ولاية نيوجيرسي.

// 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، تعرض واجهة برمجة التطبيقات رقم تعريف المكان لولاية كاليفورنيا على أنّه 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"، ستعرض واجهة برمجة التطبيقات رقم تعريف المكان لولاية كاليفورنيا:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    matched_place_id نتيجة: رقم تعريف المكان لكاليفورنيا أما جميع الأنواع الأخرى المتوافقة، فلا تعرض أي تطابق.

إذا كانت قيمة unit_code هي "US"، تعرض واجهة برمجة التطبيقات النتائج التالية عند تحديد قيم place_type التالية:

  • place_type: COUNTRY

    ‫matched_place_id نتيجة: رقم تعريف المكان للولايات المتحدة أما جميع الأنواع الأخرى المتوافقة، فلا تعرض أي تطابق.

في حال عدم العثور على أي تطابق، لن يتم ضبط matched_place_id.

يتم عرض أرقام تعريف الأماكن المرشحة في حال عدم الوضوح. على سبيل المثال، إذا كانت قيمة place هي "Santa Clara County" وقيمة 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". إذا لم يتم تحديد أي لغة، سيتم استخدام اللغة الإنجليزية (الولايات المتحدة) كلغة تلقائية.

يعرض المثال التالي طلب بحث عن مدينة بوربانك في كاليفورنيا.

// 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 سلسلة رموز الولاية أو المقاطعة وفقًا لمعيار 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 للموقع الجغرافي الذي تحاول مطابقته. تكون السمة 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 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 تعذّر الترميز الجغرافي للعنوان المقدَّم.
PlaceTypeMismatch لا يتطابق نوع المكان في الردّ مع نوع المكان في الطلب. على سبيل المثال، تم طلب locality ولكن تم عرض administrative_area_level_2.
MultipleCandidatesFound تمت مطابقة عدة مرشحين مع الإدخال. تحقَّق من candidate_place_ids. إذا كان ذلك متاحًا.
PlaceNameNotUnderstood تعذّر تحديد منطقة من اسم المكان المقدَّم.
UnitCodeNotFound لم يتم العثور على رمز الوحدة. تأكَّد من أنّ رمز الوحدة صالح وتم تقديمه بالتنسيق الصحيح.
PlaceTypeNotAllowed رقم تعريف المكان المطابق غير مدرَج في القائمة المسموح بها لنوع المكان والبلد.