Geocoding Service

نمای کلی

زمین‌کدیابی فرایند تبدیل نشانی‌ها (مانند «1600 Amphitheatre Parkway, Mountain View, CA») به مختصات جغرافیایی (مانند عرض جغرافیایی ۳۷٫۴۲۳۰۲۱ و طول جغرافیایی ۱۲۲٫۰۸۳۷۳۹-) است که می‌توانید از آن برای قرار دادن نشانگرها یا موقعیت‌یابی نقشه استفاده کنید.

زمین‌کدیابی معکوس فرایند تبدیل مختصات جغرافیایی به نشانی قابل‌خواندن برای انسان است (به زمین‌کدیابی معکوس (جستجوی نشانی) مراجعه کنید).

همچنین می‌توانید از زمین‌کدیاب برای پیدا کردن نشانی شناسه مکان داده‌شده استفاده کنید.

‫Maps JavaScript API یک کلاس Geocoder برای زمین‌کدیابی و زمین‌کدیابی معکوس به‌صورت پویا از ورودی کاربر ارائه می‌دهد. اگر درعوض می‌خواهید نشانی‌های شناخته‌شده و ثابت را زمین‌کدیابی کنید، سرویس وب زمین‌کدیابی را ببینید.

شروع کنید

قبل‌از استفاده از سرویس Geocoding در Maps JavaScript API، ابتدا مطمئن شوید که Geocoding API در کنسول Google Cloud، در همان پروژه‌ای که برای Maps JavaScript API راه‌اندازی کرده‌اید، فعال شده باشد.

برای مشاهده فهرست میاناهای برنامه‌سازی کاربردی فعال‌شده:

1. به کنسول Google Cloud بروید.
2. روی دکمه انتخاب پروژه کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API راه‌اندازی کرده‌اید انتخاب کنید و روی باز کردن کلیک کنید.
3. از فهرست میاناهای برنامه‌سازی کاربردی در داشبورد، Geocoding API را پیدا کنید.
4. اگر API را در فهرست می‌بینید، همه تنظیمات انجام شده است. اگر میانای برنامه‌سازی کاربردی در فهرست نیست، آن را فعال کنید:
   1. در بالای صفحه، فعال کردن API را انتخاب کنید تا برگه کتابخانه نمایش داده شود. یا از منوِ سمت راست، کتابخانه را انتخاب کنید.
   2. Geocoding API را جستجو کنید، سپس آن را از فهرست نتایج انتخاب کنید.
   3. فعال کردن را انتخاب کنید. وقتی فرایند تمام شد، Geocoding API در فهرست میاناهای برنامه‌سازی کاربردی در داشبورد نشان داده می‌شود.

قیمت‌گذاری و خط‌مشی‌ها

قیمت‌گذاری

برای آشنایی با خط‌مشی‌های قیمت‌گذاری و استفاده برای سرویس Geocoding جاوا اسکریپت، به استفاده و صورت‌حساب برای Geocoding API مراجعه کنید.

خط‌مشی‌ها

استفاده شما از سرویس «زمین‌کدیابی» باید مطابق با خط‌مشی‌های Geocoding API باشد.

درخواست‌های زمین‌کدیابی

دسترسی به سرویس «زمین‌کدیابی» ناهمگام است و نیاز به تماس با سرور خارجی دارد. به همین دلیل، روش geocode یک promise برمی‌گرداند که پس‌از تکمیل درخواست حل می‌شود. پس‌از برطرف شدن مشکل، می‌توانید از .then() یا await برای رسیدگی به پاسخ استفاده کنید.

بااستفاده از شیء سازنده google.maps.Geocoder، در کدتان به سرویس زمین‌کدیابی Google Maps API دسترسی پیدا می‌کنید. روش Geocoder.geocode() درخواستی را به سرویس زمین‌کدیابی ارسال می‌کند و یک راستین‌نماد شیء GeocoderRequest حاوی عبارت‌های ورودی و یک روش فراخوانی برای اجرا پس‌از دریافت پاسخ را به آن منتقل می‌کند.

راستین‌نماد شیء GeocoderRequest شامل فیلدهای زیر است:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

پارامترهای الزامی: باید یکی، و فقط یکی، از فیلدهای زیر را ارائه دهید:

• address — نشانی‌ای که می‌خواهید زمین‌کدیابی کنید.
       یا
  location — LatLng (یا LatLngLiteral) که می‌خواهید نزدیک‌ترین نشانی قابل‌خواندن برای انسان را برای آن دریافت کنید. زمین‌کدیاب زمین‌کدیابی معکوس انجام می‌دهد. برای اطلاعات بیشتر، زمین‌کدیابی معکوس را ببینید.
       یا
  placeId — شناسه مکانی که می‌خواهید نزدیک‌ترین نشانی قابل‌خواندن برای انسان را برای آن دریافت کنید. درباره بازیابی نشانی برای شناسه مکان بیشتر بدانید.

