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

بررسی اجمالی

ژئوکدینگ فرآیند تبدیل آدرس ها (مانند "1600 Amphitheatre Parkway, Mountain View, CA") به مختصات جغرافیایی (مانند عرض جغرافیایی 37.423021 و طول جغرافیایی -122.083739) است که می توانید از آنها برای قرار دادن نشانگرها یا موقعیت نقشه استفاده کنید.

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

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

Maps JavaScript API یک کلاس Geocoder برای geocoding و geocoding معکوس به صورت پویا از ورودی کاربر فراهم می کند. اگر به جای آن می‌خواهید آدرس‌های ثابت و شناخته‌شده را به صورت جغرافیایی کدگذاری کنید، به سرویس وب Geocoding مراجعه کنید.

شروع شدن

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

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

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

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

قیمت گذاری

از 16 ژوئیه 2018، یک طرح جدید قیمت‌گذاری پرداختی برای Maps، Routes و Places اجرا شد. برای کسب اطلاعات بیشتر در مورد قیمت‌گذاری و محدودیت‌های استفاده جدید برای استفاده از سرویس کدگذاری جغرافیایی جاوا اسکریپت، به Usage and Billing for Geocoding API مراجعه کنید.

سیاست های

استفاده از سرویس کدگذاری جغرافیایی باید مطابق با خط مشی های توصیف شده برای API جغرافیایی باشد.

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

دسترسی به سرویس کدگذاری جغرافیایی ناهمزمان است، زیرا Google Maps API نیاز به برقراری تماس با یک سرور خارجی دارد. به همین دلیل، باید پس از تکمیل درخواست، یک متد برگشتی را ارسال کنید تا اجرا شود. این روش پاسخ به تماس، نتیجه(های) را پردازش می کند. توجه داشته باشید که geocoder ممکن است بیش از یک نتیجه را برگرداند.

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

شیء GeocoderRequest حاوی فیلدهای زیر است:

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

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

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

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

  • bounds - LatLngBounds که در آن برای بایاس ژئوکد نتایج برجسته‌تر است. پارامتر bounds فقط بر نتایج ژئوکدر تأثیر می‌گذارد، نه کاملاً محدود. اطلاعات بیشتر در مورد بایاس درگاه دید را در زیر مشاهده کنید.
  • componentRestrictions - برای محدود کردن نتایج به یک منطقه خاص استفاده می شود. اطلاعات بیشتر در مورد فیلتر کردن اجزا را در زیر مشاهده کنید.
  • region - کد منطقه که به عنوان یک زیربرچسب منطقه یونیکد دو کاراکتری (غیر عددی) مشخص شده است. در بیشتر موارد، این برچسب‌ها مستقیماً به مقادیر دو کاراکتری آشنا ccTLD ("دامنه سطح بالا") نگاشت می‌شوند. پارامتر region فقط بر نتایج geocoder تأثیر می گذارد و به طور کامل محدود نمی شود. اطلاعات بیشتر در مورد بایاس کد منطقه را در زیر مشاهده کنید.

پاسخ های کدگذاری جغرافیایی

سرویس Geocoding نیاز به یک روش بازگشت به تماس دارد تا پس از بازیابی نتایج geocoder اجرا شود. این فراخوانی باید دو پارامتر را برای نگهداری 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[] آرایه ای است که نوع آدرس نتیجه برگشتی را نشان می دهد. این آرایه حاوی مجموعه‌ای از صفر یا چند تگ است که نوع ویژگی برگردانده شده در نتیجه را مشخص می‌کند. برای مثال، ژئوکد «شیکاگو» «محلی» را برمی‌گرداند که نشان می‌دهد «شیکاگو» یک شهر است، و همچنین «سیاسی» را برمی‌گرداند که نشان می‌دهد یک نهاد سیاسی است. اطلاعات بیشتر در مورد انواع آدرس و انواع اجزای آدرس را در زیر مشاهده کنید.
  • formatted_address رشته ای است که حاوی آدرس قابل خواندن توسط انسان این مکان است.

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

    آدرس فرمت شده منطقاً از یک یا چند جزء آدرس تشکیل شده است. به عنوان مثال، آدرس "111 8th Avenue, New York, NY" از اجزای زیر تشکیل شده است: "111" (شماره خیابان)، "8th Avenue" (مسیر)، "New York" (شهر) و "NY". " (ایالت ایالات متحده).

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

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

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

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

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

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

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

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

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

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

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

    • viewport نمای پیشنهادی را برای نتیجه برگشتی ذخیره می کند.
    • bounds (به صورت اختیاری برگردانده می شود) LatLngBounds را ذخیره می کند که می تواند به طور کامل حاوی نتیجه برگشتی باشد. توجه داشته باشید که این کران ممکن است با نمای پیشنهادی مطابقت نداشته باشد. (به عنوان مثال، سانفرانسیسکو شامل جزایر فارالون است که از نظر فنی بخشی از شهر هستند، اما نباید در نمای دید بازگردانده شوند.)

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

