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

باستخدام 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

استيراد التبعيات من المكتبة

توفر المكتبة مفتوحة المصدر "البحث عن منطقة" مجموعة من الدوال وكتب 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 اختيارية إذا كانت قيمة الحقل "نوع_المكان" هي 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، كاليفورنيا.

// 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"، يمكن أن يكون اسم المكان الصالح هو "94109". إذا كانت السمة place_type هي "COUNTRY"، يمكن أن يكون عنصر place صالحًا هو "الولايات المتحدة"، وما إلى ذلك. والسمة region_code مطلوبة عند تحديد place ما لم تكن السمة place_type هي "COUNTRY".
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 (الولاية) وكانت قيمةregion_code (رمز المنطقة) هي "US"، يمكن أن تكون قيمة unit_code صالحة "6" (رمز FIP لولاية كاليفورنيا) أو "12" (رمز FIP لولاية فلوريدا). إذا كان قيمة type_type هي ADMINISTRATIVE_AREA_LEVEL_2 (county) وregion_code (رمز_المنطقة) هي "US"، يمكن أن يكون unit_code (رمز_الوحدة) صالحًا "6001" (رمز FIP لمقاطعة ألاميدا في كاليفورنيا) أو 12086 (رمز FIP لمقاطعة Miami-Dade في فلوريدا). يجب توفّر region_code عند تحديد رمز FIP. يتم تجاهل region_code بسبب رموز البلدان ISO-3166-1.
place_type PlaceType يجب ملء الحقل. نوع المنطقة المطلوب مطابقتها.
region_code سلسلة تمثّل هذه السمة رمز البلد/المنطقة المكوّن من حرفَين وفقًا لمعيار ISO-3166 للموقع الجغرافي الذي تحاول مطابقته. ويكون رمز المنطقة اختياريًا إذا كانت السمة 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 رقم تعريف المكان المطابق غير مُدرَج في القائمة المسموح بها لنوع المكان والبلد.