پارامترهای اختیاری:

• bounds — LatLngBounds که نتایج زمین‌کدیابی در آن به‌طور برجسته‌تری سوگیری دارد. پارامتر bounds فقط بر نتایج زمین‌کدیاب تأثیر می‌گذارد و آن‌ها را کاملاً محدود نمی‌کند. اطلاعات بیشتر درباره سوگیری ناحیه نمایش را در زیر ببینید.
• componentRestrictions — برای محدود کردن نتایج به منطقه‌ای خاص استفاده می‌شود. اطلاعات بیشتر درباره فیلتر کردن مؤلفه را در زیر ببینید.
• region — کد منطقه، که به‌صورت برچسب فرعی منطقه یونی‌کد دو نویسه‌ای (غیرعددی) مشخص شده است. در بیشتر موارد، این برچسب‌ها مستقیماً به مقادیر دو نویسه‌ای ccTLD («دامنه سطح بالا») آشنا نگاشت می‌شوند. پارامتر region فقط بر نتایج زمین‌کدیاب تأثیر می‌گذارد، و آن‌ها را کاملاً محدود نمی‌کند. برای اطلاعات بیشتر درباره سوگیری کد منطقه به زیر مراجعه کنید.
• extraComputations — تنها مقدار مجاز برای این پارامتر ADDRESS_DESCRIPTORS است. برای جزئیات بیشتر، توصیف‌کننده‌های نشانی را ببینید.
• fulfillOnZeroResults — وعده را در وضعیت ZERO_RESULT در پاسخ برآورده کنید. این ممکن است مطلوب باشد زیرا حتی با صفر نتیجه زمین‌کدیابی، ممکن است همچنان فیلدهای سطح پاسخ اضافی برگردانده شود. برای جزئیات بیشتر، به Fulfill on Zero Results مراجعه کنید.

پاسخ‌های زمین‌کدیابی

سرویس «زمین‌کدیابی» به روش فراخوانی برای اجرا پس‌از بازیابی نتایج زمین‌کدیاب نیاز دارد. این فراخوانی برگشتی باید دو پارامتر را برای نگهداری results و کد status به‌ترتیب ارسال کند.

نتایج زمین‌کدیابی

شیء GeocoderResult نشان‌دهنده یک نتیجه زمین‌کدیابی است. درخواست زمین‌کدیاب ممکن است چندین شیء نتیجه برگرداند:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

این فیلدها در زیر توضیح داده شده‌اند:

• ‫types[] آرایه‌ای است که نوع نشانی نتیجه برگردانده‌شده را نشان می‌دهد. این آرایه حاوی مجموعه‌ای از صفر یا چند برچسب است که نوع ویژگی برگردانده‌شده در نتیجه را شناسایی می‌کند. برای مثال، زمین‌کدیاب «شیکاگو» مقدار «locality» (محل) را برمی‌گرداند که نشان می‌دهد «شیکاگو» یک شهر است، و همچنین مقدار «political» (سیاسی) را برمی‌گرداند که نشان می‌دهد یک نهاد سیاسی است. اطلاعات بیشتر درباره انواع نشانی و انواع مؤلفه نشانی را در زیر ببینید.
• formatted_address رشته‌ای است که حاوی نشانی قابل‌خواندن برای انسان این مکان است.

  اغلب این نشانی معادل نشانی پستی است. توجه داشته باشید که برخی کشورها، مانند پادشاهی متحد، به‌دلیل محدودیت‌های صدور پروانه، اجازه توزیع نشانی‌های پستی واقعی را نمی‌دهند.

  نشانی قالب‌بندی‌شده به‌طور منطقی از یک یا چند مؤلفه نشانی تشکیل شده است. برای مثال، نشانی «111 8th Avenue, New York, NY» از مؤلفه‌های زیر تشکیل شده است: «111» (شماره خیابان)، «8th Avenue» (مسیر)، «New York» (شهر)، و «NY» (ایالت امریکا).

  نشانی قالب‌بندی‌شده را به‌صورت برنامه‌نویسی تجزیه نکنید. درعوض باید از مؤلفه‌های نشانی فردی استفاده کنید که پاسخ میانای برنامه‌سازی کاربردی علاوه‌بر فیلد نشانی قالب‌بندی‌شده شامل آن می‌شود.

