دریافت کلید نسخه نمایشی Maps: با «کلید نسخه نمایشی Maps» برخی‌از ویژگی‌های Maps JavaScript API و «کیت میانای کاربر جاها» را بدون هزینه امتحان کنید—اطلاعات صورت‌حساب لازم نیست.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

استفاده از 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، این مراحل را دنبال کنید:

Region Lookup API را در کنسول فعال کنید.
کتابخانه متن‌باز را نصب کنید: 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» باشد، API شناسه مکان کالیفرنیا را برمی‌گرداند:

‫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 «Santa Clara County» باشد و place_type LOCALITY باشد، شناسه مکان Santa Clara County به‌عنوان نامزد برگردانده می‌شود.

پاسخ جستجوی منطقه

شیء LookupRegionResponse حاوی matched_place_id است، اگر نتیجه‌ای پیدا شده باشد. اگر نتیجه‌ای پیدا نشود، شناسه‌های مکان با اطمینان کمتر به‌عنوان شناسه‌های نامزد برگردانده می‌شوند، همراه با یک کد خطا که حاوی اطلاعات اشکال‌زدایی است.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

درخواست‌های جستجوی منطقه‌ای

برای پیدا کردن منطقه‌ای که حاوی مکان خاصی است، searchRegion را فراخوانی کنید و SearchRegionRequestData را با پارامترهای زیر مشخص کنید:

address یا latlng یا place_id (الزامی) حاوی رشته نشانی بدون ساختار، latlng، یا شناسه مکان موجود در منطقه (برای مثال نقطه موردعلاقه، ساختمان، و غیره). اگر هیچ‌کدام مشخص نشده باشد، خطایی برمی‌گردد.
place_type (الزامی) مقدار نوع مکان برای نوع منطقه‌ای که باید جستجو شود.
region_code کد کشور/منطقه ISO-3166 دوحرفی برای مکان موردنظر برای مطابقت. وقتی address مشخص شده باشد، region_code الزامی است.
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"
    }
  ]
}

Reference

`LookupRegionRequestData` شناسه

فیلد	نوع	شرح
`place`	رشته	نام منطقه‌ای که باید با شناسه مکان مطابقت داده شود. از فیلد `place` در ترکیب با `place_type` برای جستجوی شناسه مکان منطقه استفاده کنید. برای مثال، اگر `place_type` «locality» باشد، `place` معتبر می‌تواند «Palo Alto, CA» باشد. اگر `place_type` ‏ `POSTAL_CODE` باشد، place_name معتبر می‌تواند «94109» باشد. اگر `place_type` برابر با `COUNTRY` باشد، `place` معتبر می‌تواند «ایالات متحده» و غیره باشد. وقتی `place` مشخص شده باشد، `region_code` الزامی است، مگراینکه `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» (کد 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 دوحرفی برای مکانی که می‌خواهید مطابقت دهید. اگر `place_type` برابر با `COUNTRY` باشد، region_code اختیاری است.
`language_code`	رشته	کد زبان BCP-47، مانند «en-US» یا «sr-Latn»، مطابق با زبانی که نام و نشانی مکان به آن درخواست شده است. اگر هیچ‌کدام درخواست نشود، به‌طور پیش‌فرض انگلیسی انتخاب می‌شود.

`SearchRegionRequestData` شناسه

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

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