سرویس ژئوکدینگ

نمای کلی

ژئوکدینگ فرآیند تبدیل آدرس‌ها (مانند «۱۶۰۰ آمفی‌تئاتر پارک‌وی، مانتین ویو، کالیفرنیا») به مختصات جغرافیایی (مانند عرض جغرافیایی ۳۷.۴۲۳۰۲۱ و طول جغرافیایی -۱۲۲.۰۸۳۷۳۹) است که می‌توانید از آن برای قرار دادن نشانگرها یا تعیین موقعیت نقشه استفاده کنید.

ژئوکدینگ معکوس فرآیند تبدیل مختصات جغرافیایی به آدرسی قابل خواندن توسط انسان است (به ژئوکدینگ معکوس (جستجوی آدرس) مراجعه کنید).

همچنین می‌توانید از geocoder برای یافتن آدرس یک شناسه مکان مشخص استفاده کنید.

API جاوا اسکریپت Maps یک کلاس Geocoder برای ژئوکدینگ و ژئوکدینگ معکوس به صورت پویا از ورودی کاربر ارائه می‌دهد. اگر به جای آن می‌خواهید آدرس‌های ایستا و شناخته شده را ژئوکدینگ کنید، به سرویس وب Geocoding مراجعه کنید.

شروع کنید

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

برای مشاهده لیست API های فعال خود:

1. به کنسول گوگل کلود بروید.
2. روی دکمه‌ی «انتخاب پروژه» کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API تنظیم کرده‌اید، انتخاب کنید و روی «باز کردن» کلیک کنید.
3. از لیست APIهای موجود در داشبورد ، به دنبال Geocoding API بگردید.
4. اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
   1. در بالای صفحه، گزینه‌ی ENABLE API را انتخاب کنید تا تب کتابخانه نمایش داده شود. همچنین می‌توانید از منوی سمت چپ، گزینه‌ی کتابخانه را انتخاب کنید.
   2. عبارت Geocoding API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
   3. گزینه فعال‌سازی (ENABLE) را انتخاب کنید. پس از اتمام فرآیند، Geocoding API در لیست APIهای موجود در داشبورد ظاهر می‌شود.

قیمت‌گذاری و سیاست‌ها

قیمت‌گذاری

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

سیاست‌ها

استفاده شما از سرویس Geocoding باید مطابق با سیاست‌های API Geocoding باشد.

درخواست‌های ژئوکدینگ

دسترسی به سرویس Geocoding به صورت غیرهمزمان است، زیرا API نقشه‌های گوگل نیاز به برقراری ارتباط با یک سرور خارجی دارد. به همین دلیل، شما باید یک متد callback برای اجرا پس از تکمیل درخواست ارسال کنید. این متد callback نتیجه(ها) را پردازش می‌کند. توجه داشته باشید که geocoder ممکن است بیش از یک نتیجه را برگرداند.

شما با استفاده از شیء سازنده google.maps.Geocoder در کد خود به سرویس geocoding API نقشه‌های گوگل دسترسی پیدا می‌کنید. متد Geocoder.geocode() درخواستی را به سرویس geocoding آغاز می‌کند و یک شیء GeocoderRequest به صورت تحت‌اللفظی حاوی عبارات ورودی و یک متد callback برای اجرا پس از دریافت پاسخ به آن ارسال می‌کند.

شیء GeocoderRequest به صورت تحت‌اللفظی شامل فیلدهای زیر است:

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

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

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

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

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

پاسخ‌های جغرافیایی

سرویس Geocoding به یک متد فراخوانی نیاز دارد تا پس از بازیابی نتایج geocoder اجرا شود. این فراخوانی باید دو پارامتر برای نگهداری results و یک کد status ، به ترتیب، ارسال کند.