• address_components[] آرایه‌ای است که حاوی بخش‌های جداگانه قابل‌اعمال برای این نشانی است.

  هر مؤلفه نشانی معمولاً شامل فیلدهای زیر است:

  • types[] آرایه‌ای است که نوع مؤلفه نشانی را نشان می‌دهد. وقتی هیچ نوع شناخته‌شده‌ای برای آن مؤلفه نشانی وجود نداشته باشد، مؤلفه نشانی ممکن است آرایه انواع خالی داشته باشد. ممکن است میانای برنامه‌سازی کاربردی درصورت نیاز مقادیر نوع جدیدی اضافه کند. برای اطلاعات بیشتر، به انواع نشانی و انواع مؤلفه نشانی مراجعه کنید.
  • long_name شرح نوشتاری کامل یا نام مؤلفه نشانی است که توسط «زمین‌کدیاب» برگردانده شده است.
  • short_name نام متنی اختصاری برای مؤلفه نشانی است (درصورت وجود). برای مثال، مؤلفه نشانی برای ایالت آلاسکا ممکن است long_name «آلاسکا» و short_name «AK» را بااستفاده از اختصار پستی ۲ حرفی داشته باشد.

  به حقایق زیر درباره آرایه address_components[] توجه کنید:

  • آرایه مؤلفه‌های نشانی ممکن است مؤلفه‌های بیشتری نسبت به formatted_address داشته باشد.
  • این آرایه لزوماً شامل همه نهادهای سیاسی که حاوی نشانی هستند نمی‌شود، به‌جز آن‌هایی که در formatted_address گنجانده شده‌اند. برای بازیابی همه نهادهای سیاسی که حاوی نشانی خاصی هستند، باید از زمین‌کدیابی معکوس استفاده کنید و طول/عرض جغرافیایی نشانی را به‌عنوان پارامتر به درخواست ارسال کنید.
  • تضمینی وجود ندارد که قالب پاسخ بین درخواست‌ها یکسان باقی بماند. به‌ویژه، تعداد address_components براساس نشانی درخواست‌شده متفاوت است و می‌تواند درطول زمان برای نشانی یکسان تغییر کند. موقعیت مؤلفه می‌تواند در آرایه تغییر کند. نوع مؤلفه می‌تواند تغییر کند. ممکن است مؤلفه خاصی در پاسخ بعدی وجود نداشته باشد.

  اطلاعات بیشتر درباره انواع نشانی و انواع مؤلفه نشانی را در زیر ببینید.

• partial_match نشان می‌دهد که زمین‌کدیاب مطابقت دقیقی برای درخواست اصلی برنگردانده است، هرچند توانسته است بخشی از نشانی درخواستی را مطابقت دهد. شاید بخواهید درخواست اصلی را ازنظر غلط املایی و/یا نشانی ناقص بررسی کنید.

  مطابقت‌های جزئی اغلب برای نشانی‌های خیابانی رخ می‌دهد که در منطقه‌ای که در درخواست ارسال می‌کنید وجود ندارند. وقتی درخواستی با دو یا چند مکان در یک محل مطابقت داشته باشد، ممکن است مطابقت‌های جزئی نیز برگردانده شود. برای مثال، «Hillpar St, Bristol, UK» مطابقت جزئی برای هر دو Henry Street و Henrietta Street برمی‌گرداند. توجه داشته باشید که اگر درخواستی شامل بخش نشانی با املای نادرست باشد، سرویس زمین‌کدیابی ممکن است نشانی جایگزینی پیشنهاد دهد. پیشنهادهایی که به این روش فعال می‌شوند نیز به‌عنوان مطابقت جزئی علامت‌گذاری می‌شوند.

• place_idشناسه یکتای مکان است که می‌توان از آن با دیگر میاناهای برنامه‌سازی کاربردی Google استفاده کرد. برای مثال، می‌توانید از place_id با کتابخانه میانای برنامه‌سازی کاربردی Google Places استفاده کنید تا جزئیات کسب‌وکار محلی، مثل شماره تلفن، ساعت کاری، مرورهای کاربر، و غیره را دریافت کنید. نمای کلی شناسه مکان را ببینید.
• ‫postcode_localities[] آرایه‌ای است که همه محل‌های موجود در کد پستی را نشان می‌دهد و فقط زمانی وجود دارد که نتیجه کد پستی‌ای باشد که شامل چندین محل است.

