استخدام واجهة برمجة التطبيقات 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 هي "كاليفورنيا" وقيمة 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 هي "الولايات المتحدة"، تعرض واجهة برمجة التطبيقات النتائج التالية عند تحديد قيم 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.

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

// 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 الصالحة هي "بالو ألتو، كاليفورنيا". إذا كانت قيمة 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 نوع المكان الحقل مطلوب. تمثّل هذه السمة نوع المنطقة المطلوب مطابقتها.
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 رقم تعريف المكان المطابِق غير متوفر في القائمة المسموح بها لنوع المكان والبلد.