انواع آدرس و انواع اجزای آدرس

آرایه types[] در GeocoderResult نوع آدرس را نشان می دهد. آرایه types[] همچنین ممکن است در یک GeocoderAddressComponent برگردانده شود تا نوع جزء آدرس خاص را نشان دهد. آدرس های بازگردانده شده توسط geocoder ممکن است انواع مختلفی داشته باشند. انواع ممکن است برچسب در نظر گرفته شوند. به عنوان مثال، بسیاری از شهرها با نوع political و locality برچسب گذاری شده اند.

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

  • street_address نشان دهنده آدرس دقیق خیابان است.
  • route یک مسیر نامگذاری شده را نشان می دهد (مانند "US 101").
  • intersection نشان دهنده یک تقاطع بزرگ است که معمولاً از دو جاده اصلی تشکیل شده است.
  • political به معنای یک نهاد سیاسی است. معمولاً این نوع نشان دهنده چند ضلعی برخی از مدیریت شهری است.
  • country نشان‌دهنده نهاد سیاسی ملی است و معمولاً بالاترین نوع سفارش است که توسط Geocoder بازگردانده می‌شود.
  • administrative_area_level_1 یک نهاد مدنی درجه یک زیر سطح کشور را نشان می دهد. در داخل ایالات متحده، این سطوح اداری ایالت ها هستند. همه کشورها این سطوح اداری را نشان نمی دهند. در بیشتر موارد، نام‌های کوتاه administrative_area_level_1 با زیربخش‌های ISO 3166-2 و سایر فهرست‌های پرتیراژ بسیار مطابقت دارند. با این حال، این تضمین نمی شود، زیرا نتایج جغرافیایی ما بر اساس سیگنال های مختلف و داده های مکان است.
  • administrative_area_level_2 نشان دهنده یک نهاد مدنی درجه دوم زیر سطح کشور است. در داخل ایالات متحده، این سطوح اداری شهرستان ها هستند. همه کشورها این سطوح اداری را نشان نمی دهند.
  • administrative_area_level_3 یک نهاد مدنی درجه سوم زیر سطح کشور را نشان می دهد. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
  • administrative_area_level_4 نشان دهنده یک نهاد مدنی درجه چهارم زیر سطح کشور است. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
  • administrative_area_level_5 نشان دهنده یک نهاد مدنی درجه پنجم زیر سطح کشور است. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
  • administrative_area_level_6 نشان دهنده یک نهاد مدنی درجه شش زیر سطح کشور است. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
  • administrative_area_level_7 نشان دهنده یک نهاد مدنی درجه هفتم زیر سطح کشور است. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
  • colloquial_area یک نام جایگزین رایج برای موجودیت را نشان می دهد.
  • locality نشان دهنده یک نهاد سیاسی یک شهر یا شهر است.
  • sublocality یک نهاد مدنی مرتبه اول را در زیر یک محل نشان می دهد. برای برخی مکان‌ها ممکن است یکی از انواع اضافی دریافت شود: sublocality_level_1 تا sublocality_level_5 . هر سطح فرعی یک نهاد مدنی است. اعداد بزرگتر نشان دهنده یک منطقه جغرافیایی کوچکتر است.
  • neighborhood نشان دهنده محله ای با نام است
  • premise یک مکان نامگذاری شده را نشان می دهد، معمولاً یک ساختمان یا مجموعه ای از ساختمان ها با نام مشترک
  • subpremise یک موجودیت مرتبه اول را در زیر یک مکان نامگذاری شده نشان می دهد، معمولاً یک ساختمان منحصر به فرد در مجموعه ای از ساختمان ها با نام مشترک
  • plus_code یک مرجع مکان کدگذاری شده را نشان می دهد که از طول و عرض جغرافیایی مشتق شده است. کدهای پلاس می توانند به عنوان جایگزینی برای آدرس های خیابان ها در مکان هایی که وجود ندارند (جایی که ساختمان ها شماره گذاری نشده اند یا خیابان ها نامگذاری نشده اند) استفاده شود. برای جزئیات بیشتر به https://plus.codes مراجعه کنید.
  • postal_code یک کد پستی را نشان می دهد که برای آدرس دهی نامه های پستی در داخل کشور استفاده می شود.
  • natural_feature یک ویژگی طبیعی برجسته را نشان می دهد.
  • airport نشان دهنده یک فرودگاه است.
  • park یک پارک نامگذاری شده را نشان می دهد.
  • point_of_interest یک نقطه مورد علاقه نامگذاری شده را نشان می دهد. به طور معمول، این "POI" نهادهای محلی برجسته ای هستند که به راحتی در دسته بندی دیگری مانند "امپایر استیت بیلدینگ" یا "برج ایفل" قرار نمی گیرند.

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

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

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

  • floor نشان دهنده طبقه یک ساختمان است.
  • establishment معمولاً مکانی را نشان می دهد که هنوز طبقه بندی نشده است.
  • landmark مکان نزدیکی را نشان می دهد که به عنوان مرجع برای کمک به ناوبری استفاده می شود.
  • point_of_interest یک نقطه مورد علاقه نامگذاری شده را نشان می دهد.
  • parking نشان دهنده یک پارکینگ یا سازه پارکینگ است.
  • post_box یک صندوق پستی خاص را نشان می دهد.
  • postal_town نشان‌دهنده گروه‌بندی مناطق جغرافیایی، مانند locality و sublocality است که برای آدرس‌های پستی در برخی کشورها استفاده می‌شود.
  • room نشان دهنده اتاق یک ساختمان است.
  • street_number شماره دقیق خیابان را نشان می دهد.
  • bus_station ، train_station و transit_station مکان اتوبوس، قطار یا ایستگاه حمل و نقل عمومی را نشان می دهد.