• geometry حاوی اطلاعات زیر است:

  • location حاوی مقدار زمین‌کدیابی‌شده عرض جغرافیایی، طول جغرافیایی است. توجه داشته باشید که این مکان را به‌عنوان شیء LatLng برمی‌گردانیم، نه به‌عنوان رشته قالب‌بندی‌شده.
  • location_type داده‌های بیشتری درباره مکان مشخص‌شده ذخیره می‌کند. از مقادیر زیر پشتیبانی می‌شود:
    • ‫ROOFTOP نشان می‌دهد که نتیجه برگردانده‌شده نشان‌دهنده زمین‌کدیاب دقیق است.
    • RANGE_INTERPOLATED نشان می‌دهد که نتیجه برگردانده‌شده نشان‌دهنده یک تقریب (معمولاً در جاده) است که بین دو نقطه دقیق (مانند تقاطع‌ها) درون‌یابی شده است. نتایج درون‌یابی‌شده معمولاً زمانی برگردانده می‌شوند که زمین‌کدیاب‌های پشت‌بام برای نشانی خیابان دردسترس نباشند.
    • GEOMETRIC_CENTER نشان می‌دهد که نتیجه برگردانده‌شده مرکز هندسی نتیجه‌ای مانند چندخطی (مثلاً خیابان) یا چندضلعی (منطقه) است.
    • APPROXIMATE نشان می‌دهد که نتیجه برگردانده‌شده تقریبی است.
  
  
  • viewport ناحیه نمایش توصیه‌شده را برای نتیجه برگردانده‌شده ذخیره می‌کند.
  • bounds (به‌صورت اختیاری برگردانده می‌شود) LatLngBounds را ذخیره می‌کند که می‌تواند به‌طور کامل حاوی نتیجه برگردانده‌شده باشد. توجه داشته باشید که این مرزها ممکن است با نمای پیشنهادی مطابقت نداشته باشد. (برای مثال، سان فرانسیسکو شامل جزایر فارالون است که ازنظر فنی بخشی از شهر است، اما نباید در نمای هدف برگردانده شود.)

Addresses are returned by the Geocoder using the browser's preferred language setting, or the language specified when loading the API JavaScript using the language parameter. (برای اطلاعات بیشتر، به بومی‌سازی مراجعه کنید.)

انواع نشانی و انواع مؤلفه نشانی

آرایه types[] در GeocoderResult در پاسخ، نوع نشانی را نشان می‌دهد. نمونه‌هایی از انواع نشانی شامل نشانی خیابان، کشور، یا نهاد سیاسی است. آرایه types در GeocoderAddressComponent نوع هر بخش از نشانی را نشان می‌دهد. برای مثال، شماره خیابان یا کشور.

نشانی‌ها ممکن است چند نوع داشته باشند. این نوع‌ها ممکن است به‌عنوان «برچسب» درنظر گرفته شوند. برای مثال، بسیاری‌از شهرها با نوع political و locality برچسب‌گذاری شده‌اند.

انواع زیر پشتیبانی می‌شوند و در هر دو آرایه نوع نشانی و نوع مؤلفه نشانی برگردانده می‌شوند:

فهرست خالی از انواع نشان می‌دهد که هیچ نوع شناخته‌شده‌ای برای مؤلفه نشانی خاص وجود ندارد (برای مثال، Lieu-dit در فرانسه).

علاوه‌بر موارد بالا، مؤلفه‌های نشانی ممکن است شامل انواع زیر باشد.

توجه: این فهرست کامل نیست و ممکن است تغییر کند.

علاوه‌بر موارد بالا، مؤلفه‌های نشانی ممکن است شامل انواع فهرست‌شده در زیر باشد.

رمزهای وضعیت

کد status ممکن است یکی از مقادیر زیر را برگرداند:

• "OK" نشان می‌دهد که خطایی رخ نداده است؛ نشانی باموفقیت تجزیه شده است و حداقل یک زمین‌کد برگردانده شده است.
• "ZERO_RESULTS" نشان می‌دهد که زمین‌کدیابی موفقیت‌آمیز بوده است اما نتیجه‌ای برنگردانده است. این خطا ممکن است زمانی رخ دهد که address ناموجودی به زمین‌کدیاب ارسال شده باشد.
• "OVER_QUERY_LIMIT" نشان می‌دهد که از سهمیه‌تان فراتر رفته‌اید.
• "REQUEST_DENIED" نشان می‌دهد که درخواستتان رد شده است. صفحه وب مجاز به استفاده از زمین‌کدیاب نیست.
• "INVALID_REQUEST" معمولاً نشان می‌دهد که پُرسمان (address، components یا latlng) وجود ندارد.
• "UNKNOWN_ERROR" نشان می‌دهد که درخواست به‌دلیل خطای سرور پردازش نشده است. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.
• "ERROR" نشان می‌دهد که زمان درخواست به‌پایان رسیده است یا مشکلی در تماس با سرورهای Google وجود دارد. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.

نمونه زمین‌کدیابی

مثال زیر زمین‌کدیابی نشانی و قرار دادن نشانگر در مقادیر عرض جغرافیایی و طول جغرافیایی برگردانده‌شده را نشان می‌دهد. نتیجه زمین‌کدیابی بااستفاده از یک promise مدیریت می‌شود. روی هر جایی از نقشه کلیک کنید تا نشانی آن مکان زمین‌کدیابی شود.

async function geocode(request: google.maps.GeocoderRequest) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}
index.ts

async function geocode(request) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}
index.js

نمونه کامل را مشاهده کنید.

سوگیری ناحیه نمایش

