نمای کلی
ژئوکدینگ فرآیند تبدیل آدرس ها (مانند "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 های فعال:
- به Google Cloud Console بروید.
- روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
- از لیست APIها در داشبورد ، به دنبال Geocoding API باشید.
- اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
- در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
- Geocoding API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
- 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 تأثیر می گذارد و به طور کامل محدود نمی شود. اطلاعات بیشتر در مورد بایاس کد منطقه را در زیر مشاهده کنید. -
extraComputations
- تنها مقدار مجاز برای این پارامترADDRESS_DESCRIPTORS
است. برای جزئیات بیشتر به توضیحات آدرس مراجعه کنید. -
fulfillOnZeroResults
- به قول وضعیت ZERO_RESULT در پاسخ، عمل کنید. این ممکن است مطلوب باشد زیرا حتی با نتایج صفر کدگذاری جغرافیایی، ممکن است هنوز فیلدهای سطح پاسخ اضافی برگردانده شوند. برای جزئیات بیشتر به Fullfill on Zero Results مراجعه کنید.
پاسخ های کدگذاری جغرافیایی
سرویس 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 معکوس، به طور پیشفرض وعده در status=ZERO_RESULTS
شکسته میشود. با این حال، فیلدهای سطح پاسخ اضافی plus_code
و address_descriptor
ممکن است همچنان در این مورد پر شوند. اگر true برای پارامتر fulfillOnZeroResults
ارائه شود، وعده شکسته نمی شود و در صورت وجود، این فیلدهای اضافی از وعده قابل دسترسی هستند.
در زیر نمونه ای از این رفتار برای طول و عرض جغرافیایی در قطب جنوب آورده شده است. حتی با وجود اینکه هیچ نتیجه ای برای کدگذاری جغرافیایی معکوس وجود ندارد، اما اگر 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`); }); }
توصیف کننده های آدرس
توصیفگرهای آدرس شامل اطلاعات اضافی است که به توصیف یک مکان با استفاده از نشانهها و مناطق کمک میکند. برای بررسی این ویژگی ، نسخه ی نمایشی توصیفگر آدرس را بررسی کنید.
توصیف کننده های آدرس را می توان با استفاده از پارامتر extraComputations
فعال کرد. extra_computations=ADDRESS_DESCRIPTORS
را در یک درخواست کدگذاری جغرافیایی ، درخواست کدگذاری جغرافیایی معکوس ، یا درخواست کدگذاری جغرافیایی مکانها برای دریافت توصیفگرهای آدرس در پاسخ خود قرار دهید.
مثال در ژئوکدینگ مکان ها
جستار زیر حاوی آدرس مکانی در دهلی است.
function addressDescriptorPlaceIdLookup() { 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
شامل حداکثر 5 نتیجه است که به ترتیب مرتبط با در نظر گرفتن نزدیکی به مختصات درخواستی، شیوع نقطه عطف و قابلیت مشاهده آن رتبهبندی شدهاند. هر نتیجه مشخصه حاوی مقادیر زیر است:
-
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
دارای حداکثر 3 پاسخ است و خود را محدود به مکان هایی می کند که مناطق کوچک را نشان می دهد، مانند همسایگی ها، مناطق فرعی و مجتمع های بزرگ. مناطقی که حاوی مختصات درخواستی هستند ابتدا فهرست شده و از کوچکترین به بزرگتر مرتب می شوند. نتیجه هر areas
حاوی مقادیر زیر است:
-
place_id
شناسه مکان نتایج مناطق است. نمای کلی شناسه مکان را ببینید. -
display_name
نام نمایشی منطقه است و حاویlanguage_code
وtext
است. -
containment
رابطه محفظه تخمینی بین مختصات ورودی و ناحیه حاصل است: -
"NEAR"
رابطه پیشفرض زمانی است که هیچ یک از موارد زیر اعمال نمیشود. - زمانی که مختصات ورودی نزدیک به مرکز منطقه باشد،
"WITHIN"
. - زمانی که مختصات ورودی نزدیک به لبه ناحیه باشد،
"OUTSKIRTS"
.
پوشش توصیفگر آدرس
این ویژگی فقط در کشورهای منتخب موجود است.
این یک ویژگی پیش نمایش است و ما از بازخورد آن قدردانی خواهیم کرد. لطفاً به آدرس address-descriptors-feedback@google.com ایمیل بزنید.
ژئوکدینگ معکوس (جستجوی آدرس)
اصطلاح 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;