کدهای وضعیت

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

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

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

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

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

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

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

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

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

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

به عنوان مثال، یک ژئوکد برای "Toledo" این نتیجه را برمی گرداند، زیرا دامنه پیش فرض سرویس Geocoding روی ایالات متحده تنظیم شده است:

{
  "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 مشخص کنید. مقادیر فیلتر از همان روش‌های تصحیح املا و تطبیق جزئی مانند سایر درخواست‌های کدگذاری جغرافیایی پشتیبانی می‌کنند.

geocoder فقط نتایجی را برمی گرداند که با تمام فیلترهای مؤلفه مطابقت دارند. یعنی مشخصات فیلتر را به عنوان 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);
  }
});
}

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

اصطلاح geocoding به طور کلی به ترجمه یک آدرس قابل خواندن توسط انسان به یک مکان روی نقشه اشاره دارد. فرآیند انجام مکالمه، ترجمه یک مکان روی نقشه به یک آدرس قابل خواندن برای انسان، به عنوان رمزگذاری معکوس جغرافیایی شناخته می شود.

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

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

TypeScript

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

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

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

جاوا اسکریپت

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

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

window.initMap = initMap;
مشاهده نمونه

Sample را امتحان کنید

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

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

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

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 فیلد results[].types .

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

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

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

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

  • address
  • latLng
  • location
  • componentRestrictions

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

TypeScript

// 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;

جاوا اسکریپت

// 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;
مشاهده نمونه

Sample را امتحان کنید