می‌توانید به «سرویس زمین‌کدیابی» دستور دهید که نتایج را در یک نمای هدف مشخص (که به‌صورت کادر مرزی بیان می‌شود) ترجیح دهد. این کار را با تنظیم پارامتر bounds در راستین‌نماد شیء GeocoderRequest انجام می‌دهید تا مرزهای این نمای هدف را تعریف کنید. توجه داشته باشید که سوگیری فقط نتایج درون مرزها را ترجیح می‌دهد؛ اگر نتایج مرتبط‌تری خارج از این مرزها وجود داشته باشد، ممکن است گنجانده شوند.

برای مثال، زمین‌کد «Winnetka» معمولاً این حومه شیکاگو را برمی‌گرداند:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

بااین‌حال، مشخص کردن پارامتر bounds که کادر محدودکننده را برای «دره سن فرناندو» در «لس‌آنجلس» تعریف می‌کند، باعث می‌شود این زمین‌کدیاب محله‌ای به‌نام «وینِتکا» را در آن مکان برگرداند:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

سوگیری کد منطقه

می‌توانید «سرویس زمین‌کدیابی» را طوری تنظیم کنید که نتایج را به‌طور صریح بااستفاده از پارامتر region به منطقه خاصی متمایل کند. این پارامتر کد منطقه را می‌گیرد که به‌عنوان برچسب فرعی منطقه «یونی‌کد» دو نویسه‌ای (غیرعددی) مشخص شده است. این برچسب‌ها مستقیماً به مقادیر دوحرفی آشنای ccTLD («دامنه سطح بالا») نگاشت می‌شوند، مثلاً «uk» در «co.uk». در برخی موارد، برچسب region از کدهای ISO-3166-1 نیز پشتیبانی می‌کند که گاهی با مقادیر ccTLD متفاوت است (برای مثال، «GB» برای «بریتانیای کبیر»).

هنگام استفاده از پارامتر region:

• فقط یک کشور یا منطقه را مشخص کنید. مقادیر متعدد نادیده گرفته می‌شود و می‌تواند منجر به ناموفق شدن درخواست شود.
• فقط از برچسب‌های فرعی منطقه دو نویسه‌ای (قالب Unicode CLDR) استفاده کنید. همه ورودی‌های دیگر منجر به خطا خواهد شد.
• فقط کشورها و مناطقی که در جزئیات پوشش Google Maps Platform فهرست شده‌اند پشتیبانی می‌شوند.

درخواست‌های زمین‌کدیابی را می‌توان برای هر دامنه‌ای که برنامه اصلی Google Maps در آن زمین‌کدیابی ارائه می‌دهد ارسال کرد. توجه داشته باشید که سوگیری فقط نتایج مربوط به دامنه خاصی را ترجیح می‌دهد؛ اگر نتایج مرتبط‌تری خارج از این دامنه وجود داشته باشد، ممکن است آن‌ها نیز گنجانده شوند.

برای مثال، زمین‌کدیاب برای «تولدو» این نتیجه را برمی‌گرداند، زیرا دامنه پیش‌فرض برای «سرویس زمین‌کدیابی» روی ایالات متحده تنظیم شده است:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

زمین‌کدیاب برای «تولدو» با فیلد region تنظیم‌شده روی 'es' (اسپانیا) شهر اسپانیایی را برمی‌گرداند:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

فیلتر کردن مؤلفه

بااستفاده از فیلتر مؤلفه‌ها، می‌توانید «سرویس زمین‌کدیابی» را طوری تنظیم کنید که نتایج نشانی را محدود به منطقه‌ای خاص برگرداند. فیلتر را در پارامتر componentRestrictions مشخص کنید. مقادیر فیلتر از همان روش‌های تصحیح املایی و تطابق جزئی مانند سایر درخواست‌های زمین‌کدیابی پشتیبانی می‌کنند.

زمین‌کدیاب فقط نتایجی را برمی‌گرداند که با همه فیلترهای مؤلفه مطابقت داشته باشند. یعنی مشخصات فیلتر را به‌عنوان AND ارزیابی می‌کند، نه OR.

فیلتر مؤلفه‌ها از یک یا چند مورد زیر تشکیل شده است:

• route با نام کوتاه یا بلند مسیر مطابقت دارد.
• locality با انواع محلی و فرعی مطابقت دارد.
• administrativeArea با همه سطوح تقسیمات کشوری مطابقت دارد.
• postalCode با کدهای پستی و پیشوندهای کد پستی مطابقت دارد.
• country با نام کشور یا کد کشور دوحرفی ISO 3166-1 مطابقت دارد. توجه: API از استاندارد ISO برای تعریف کشورها پیروی می‌کند و فیلتر کردن زمانی بهترین عملکرد را دارد که از کد ISO مربوط به کشور استفاده شود.

مثال زیر نحوه استفاده از پارامتر componentRestrictions را برای فیلتر کردن براساس country و postalCode نشان می‌دهد:

