استخدام واجهة برمجة تطبيقات البحث عن المنطقة

باستخدام واجهة برمجة التطبيقات 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، تعرض واجهة برمجة التطبيقات معرّف المكان لكاليفورنيا على أنّه 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 results: رقم تعريف المكان للولايات المتحدة. ولا تُظهر جميع الأنواع المتوافقة الأخرى أي مطابقة.

في حال عدم العثور على أي مطابقة، لن يتم ضبط 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.

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

// 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 válida هي "الولايات المتحدة" وما إلى ذلك. تكون قيمة 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 لflorida). إذا كانت قيمة سمة place_type هي ADMINISTRATIVE_AREA_LEVEL_2 (مقاطعة) وكانت قيمة سمة region_code هي "US"، يمكن أن تكون قيمة سمة unit_code صالحة هي "6001" (رمز FIPS لمقاطعة Alameda في كاليفورنيا) أو "12086" (رمز FIPS لمقاطعة Miami-Dade في فلوريدا). يجب إدخال region_code عند تحديد رمز FIPs. يتم تجاهل region_code في رموز البلدان وفقًا لمعيار ISO-3166-1.
place_type PlaceType مطلوب. نوع المنطقة المطلوب مطابقتها.
region_code سلسلة رمز البلد أو المنطقة المكوّن من حرفَين وفقًا لمعيار ISO-3166 للموقع الجغرافي الذي تحاول مطابقته. يكون رمز_المنطقة اختياريًا إذا كانت قيمة place_type هي "البلد".
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 تعذّر الترميز الجغرافي للعنوان المقدَّم.
PlaceTypeMismatch لا يتطابق نوع المكان في الردّ مع نوع الطلب. على سبيل المثال، تم طلب locality ولكن تم عرض administrative_area_level_2.
MultipleCandidatesFound تمّت مطابقة عدّة مرشّحين مع الإدخال. يُرجى الاطّلاع على candidate_place_ids. إذا كان ذلك متاحًا
PlaceNameNotUnderstood تعذّر تحويل اسم المكان المقدَّم إلى منطقة.
UnitCodeNotFound تعذّر العثور على رمز الوحدة. تأكَّد من أنّ رمز الوحدة صالح ومقدَّم بالتنسيق الصحيح.
PlaceTypeNotAllowed معرّف المكان المطابق غير مُدرَج في القائمة المسموح بها لنوع المكان والبلد.