نتایج کدگذاری جغرافیایی

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

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[] is an array indicating the address type of the returned result. This array contains a set of zero or more tags identifying the type of feature returned in the result. For example, a geocode of "Chicago" returns "locality" which indicates that "Chicago" is a city, and also returns "political" which indicates it is a political entity. See more information about address types and address component types below.
• formatted_address رشته‌ای است که حاوی آدرس قابل خواندن توسط انسان این مکان است.

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

  آدرس قالب‌بندی شده به طور منطقی از یک یا چند جزء آدرس تشکیل شده است. برای مثال، آدرس "111 خیابان هشتم، نیویورک، نیویورک" از اجزای زیر تشکیل شده است: "111" (شماره خیابان)، "خیابان هشتم" (مسیر)، "نیویورک" (شهر) و "NY" (ایالت ایالات متحده).

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

• address_components[] آرایه‌ای است که شامل اجزای جداگانه‌ای است که برای این آدرس قابل استفاده هستند.

  هر جزء آدرس معمولاً شامل فیلدهای زیر است:

  • types[] آرایه‌ای است که نوع مؤلفه آدرس را نشان می‌دهد. لیست انواع پشتیبانی شده را ببینید.
  • long_name توضیحات متنی کامل یا نام کامپوننت آدرس است که توسط Geocoder برگردانده می‌شود.
  • short_name یک نام متنی خلاصه شده برای کامپوننت آدرس است، در صورت وجود. برای مثال، یک کامپوننت آدرس برای ایالت آلاسکا ممکن است دارای یک long_name به شکل "Alaska" و یک short_name به شکل "AK" با استفاده از مخفف پستی دو حرفی باشد.

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

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

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

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

  Partial matches most often occur for street addresses that do not exist within the locality you pass in the request. Partial matches may also be returned when a request matches two or more locations in the same locality. For example, "Hillpar St, Bristol, UK" will return a partial match for both Henry Street and Henrietta Street. Note that if a request includes a misspelled address component, the geocoding service may suggest an alternative address. Suggestions triggered in this way will also be marked as a partial match.

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

• geometry شامل اطلاعات زیر است:

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

آدرس‌ها توسط Geocoder با استفاده از تنظیمات زبان ترجیحی مرورگر یا زبانی که هنگام بارگذاری API جاوا اسکریپت با استفاده از پارامتر language مشخص شده است، بازگردانده می‌شوند. (برای اطلاعات بیشتر، به محلی‌سازی مراجعه کنید. )

انواع آدرس و انواع مؤلفه آدرس

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

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

انواع زیر پشتیبانی می‌شوند و در هر دو آرایه نوع آدرس و نوع جزء آدرس بازگردانده می‌شوند:

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

علاوه بر موارد فوق، اجزای آدرس ممکن است شامل انواع زیر باشند.

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

علاوه بر موارد فوق، اجزای آدرس ممکن است شامل انواع ذکر شده در زیر باشند.

کدهای وضعیت

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

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

در این مثال، ما یک آدرس را geocode می‌کنیم و یک نشانگر در مقادیر طول و عرض جغرافیایی برگردانده شده قرار می‌دهیم. توجه داشته باشید که handler به عنوان یک تابع بی‌نام به صورت تحت‌اللفظی ارسال می‌شود.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

مشاهده مثال.

بایاس کردن ویوپورت

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

برای مثال، یک کد جغرافیایی برای "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 که یک کادر مرزی برای دره سن فرناندو لس‌آنجلس تعریف می‌کند، منجر به این می‌شود که این geocode محله‌ای به نام "Winnetka" را در آن مکان بازگرداند:

{
  "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"
}

بایاس کد منطقه

You can set the Geocoding Service to return results biased to a particular region explicitly using the region parameter. This parameter takes a region code, specified as a two-character (non-numeric) Unicode region subtag. These tags map directly to familiar ccTLD ("top-level domain") two-character values such as "uk" in "co.uk" for example. In some cases, the region tag also supports ISO-3166-1 codes, which sometimes differ from ccTLD values ("GB" for "Great Britain" for example).

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

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

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

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

