از منطقه جستجوی 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. 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 برای تطبیق مکان. اگر place_type برابر COUNTRY باشد، region_code اختیاری است.
  • 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 برابر با "California" و place_type برابر با ADMINISTRATIVE_AREA_LEVEL_1 باشد، API شناسه مکان را برای California به عنوان 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" باشد، API شناسه مکان برای کالیفرنیا را برمی‌گرداند:

  • place_type : ADMINISTRATIVE_AREA_LEVEL_1

  • region_code : US

    نتایج matched_place_id : شناسه مکان برای کالیفرنیا. همه انواع پشتیبانی شده دیگر هیچ تطابقی برنمی‌گردانند.

اگر unit_code برابر با "US" باشد، API در صورت مشخص شدن 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 یا شناسه مکان موجود در منطقه (به عنوان مثال POI، ساختمان و غیره) است. اگر هیچ کدام مشخص نشده باشد، خطا برگردانده می‌شود.
  • 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 برابر با "locality" باشد، یک place معتبر می‌تواند "Palo Alto, CA" باشد. اگر place_type با `POSTAL_CODE` باشد، یک نام مکان معتبر می‌تواند "94109" باشد. اگر place_type برابر با `COUNTRY` باشد، یک place معتبر می‌تواند "United States" باشد و غیره. region_code هنگام مشخص کردن place مورد نیاز است، مگر اینکه place_type برابر با `COUNTRY` باشد.
unit_code رشته کدهای ایالت یا شهرستان FIP (فقط ایالات متحده) یا کد کشور 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 برای فلوریدا) باشد. اگر place_type برابر با ADMINISTRATIVE_AREA_LEVEL_2 (شهرستان) و region_code برابر با "US" باشد، یک unit_code معتبر می‌تواند "6001" (کد FIP برای شهرستان آلامدا در کالیفرنیا) یا "12086" (کد FIP برای شهرستان میامی-دید در فلوریدا) باشد. region_code هنگام مشخص کردن کد FIP الزامی است. region_code برای کدهای کشور ISO-3166-1 نادیده گرفته می‌شود.
place_type نوع مکان الزامی. نوع منطقه‌ای که باید مطابقت داده شود.
region_code رشته کد دو حرفی کشور/منطقه ISO-3166 برای مکانی که می‌خواهید مطابقت دهید. اگر place_type با `COUNTRY` باشد، region_code اختیاری است.
language_code رشته کد زبان BCP-47، مانند "en-US" یا "sr-Latn"، مربوط به زبانی است که نام و آدرس مکان به آن درخواست می‌شود. اگر هیچ زبانی درخواست نشود، به طور پیش‌فرض انگلیسی در نظر گرفته می‌شود.

شناسه‌های داده SearchRegionRequestData

الزامی: یکی از address ، latlng یا place_id .

میدان نوع توضیحات
address رشته یک آدرس خیابان بدون ساختار که درون یک منطقه برای مطابقت قرار دارد. هنگام مشخص کردن address region_code الزامی است.
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 نهاد سیاسی ملی، که معمولاً بالاترین نوع آن است.

لات‌لنگ

شیء‌ای که یک جفت عرض/طول جغرافیایی را نشان می‌دهد. این به صورت یک جفت دوتایی بیان می‌شود تا درجه عرض جغرافیایی و درجه طول جغرافیایی را نشان دهد. مگر اینکه خلاف آن مشخص شده باشد، این شیء باید با استاندارد 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 شناسه مکان منطبق در فهرست مجاز نوع مکان و کشور نیست.