استخدام واجهة برمجة التطبيقات 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 هي "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.

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

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