{
  "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"
}

فیلتر کردن کامپوننت

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

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

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

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

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

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

بدون نتیجه، به خواسته‌هایتان برسید

For reverse geocoding, by default the promise is broken on status=ZERO_RESULTS . However, the additional response level fields of plus_code and address_descriptor may still be populated in this case. If true is provided for the fulfillOnZeroResults parameter, populated in this case. If true is provided for the fulfillOnZeroResults parameter, the promise is not broken and these additional fields are accessible from the promise if present.

در ادامه مثالی از این رفتار برای طول/عرض جغرافیایی در قطب جنوب آمده است. اگرچه هیچ نتیجه‌ی معکوسی برای geocoding وجود ندارد، اما اگر مقدار fulfillOnZeroResults=true تنظیم کنیم، می‌توانیم کد مثبت را در promise چاپ کنیم.

    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`);
        });
    }
  

توصیف‌گرهای آدرس

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

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

مثال در مکان‌های جغرافیایی

عبارت جستجوی زیر شامل آدرس مکانی در دهلی است.

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 هستند. استفاده از توصیف‌گرهای آدرس در هند هیچ هزینه اضافی ندارد و استفاده از آنها توسط SKU موجود Geocoding (India) Essentials پوشش داده می‌شود.

بازخورد

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

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

ژئوکدینگ معکوس (جستجوی آدرس)

اصطلاح ژئوکدینگ (geocding) عموماً به ترجمه یک آدرس قابل خواندن توسط انسان به مکانی روی نقشه اشاره دارد. فرآیند انجام عکس این عمل، یعنی ترجمه یک مکان روی نقشه به آدرسی قابل خواندن توسط انسان، به عنوان ژئوکدینگ معکوس شناخته می‌شود.

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

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

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

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

    // 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') as HTMLElement;

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

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

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

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

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

    // Make an initial request upon loading.
    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]),
    };

    geocoder
        .geocode({ location: latlng })
        .then((response) => {
            if (response.results[0]) {
                marker.position = latlng;
                map.setCenter(latlng);
                infowindow.setContent(response.results[0].formatted_address);
                infowindow.open(map, marker);
            } else {
                window.alert('No results found');
            }
        })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}

initMap();
index.ts

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, 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,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    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]),
    };
    geocoder
        .geocode({ location: latlng })
        .then((response) => {
        if (response.results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infowindow.setContent(response.results[0].formatted_address);
            infowindow.open(map, marker);
        }
        else {
            window.alert('No results found');
        }
    })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}
initMap();
index.js

Note that in the previous example we showed the first result by selecting results[0] . The reverse geocoder often returns more than one result. Geocoded addresses are not just postal addresses, but any way to geographically name a location. For example, when geocoding a point in the city of Chicago, the geocoded point may be labeled as a street address, as the city (Chicago), as its state (Illinois) or as a country (The United States). All are addresses to the geocoder. The reverse geocoder returns all of these results.

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

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

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"

Addresses are returned in the order of best to least matches. Generally, the more exact address is the most prominent result, as it is in this case. Note that we return different types of addresses, from the most specific street address to less specific political entities such as neighborhoods, cities, counties, states, etc. If you want to match a more general address, you may want to inspect the results[].types field.

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

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

برای یافتن آدرس یک شناسه مکان مشخص، یک placeId ارائه دهید. شناسه مکان یک شناسه منحصر به فرد است که می‌تواند با سایر APIهای گوگل مورد استفاده قرار گیرد. برای مثال، می‌توانید placeId برگردانده شده توسط Roads API را ارائه دهید تا آدرس یک نقطه snap شده را دریافت کنید. برای اطلاعات بیشتر در مورد شناسه‌های مکان، به مرور کلی شناسه مکان مراجعه کنید.

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

• address
• latLng
• location
• componentRestrictions

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

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

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

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

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

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

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

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js