async function codeAddress(request: google.maps.GeocoderRequest) {
    clear();
    geocoder.geocode({
        componentRestrictions: {
            country: 'AU',
            postalCode: '2000'
        }
    })
    .then((result) => {
        const { results } = result;
        innerMap.setCenter(results[0].geometry.location);
        let marker = new google.maps.marker.AdvancedMarkerElement({
            map: innerMap,
            position: results[0].geometry.location
        });
    })
    .catch((e) => {
        alert('Geocode was not successful for the following reason: ' + e);
    });
};

اجرا کردن درصورت نبود نتیجه

برای زمین‌کدیابی معکوس، به‌طور پیش‌فرض، وعده در status=ZERO_RESULTS شکسته می‌شود. بااین‌حال، فیلدهای سطح پاسخ اضافی plus_code و address_descriptor ممکن است همچنان در این مورد پر شوند. اگر برای پارامتر fulfillOnZeroResults مقدار «درست» ارائه شده باشد، در این مورد درج می‌شود. اگر مقدار true برای پارامتر fulfillOnZeroResults ارائه شود، قول شکسته نمی‌شود و این فیلدهای اضافی درصورت وجود ازطریق قول قابل‌دسترسی هستند.

در زیر مثالی از این رفتار برای طول/عرض جغرافیایی در قطب جنوب آورده شده است. Even though there are no reverse geocoding results, we can still print the plus code in the promise if we set fulfillOnZeroResults=true.

function addressDescriptorReverseGeocoding() {
  var latlng = new google.maps.LatLng(-75.290330, 38.653861);
  geocoder
    .geocode({
      'location': latlng,
      'fulfillOnZeroResults': true,
    })
    .then((response) => {
      console.log(response.plus_code);
    })
    .catch((error) => {
      window.alert(`Error: ${error}`);
    });
}

توصیف‌گرهای نشانی

توصیف‌کننده‌های نشانی شامل اطلاعات اضافی است که به توصیف مکان بااستفاده از نشانگرهای مکانی و مناطق کمک می‌کند. برای کاوش این ویژگی، نمونه توصیف‌گرهای نشانی را بررسی کنید.

توصیف‌کننده‌های نشانی را می‌توان بااستفاده از پارامتر extraComputations فعال کرد. extra_computations=ADDRESS_DESCRIPTORS را در درخواست زمین‌کدیابی ، درخواست زمین‌کدیابی معکوس ، یا درخواست زمین‌کدیابی مکان‌ها بگنجانید تا توصیف‌کننده‌های نشانی را در پاسخ دریافت کنید.

مثال در زمین‌کدیابی مکان‌ها

پرسمان زیر حاوی نشانی مکانی در دهلی است.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

مثال در زمین‌کدیابی معکوس

پُرسمان زیر حاوی مقدار عرض/طول جغرافیایی برای مکانی در دهلی است.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }
  

نمونه توصیف‌گر نشانی

نمونه‌ای از address_descriptor در زیر آمده است.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

در هر شیء address_descriptor دو آرایه وجود دارد: landmarks و areas. آرایه landmarks حداکثر ۵ نتیجه را دربرمی‌گیرد که براساس میزان مربوط بودن رتبه‌بندی شده‌اند. این رتبه‌بندی با درنظر گرفتن نزدیکی به مختصات درخواست‌شده، رواج مکان دیدنی، و رؤیت‌پذیری آن انجام می‌شود. هر نتیجه نشانگر حاوی مقادیر زیر است:

• place_id شناسه مکان نتیجه نشانگرهای مکان است. نمای کلی شناسه مکان را ببینید.
• display_name نام نمایشی این مکان دیدنی است و حاوی language_code و text است.
• straight_line_distance_meters فاصله نقطه به نقطه برحسب متر بین مختصات ورودی و نتیجه نشان‌یابی است.
• travel_distance_meters فاصله برحسب متر است که بااستفاده از شبکه جاده‌ای (بدون درنظر گرفتن محدودیت‌های جاده‌ای) بین مختصات ورودی و نتیجه نشان‌ها طی شده است.
• spatial_relationship رابطه تخمینی بین مختصات ورودی و نتیجه نشانگرها است:
• "NEAR" رابطه پیش‌فرض است وقتی هیچ‌کدام از موارد زیر اعمال نشود.
• "WITHIN" وقتی مختصات ورودی در محدوده ساختار مرتبط با نشانگر مکان قرار دارد.
• "BESIDE" وقتی مختصات ورودی مستقیماً در مجاورت نقطه عطف یا نقطه دسترسی نقطه عطف باشد.
• "ACROSS_THE_ROAD" وقتی مختصات ورودی دقیقاً در مقابل نقطه عطف در طرف دیگر مسیر باشد.
• "DOWN_THE_ROAD" وقتی مختصات ورودی در امتداد همان مسیر نشانگر است، اما "BESIDES" یا "ACROSS_THE_ROAD" نیست.
• "AROUND_THE_CORNER" وقتی مختصات ورودی در امتداد مسیر عمود بر نشانگر مکان باشد (محدود به یک پیچ).
• "BEHIND" وقتی مختصات ورودی ازنظر فضایی به مکان دیدنی نزدیک است، اما از نقطه دسترسی آن دور است.
• types انواع مکان این نقطه عطف است.

