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

من خلال واجهة برمجة التطبيقات Region Verification API، يمكنك العثور على أرقام تعريف الأماكن للمناطق، والتي يمكنك استخدامها لتصميم مضلّعات الحدود في النمط المستند إلى البيانات للحدود. تتيح واجهة برمجة التطبيقات للبحث عن المنطقة نوعين من الطلبات:

  • يبحث البحث عن منطقة عن منطقة حسب اسم المكان أو رمز FIPS (الولايات والمقاطعات في الولايات المتحدة فقط) أو رمز البلد ISO-3166-1.
  • باستخدام ميزة البحث عن منطقة، يتم البحث عن المنطقة التي تحتوي على موقع جغرافي محدّد كما هو محدّد من خلال العنوان أو LatLng أو معرّف المكان.

أنواع الأماكن المتاحة في المناطق

تتوفّر أنواع الأماكن التالية في المناطق: country وadministrative_area_level_1 وadministrative_area_level_2 وpostal_code وlocality.

تثبيت المكتبة

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

  1. تفعيل واجهة برمجة التطبيقات للبحث عن المنطقة في وحدة التحكّم
  2. تثبيت مكتبة مفتوحة المصدر: npm install @googlemaps/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 نتائج: رقم تعريف المكان في الولايات المتحدة ولا تعرض جميع الأنواع المتوافقة الأخرى أي تطابق.

وفي حال عدم العثور على نتائج مطابقة، لم يتم ضبط السمة 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, 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 هي "المنطقة المحلية"، يمكن أن تكون قيمة place الصالحة "Palo Alto, CA". إذا كانت قيمة place_type هي "POSTAL_CODE"، يمكن أن تكون قيمة Place_name الصالحة هي "94109". إذا كانت قيمة السمة place_type هي "البلد"، يمكن أن تكون قيمة السمة place الصالحة "الولايات المتحدة" أو غير ذلك. ويجب استخدام السمة region_code عند تحديد السمة place ما لم تكن السمة place_type هي "البلد".
unit_code سلسلة تمثّل هذه السمة رموز الولاية أو المقاطعات (في الولايات المتحدة فقط) أو رمز البلد 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 (الولاية) وقيمة سمة رمز المنطقة إلى الولايات المتحدة (US)، يمكن أن تكون قيمة رمز unit_code الصالح هي 6 (رمز FIP لولاية كاليفورنيا) أو 12 (رمز FIP لولاية فلوريدا). إذا كانت قيمة 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 هي "البلد".
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 رقم تعريف المكان المطابق غير مُدرَج في القائمة المسموح بها لنوع المكان والبلد.