از منطقه جستجوی API استفاده کنید

با منطقه جستجوی 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 است.

مثال زیر یک درخواست جستجو برای Newark، NJ را نشان می دهد.

// 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 باشد، API شناسه مکان کالیفرنیا را به عنوان 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 "محلی" باشد، یک place معتبر می تواند "Palo Alto, CA" باشد. اگر place_type «POSTAL_CODE» باشد، یک مکان_نام معتبر می‌تواند «94109» باشد. اگر place_type "COUNTRY" باشد، یک place معتبر می تواند "ایالات متحده" باشد، و غیره. 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 Code for United States) یا "BR" (ISO-3166-1 Alpha-2 Code for Brazil) باشد. اگر place_type ADMINISTRATIVE_AREA_LEVEL_1 (ایالت) و region_code "US" باشد، یک unit_code معتبر می تواند "6" (کد FIP برای کالیفرنیا) یا "12" (کد FIP برای فلوریدا) باشد. اگر محل_نوع ADMINISTRATIVE_AREA_LEVEL_2 (شهرستان) و منطقه_کد "US" باشد، یک واحد_کد معتبر می تواند "6001" (کد FIP برای شهرستان آلامدا در کالیفرنیا) یا "12086" (کد FIP برای شهرستان میامی داد در فلوریدا) باشد. region_code هنگام تعیین یک کد FIP مورد نیاز است. 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 رشته یک آدرس خیابان بدون ساختار که در داخل یک منطقه برای مطابقت وجود دارد. 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 شناسه مکان منطبق در لیست مجاز نوع مکان و کشور نیست.