شیء areas حداکثر ۳ پاسخ دارد و خود را به مکان‌هایی محدود می‌کند که مناطق کوچک را نشان می‌دهند، مانند محله‌ها، مناطق فرعی، و مجتمع‌های بزرگ. مناطقی که حاوی مختصات درخواستی هستند ابتدا فهرست می‌شوند و از کوچک‌ترین به بزرگ‌ترین مرتب می‌شوند. هر نتیجه areas حاوی مقادیر زیر است:

• place_id شناسه مکان نتیجه مناطق است. نمای کلی شناسه مکان را ببینید.
• display_name نام نمایشی منطقه است و حاوی language_code و text است.
• containment رابطه مهار تخمینی بین مختصات ورودی و نتیجه مناطق است:
• "NEAR" رابطه پیش‌فرض است وقتی هیچ‌کدام از موارد زیر اعمال نشود.
• "WITHIN" وقتی مختصات ورودی نزدیک به مرکز منطقه باشد.
• "OUTSKIRTS" وقتی مختصات ورودی نزدیک به لبه منطقه باشد.

پوشش توصیف‌گر نشانی

توصیف‌کننده‌های نشانی در GA برای هند دردسترس است. استفاده از توصیف‌کننده‌های نشانی در هند هیچ هزینه اضافی‌ای ندارد و استفاده از آن تحت پوشش Geocoding (India) Essentials SKU موجود است.

بازخورد

این ویژگی در همه مناطق دردسترس است. این ویژگی در مرحله «دردسترس عموم» برای هند و در مرحله راه‌اندازی «آزمایشی» پیش‌از «دردسترس عموم» برای همه مناطق دیگر است. از بازخورد شما استقبال می‌کنیم:

• برای مشکلات مربوط به منطقه هند، با تیم پشتیبانی تماس بگیرید.
• برای ارائه بازخورد درباره نسخه آزمایشی، به ما ایمیل بزنید: address-descriptors-feedback@google.com.
• برای اطلاعات بیشتر، به جزئیات پوشش توصیف‌کننده‌های نشانی مراجعه کنید.

زمین‌کدیابی معکوس (جستجوی نشانی)

اصطلاح زمین‌کدیابی معمولاً به ترجمه نشانی قابل‌خواندن برای انسان به مکانی روی نقشه اشاره دارد. فرایند انجام عکس این کار، یعنی ترجمه کردن مکان روی نقشه به نشانی قابل‌خواندن برای انسان، زمین‌کدیابی معکوس نامیده می‌شود.

به‌جای ارائه address نوشتاری، یک جفت طول/عرض جغرافیایی جداشده با کاما در پارامتر location ارائه دهید.

مثال زیر مقدار عرض جغرافیایی/طول جغرافیایی را زمین‌کدیابی می‌کند و نقشه را در آن مکان متمرکز می‌کند و پنجره اطلاعاتی با نشانی قالب‌بندی‌شده را نمایش می‌دهد. برای زمین‌کدیابی مکان، روی هر جایی از نقشه کلیک کنید یا مختصات خودتان را وارد کنید.

let marker: google.maps.marker.AdvancedMarkerElement;

async function init() {
    //  Request the needed libraries.
    const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('geocoding'),
            google.maps.importLibrary('marker'),
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit')!;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
        mapTypeControl: false,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    marker.anchorTop = '40px';

    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        void geocodeLatLng(geocoder, innerMap, infoWindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        if (event.latLng) {
            latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
            void geocodeLatLng(geocoder, innerMap, infoWindow);
        }
    });

    // Make an initial request upon loading.
    void geocodeLatLng(geocoder, innerMap, infoWindow);
}

async function geocodeLatLng(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infoWindow: google.maps.InfoWindow
) {
    const input = (document.getElementById('latlng') as HTMLInputElement).value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();
index.ts

let marker;

async function init() {
    //  Request the needed libraries.
    const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('geocoding'),
            google.maps.importLibrary('marker'),
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');

    // Get the submit button.
    const submitButton = document.getElementById('submit');

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
        mapTypeControl: false,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    marker.anchorTop = '40px';

    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        void geocodeLatLng(geocoder, innerMap, infoWindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        if (event.latLng) {
            latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
            void geocodeLatLng(geocoder, innerMap, infoWindow);
        }
    });

    // Make an initial request upon loading.
    void geocodeLatLng(geocoder, innerMap, infoWindow);
}

async function geocodeLatLng(geocoder, map, infoWindow) {
    const input = document.getElementById('latlng').value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();
index.js

/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
gmp-map {
    height: 100%;
}

/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
    font-family: Roboto, sans-serif;
}

#floating-panel {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 10px;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
}

#latlng {
    width: 100%;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
    margin-bottom: 4px;
}

#submit {
    font-size: 1rem;
}
style.css

<html>
    <head>
        <title>Reverse Geocoding</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="0.714224, -73.961452" zoom="8" map-id="DEMO_MAP_ID">
            <div id="floating-panel" slot="control-block-start-inline-start">
                <p>
                    Click the map to reverse geocode, or add your own
                    coordinates.
                </p>
                <input
                    id="latlng"
                    type="text"
                    value="40.714224, -73.961452" /><br />
                <input id="submit" type="button" value="Reverse Geocode" />
            </div>
        </gmp-map>
    </body>
</html>
index.html

توجه داشته باشید که در مثال قبلی، اولین نتیجه را با انتخاب results[0] نشان دادیم. زمین‌کدیاب معکوس اغلب بیش‌از یک نتیجه برمی‌گرداند. نشانی‌های زمین‌کدیابی‌شده فقط نشانی‌های پستی نیستند، بلکه هر روشی برای نام‌گذاری جغرافیایی یک مکان را شامل می‌شوند. برای مثال، هنگام زمین‌کدیابی نقطه‌ای در شهر شیکاگو، نقطه زمین‌کدیابی‌شده ممکن است به‌عنوان نشانی خیابان، به‌عنوان شهر (شیکاگو)، به‌عنوان ایالت آن (ایلینوی)، یا به‌عنوان کشور (ایالات متحده) برچسب‌گذاری شود. همه نشانی‌ها به زمین‌کدیاب ارسال می‌شوند. زمین‌کدیاب معکوس همه این نتایج را برمی‌گرداند.

زمین‌کدیاب معکوس با نهادهای سیاسی (کشورها، استان‌ها، شهرها، و محله‌ها)، نشانی‌های خیابان، و کدهای پستی مطابقت دارد.

در اینجا نمونه‌ای از فهرست نشانی‌هایی که پرسمان بالا ممکن است برگرداند آورده شده است:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

نشانی‌ها به‌ترتیب از بهترین تا کمترین مطابقت برگردانده می‌شوند. به‌طور کلی، نشانی دقیق‌تر برجسته‌ترین نتیجه است، همان‌طور که در این مورد می‌بینید. توجه داشته باشید که ما انواع مختلفی از نشانی‌ها را برمی‌گردانیم، از نشانی خیابان بسیار خاص گرفته تا نهادهای سیاسی کمتر خاص مانند محله‌ها، شهرها، شهرستان‌ها، ایالت‌ها، و غیره. اگر می‌خواهید نشانی عمومی‌تری را مطابقت دهید، ممکن است بخواهید فیلد results[].types را بررسی کنید.

توجه: زمین‌کدیابی معکوس علم دقیقی نیست. زمین‌کدیاب تلاش می‌کند نزدیک‌ترین مکان قابل‌آدرس‌دهی را در محدوده تلورانس مشخصی پیدا کند.

بازیابی نشانی برای شناسه مکان

برای پیدا کردن نشانی شناسه مکان داده‌شده، placeId را ارائه دهید. شناسه مکان شناسه یکتایی است که می‌توان از آن با دیگر میاناهای برنامه‌سازی کاربردی Google استفاده کرد. برای مثال، می‌توانید placeId برگردانده‌شده توسط Roads API را ارائه دهید تا نشانی نقطه چسبیده را دریافت کنید. برای اطلاعات بیشتر درباره شناسه‌های مکان، نمای کلی شناسه مکان را ببینید.

وقتی placeId ارائه می‌دهید، درخواست نمی‌تواند حاوی هیچ‌کدام از فیلدهای زیر باشد:

• address
• latLng
• location
• componentRestrictions

مثال زیر شناسه مکان را می‌پذیرد، نشانی مربوطه را پیدا می‌کند، و نقشه را روی آن مکان متمرکز می‌کند. همچنین پنجره اطلاعاتی را نشان می‌دهد که نشانی قالب‌بندی‌شده مکان مربوطه را نشان می‌دهد:

// Initialize the map.
async function init(): Promise<void> {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit')!.addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infoWindow: google.maps.InfoWindow
) {
    const placeId = (document.getElementById('place-id') as HTMLInputElement)
        .value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    const { results } = await geocoder.geocode({ placeId });
    if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new AdvancedMarkerElement({
            map,
            position: results[0].geometry.location,
        });

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();
index.ts

// Initialize the map.
async function init() {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit').addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(geocoder, map, infoWindow) {
    const placeId = document.getElementById('place-id').value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    const { results } = await geocoder.geocode({ placeId });
    if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new AdvancedMarkerElement({
            map,
            position: results[0].geometry.location,
        });

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();
index.js