درخواست
یک درخواست API مربوط به Geocoding به شکل زیر است:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
که در آن outputFormat می‌تواند یکی از مقادیر زیر باشد:
-
json(توصیه می‌شود) خروجی را در قالب نشانه‌گذاری شیء جاوااسکریپت (JSON) نشان می‌دهد؛ یا -
xmlخروجی را در XML نشان می‌دهد.
HTTPS الزامی است.
برخی از پارامترها الزامی و برخی اختیاری هستند. همانطور که در URLها استاندارد است، پارامترها با استفاده از کاراکتر & از هم جدا می‌شوند.
ادامه‌ی این صفحه، ژئوکدینگ و ژئوکدینگ معکوس را جداگانه توضیح می‌دهد، زیرا پارامترهای متفاوتی برای هر نوع درخواست در دسترس است.
پارامترهای جغرافیایی (جستجوی طول و عرض جغرافیایی)
پارامترهای مورد نیاز در یک درخواست geocoding:
-
key— کلید API برنامه شما. این کلید، برنامه شما را برای اهداف مدیریت سهمیه شناسایی می‌کند. یاد بگیرید که چگونه یک کلید دریافت کنید . شما باید
addressیاcomponentsیا هر دو را در یک درخواست مشخص کنید:-
address— آدرس خیابان یا کد پلاس که می‌خواهید ژئوکد کنید. آدرس‌ها را مطابق با قالب مورد استفاده توسط سرویس پستی ملی کشور مربوطه مشخص کنید. از عناصر آدرس اضافی مانند نام کسب و کار و شماره واحد، سوئیت یا طبقه باید اجتناب شود. عناصر آدرس خیابان باید با فاصله (که در اینجا به صورت url-escaped to%20نشان داده شده است) از هم جدا شوند:address=24%20Sussex%20Drive%20Ottawa%20ON
%2Bو فاصله‌ها به صورت%20با url-escaped نمایش داده می‌شوند):- کد جهانی یک کد منطقه‌ای ۴ کاراکتری و کد محلی ۶ کاراکتری یا بیشتر است (۸۴۹VCWC8+R9
849VCWC8%2BR9است). - کد مرکب، یک کد محلی ۶ کاراکتری یا بیشتر با موقعیت مکانی مشخص است (CWC8+R9 مانتین ویو، کالیفرنیا، ایالات متحده آمریکا به صورت
CWC8%2BR9%20Mountain%20View%20CA%20USAاست).
- کد جهانی یک کد منطقه‌ای ۴ کاراکتری و کد محلی ۶ کاراکتری یا بیشتر است (۸۴۹VCWC8+R9
-
components— یک فیلتر کامپوننت‌ها با عناصری که با یک خط عمودی (|) از هم جدا شده‌اند. فیلتر کامپوننت‌ها همچنین در صورت ارائهaddress، به عنوان یک پارامتر اختیاری پذیرفته می‌شود. هر عنصر در فیلتر کامپوننت‌ها از یک جفتcomponent:valueتشکیل شده است و نتایج حاصل از ژئوکودر را به طور کامل محدود می‌کند. اطلاعات بیشتر در مورد فیلتر کامپوننت را در زیر ببینید.
-
برای راهنمایی بیشتر به سوالات متداول مراجعه کنید.
پارامترهای اختیاری در یک درخواست Geocoding:
-
bounds— کادر محدودکننده‌ی نمای دید که در آن می‌توان نتایج geocode را به طور برجسته‌تری بایاس کرد. این پارامتر فقط بر نتایج geocoder تأثیر می‌گذارد، نه اینکه آنها را به طور کامل محدود کند. (برای اطلاعات بیشتر به Viewport Biasing در زیر مراجعه کنید.) -
language— زبانی که نتایج با آن برگردانده می‌شوند.- فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر
languageارائه نشود، geocoder تلاش می‌کند از زبان ترجیحی مشخص شده در سربرگAccept-Languageیا زبان مادری دامنه‌ای که درخواست از آن ارسال می‌شود، استفاده کند. - جئوکودر تمام تلاش خود را می‌کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به خطی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
- اگر نامی به زبان ترجیحی موجود نباشد، ژئوکودر از نزدیکترین مورد منطبق استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها دارد. کدگذار جغرافیایی بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند. به عنوان مثال، utca و tér به ترتیب مترادف خیابان و میدان در زبان مجارستانی هستند.
-
region— کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. این پارامتر فقط بر نتایج حاصل از geocoder تأثیر می‌گذارد، نه به طور کامل آنها را محدود می‌کند. (برای اطلاعات بیشتر به Region Biasing در زیر مراجعه کنید.) این پارامتر همچنین می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد. -
components— یک فیلتر کامپوننت‌ها با عناصری که با یک خط عمودی (|) از هم جدا شده‌اند. فیلتر کامپوننت‌ها در صورتی مورد نیاز است که درخواست شاملaddressنباشد. هر عنصر در فیلتر کامپوننت‌ها از یک جفتcomponent:valueتشکیل شده است و نتایج حاصل از geocoder را به طور کامل محدود می‌کند. اطلاعات بیشتر در مورد فیلتر کامپوننت را در زیر ببینید. -
extra_computations— از این پارامتر برای مشخص کردن ویژگی‌های اضافی زیر در پاسخ استفاده کنید:-
ADDRESS_DESCRIPTORS— برای جزئیات بیشتر به توصیف‌گرهای آدرس مراجعه کنید. -
BUILDING_AND_ENTRANCES— برای جزئیات بیشتر به ورودی‌ها و طرح کلی ساختمان مراجعه کنید.
extra_computationsرا در درخواست برای هر ویژگی وارد کنید، برای مثال:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
-
پاسخ‌ها
پاسخ‌های ژئوکدینگ در قالبی که توسط پرچم output در درخواست URL مشخص شده است، یا به طور پیش‌فرض در قالب JSON بازگردانده می‌شوند.
در این مثال، API مربوط به Geocoding برای پرس‌وجویی در آدرس "1600 Amphitheatre Parkway, Mountain View, CA" درخواست پاسخ json می‌کند.
این درخواست استفاده از پرچم output JSON را نشان می‌دهد:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
این درخواست استفاده از پرچم output XML را نشان می‌دهد:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
برای مشاهده نمونه پاسخ‌های JSON و XML، تب‌های زیر را انتخاب کنید.
جی‌سون
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "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" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
توجه داشته باشید که پاسخ JSON شامل دو عنصر ریشه است:
-
"status"شامل ابرداده‌های مربوط به درخواست است. کدهای وضعیت زیر را ببینید. -
"results"شامل آرایه‌ای از اطلاعات آدرس جغرافیایی و اطلاعات هندسی است.
به‌طورکلی، فقط یک ورودی در آرایه "results" برای جستجوی آدرس برگردانده می‌شود، هرچند وقتی درخواست‌های آدرس مبهم باشند، ممکن است جئوکدِر چندین نتیجه برگرداند.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
توجه داشته باشید که پاسخ XML شامل یک <GeocodeResponse> و دو عنصر سطح بالا است:
-
<status>شامل فراداده‌های مربوط به درخواست است. کدهای وضعیت زیر را ببینید. - صفر یا چند عنصر
<result>که هر کدام شامل مجموعه‌ای از اطلاعات آدرس جغرافیایی و اطلاعات هندسی هستند.
پاسخ XML به طور قابل توجهی طولانی‌تر از پاسخ JSON است. به همین دلیل، توصیه می‌کنیم از json به عنوان پرچم خروجی ترجیحی استفاده کنید، مگر اینکه سرویس شما به دلایلی xml نیاز داشته باشد. علاوه بر این، پردازش درخت‌های XML نیاز به کمی دقت دارد، به طوری که به گره‌ها و عناصر مناسب ارجاع دهید. برای برخی از الگوهای طراحی توصیه شده برای پردازش خروجی، به تجزیه XML با XPath مراجعه کنید.
- نتایج XML در یک عنصر ریشه
<GeocodeResponse>قرار می‌گیرند. - JSON ورودی‌هایی با چندین عنصر را با آرایه‌های جمع (
types) نشان می‌دهد، در حالی که XML این موارد را با استفاده از چندین عنصر مفرد (<type>) نشان می‌دهد. - عناصر خالی در JSON از طریق آرایه‌های خالی نشان داده می‌شوند، اما در XML با عدم وجود چنین عنصری. پاسخی که هیچ نتیجه‌ای تولید نمی‌کند، یک آرایه
resultsخالی در JSON برمی‌گرداند، اما برای مثال هیچ عنصر<result>در XML وجود ندارد.
کدهای وضعیت
فیلد "status" در شیء پاسخ Geocoding شامل وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال‌زدایی باشد تا به شما در پیگیری دلیل عدم کارکرد geocoding کمک کند. فیلد "status" ممکن است حاوی مقادیر زیر باشد:
-
"OK"نشان می‌دهد که هیچ خطایی رخ نداده است؛ آدرس با موفقیت تجزیه شده و حداقل یک کد جغرافیایی بازگردانده شده است. -
"ZERO_RESULTS"نشان می‌دهد که کد جغرافیایی موفقیت‌آمیز بوده اما هیچ نتیجه‌ای برنگردانده است. این ممکن است در صورتی رخ دهد که به کد جغرافیایی یکaddressناموجود داده شده باشد. -
OVER_DAILY_LIMITبه هر یک از موارد زیر اشاره دارد:- کلید API موجود نیست یا نامعتبر است.
- پرداخت در حساب شما فعال نشده است.
- از سقف مصرف تعیین‌شده توسط خود کاربر، عبور شده است.
- روش پرداخت ارائه شده دیگر معتبر نیست (برای مثال، اعتبار کارت اعتباری منقضی شده است).
برای یادگیری نحوه رفع این مشکل، به سوالات متداول نقشه‌ها مراجعه کنید.
-
"OVER_QUERY_LIMIT"نشان می‌دهد که از سهمیه خود فراتر رفته‌اید. -
"REQUEST_DENIED"نشان می‌دهد که درخواست شما رد شده است. -
"INVALID_REQUEST"عموماً نشان می‌دهد که عبارت جستجو (address،componentsیاlatlng) وجود ندارد. -
"UNKNOWN_ERROR"نشان می‌دهد که درخواست به دلیل خطای سرور قابل پردازش نیست. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.
پیام‌های خطا
وقتی geocoder کد وضعیتی غیر از OK را برمی‌گرداند، ممکن است یک فیلد error_message اضافی در شیء پاسخ Geocoding وجود داشته باشد. این فیلد حاوی اطلاعات دقیق‌تری در مورد دلایل کد وضعیت داده شده است.
نتایج
وقتی geocoder نتایج را برمی‌گرداند، آنها را در یک آرایه results (JSON) قرار می‌دهد. حتی اگر geocoder هیچ نتیجه‌ای برنگرداند (مثلاً اگر آدرس وجود نداشته باشد)، باز هم یک آرایه results خالی برمی‌گرداند. (پاسخ‌های XML شامل صفر یا چند عنصر <result> هستند.)
یک نتیجه‌ی معمول شامل فیلدهای زیر است:
- آرایه
types[]نوع نتیجه برگشتی را نشان می‌دهد. این آرایه شامل مجموعه‌ای از صفر یا چند برچسب است که نوع ویژگی برگشتی در نتیجه را مشخص می‌کند. به عنوان مثال، یک کد جغرافیایی "شیکاگو" "locality" را برمی‌گرداند که نشان می‌دهد "شیکاگو" یک شهر است و همچنین "political" را برمی‌گرداند که نشان می‌دهد یک نهاد سیاسی است. وقتی هیچ نوع شناخته‌شده‌ای برای آن جزء آدرس وجود ندارد، ممکن است اجزا یک آرایه انواع خالی داشته باشند. API ممکن است در صورت نیاز مقادیر نوع جدیدی اضافه کند. برای اطلاعات بیشتر، به Address types و address components مراجعه کنید. -
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بر اساس آدرس درخواستی متفاوت است و می‌تواند در طول زمان برای همان آدرس تغییر کند. یک جزء می‌تواند موقعیت خود را در آرایه تغییر دهد. نوع جزء می‌تواند تغییر کند. یک جزء خاص ممکن است در پاسخ بعدی وجود نداشته باشد.
برای مدیریت آرایه‌ای از اجزا، باید پاسخ را تجزیه کرده و مقادیر مناسب را از طریق عبارات انتخاب کنید. به راهنمای تجزیه پاسخ مراجعه کنید.
-
-
postcode_localities[]آرایه‌ای است که حداکثر ۱۰۰ منطقه‌ی موجود در یک کد پستی را نشان می‌دهد. این فقط زمانی وجود دارد که نتیجه یک کد پستی باشد که شامل چندین منطقه‌ی محلی باشد. -
geometryشامل اطلاعات زیر است:-
locationشامل مقدار طول و عرض جغرافیایی با کد جغرافیایی است. برای جستجوی آدرس‌های معمولی، این فیلد معمولاً مهمترین است. location_typeداده‌های اضافی در مورد مکان مشخص شده را ذخیره می‌کند. مقادیر زیر در حال حاضر پشتیبانی می‌شوند:-
"ROOFTOP"نشان می‌دهد که نتیجه‌ی برگردانده شده یک کد جغرافیایی دقیق است که برای آن اطلاعات مکانی دقیقی تا دقت آدرس خیابان داریم. -
"RANGE_INTERPOLATED"نشان می‌دهد که نتیجه‌ی برگردانده شده، تقریبی (معمولاً در یک جاده) را نشان می‌دهد که بین دو نقطه‌ی دقیق (مانند تقاطع‌ها) درون‌یابی شده است. نتایج درون‌یابی شده معمولاً زمانی بازگردانده می‌شوند که کدهای جغرافیایی پشت بام برای آدرس خیابان در دسترس نباشند. -
"GEOMETRIC_CENTER"نشان می‌دهد که نتیجه‌ی برگردانده شده، مرکز هندسی یک نتیجه مانند یک چندخطی (مثلاً یک خیابان) یا چندضلعی (منطقه) است. -
"APPROXIMATE"نشان می‌دهد که نتیجه‌ی برگشتی تقریبی است.
-
-
viewportشامل viewport پیشنهادی برای نمایش نتیجه‌ی برگشتی است که به صورت دو مقدار طول و عرض جغرافیایی مشخص شده و گوشه‌یsouthwestوnortheastکادر محدوده‌ی viewport را تعریف می‌کند. عموماً از viewport برای قاب‌بندی نتیجه هنگام نمایش آن به کاربر استفاده می‌شود. -
bounds(که به صورت اختیاری برگردانده می‌شود) کادر مرزی را ذخیره می‌کند که می‌تواند به طور کامل نتیجه‌ی برگشتی را در خود جای دهد. توجه داشته باشید که این مرزها ممکن است با نمای پیشنهادی مطابقت نداشته باشند. (برای مثال، سانفرانسیسکو شامل جزایر فارالون است که از نظر فنی بخشی از شهر هستند، اما احتمالاً نباید در نمای دید برگردانده شوند.)
-
-
plus_code(به Open Location Code و Plus codes مراجعه کنید) یک مرجع مکانی کدگذاری شده است که از مختصات طول و عرض جغرافیایی گرفته شده و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچکتر. کدهای پلاس می‌توانند به عنوان جایگزینی برای آدرس خیابان‌ها در مکان‌هایی که آدرس وجود ندارد (جایی که ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نامگذاری نشده‌اند) استفاده شوند. API همیشه کدهای پلاس را برنمی‌گرداند.وقتی سرویس یک کد پلاس برمی‌گرداند، به صورت یک کد سراسری و یک کد مرکب قالب‌بندی می‌شود:
-
global_codeیک کد ناحیه‌ای ۴ کاراکتری و یک کد محلی ۶ کاراکتری یا بیشتر است (۸۴۹VCWC8+R9). -
compound_codeیک کد محلی ۶ کاراکتری یا بیشتر با موقعیت مکانی صریح (CWC8+R9، مانتین ویو، کالیفرنیا، ایالات متحده) است. این محتوا را به صورت برنامه‌نویسی تجزیه نکنید.
-
partial_matchنشان می‌دهد که geocoder تطابق دقیقی برای درخواست اصلی برنگردانده است، اگرچه توانسته بخشی از آدرس درخواستی را مطابقت دهد. شما می‌توانید درخواست اصلی را از نظر غلط املایی و/یا آدرس ناقص بررسی کنید.تطابق‌های جزئی اغلب برای آدرس‌های خیابانی رخ می‌دهند که در محلی که در درخواست وارد می‌کنید وجود ندارند. تطابق‌های جزئی همچنین ممکن است زمانی برگردانده شوند که یک درخواست با دو یا چند مکان در یک محل مطابقت داشته باشد. به عنوان مثال، "خیابان هیلپار، بریستول، انگلستان" یک تطابق جزئی برای هر دو خیابان هنری و خیابان هنریتا برمی‌گرداند. توجه داشته باشید که اگر درخواستی شامل یک جزء آدرس با املای اشتباه باشد، سرویس کدگذاری جغرافیایی ممکن است یک آدرس جایگزین پیشنهاد دهد. پیشنهادهایی که به این روش فعال می‌شوند نیز به عنوان یک تطابق جزئی علامت‌گذاری می‌شوند.
-
place_idیک شناسه منحصر به فرد است که می‌تواند با سایر APIهای گوگل مورد استفاده قرار گیرد. برای مثال، می‌توانید ازplace_idدر یک درخواست Places API برای دریافت جزئیات یک کسب و کار محلی، مانند شماره تلفن، ساعات کاری، نظرات کاربران و موارد دیگر استفاده کنید. به نمای کلی شناسه مکان مراجعه کنید.
انواع آدرس و انواع مؤلفه آدرس
آرایه‌ی types در پاسخ، نوع آدرس را نشان می‌دهد. نمونه‌هایی از انواع آدرس شامل آدرس خیابان، کشور یا یک نهاد سیاسی است. آرایه‌ی types در فیلد address_component نوع هر بخش از آدرس را نشان می‌دهد. مثال‌هایی از جمله شماره خیابان یا کشور.
آدرس‌ها ممکن است انواع مختلفی داشته باشند. این انواع ممکن است به عنوان «برچسب» در نظر گرفته شوند. برای مثال، بسیاری از شهرها با انواع political و locality برچسب‌گذاری شده‌اند.
انواع زیر پشتیبانی می‌شوند و در هر دو آرایه نوع آدرس و نوع جزء آدرس بازگردانده می‌شوند:
| نوع آدرس | توضیحات |
|---|---|
street_address | یک آدرس دقیق خیابان. |
route | یک مسیر نامگذاری شده (مانند "US 101"). |
intersection | تقاطع اصلی، معمولاً بین دو جاده اصلی |
political | یک نهاد سیاسی. معمولاً این نوع، چندضلعیِ نوعی مدیریت شهری را نشان می‌دهد. |
country | نهاد سیاسی ملی، و معمولاً بالاترین نوع مرتبۀ برگردانده شده توسط ژئوکودر است. |
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 | محل ایستگاه اتوبوس، قطار یا وسایل حمل و نقل عمومی. |
بایاس کردن ویوپورت
در یک درخواست Geocoding، می‌توانید به سرویس Geocoding دستور دهید که نتایج درون یک نمای مشخص (که به صورت یک کادر محصورکننده بیان می‌شود) را ترجیح دهد. شما این کار را با تنظیم پارامتر bounds در URL درخواست انجام می‌دهید.
پارامتر bounds مختصات عرض/طول جغرافیایی گوشه‌های جنوب غربی و شمال شرقی این کادر مرزی را با استفاده از کاراکتر پایپ ( | ) برای جدا کردن مختصات تعریف می‌کند.
برای مثال، یک کد جغرافیایی برای "واشنگتن" معمولاً ایالت واشنگتن ایالات متحده را برمی‌گرداند:
درخواست:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
پاسخ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
با این حال، اضافه کردن یک آرگومان bounds که یک کادر مرزی را در اطراف بخش شمال شرقی ایالات متحده تعریف می‌کند، منجر به این ژئوکد می‌شود که شهر واشنگتن دی سی را برمی‌گرداند:
درخواست:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
پاسخ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
بایاس منطقه
در یک درخواست Geocoding، می‌توانید با استفاده از پارامتر region به سرویس Geocoding دستور دهید تا نتایجی را که به یک منطقه خاص متمایل هستند، برگرداند. این پارامتر یک آرگومان ccTLD (دامنه سطح بالای کد کشور) می‌گیرد که گرایش منطقه را مشخص می‌کند. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، به جز برخی استثنائات قابل توجه. به عنوان مثال، ccTLD بریتانیا "uk" ( .co.uk ) است در حالی که کد ISO 3166-1 آن "gb" است (از نظر فنی برای موجودیت "بریتانیای کبیر و ایرلند شمالی").
نتایج کدگذاری جغرافیایی می‌تواند برای هر دامنه‌ای که برنامه اصلی نقشه‌های گوگل رسماً در آن راه‌اندازی شده است، جانبدارانه باشد. توجه داشته باشید که جانبدارانه بودن فقط نتایج مربوط به یک دامنه خاص را ترجیح می‌دهد ؛ اگر نتایج مرتبط‌تری خارج از این دامنه وجود داشته باشد، ممکن است گنجانده شوند.
برای مثال، یک کد جغرافیایی برای "تولدو" این نتیجه را برمی‌گرداند، زیرا دامنه پیش‌فرض برای API کد جغرافیایی روی ایالات متحده تنظیم شده است. درخواست:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
پاسخ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
یک درخواست ژئوکدینگ برای "تولدو" با region=es (اسپانیا)، شهر اسپانیایی را برمی‌گرداند.
درخواست:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
پاسخ:
{
"results" : [
{
"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" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
فیلتر کردن کامپوننت
در یک پاسخ Geocoding، API مربوط به Geocoding می‌تواند نتایج آدرس محدود به یک منطقه خاص را برگرداند. می‌توانید این محدودیت را با استفاده از فیلتر components مشخص کنید. یک فیلتر شامل لیستی از جفت‌های component:value که با یک pipe ( | ) از هم جدا شده‌اند. مقادیر فیلتر از همان روش‌های تصحیح املا و تطبیق جزئی مانند سایر درخواست‌های Geocoding پشتیبانی می‌کنند. اگر geocoder یک تطبیق جزئی برای یک فیلتر component پیدا کند، پاسخ شامل یک فیلد partial_match خواهد بود.
components که می‌توانند فیلتر شوند عبارتند از:
-
postal_codeباpostal_codeوpostal_code_prefixمطابقت دارد. -
countryبا نام کشور یا کد دو حرفی ISO 3166-1 کشور مطابقت دارد. این API از استاندارد ISO برای تعریف کشورها پیروی می‌کند و فیلتر کردن زمانی که از کد ISO مربوطه برای کشور استفاده می‌شود، بهترین عملکرد را دارد.
components زیر ممکن است برای تأثیرگذاری بر نتایج مورد استفاده قرار گیرند، اما اجرا نخواهند شد:
-
routeبا نام بلند یا کوتاه یک مسیر مطابقت دارد. - تطابق
localityبا انواعlocalityوsublocality. -
administrative_areaبا تمام سطوحadministrative_areaمطابقت دارد.
نکاتی در مورد فیلتر کردن اجزا:
- این فیلترهای کامپوننت را در درخواست‌ها تکرار نکنید، در غیر این صورت API
Invalid_requestبرمی‌گرداند:country،postal_code،route - اگر درخواست شامل فیلترهای کامپوننت تکراری باشد، API آن فیلترها را به عنوان AND ارزیابی می‌کند، نه OR.
- نتایج با نقشه‌های گوگل سازگار است، که گاهی اوقات پاسخ‌های غیرمنتظره
ZERO_RESULTSمی‌دهد. استفاده از تکمیل خودکار مکان ممکن است در برخی موارد نتایج بهتری ارائه دهد. برای کسب اطلاعات بیشتر، به این سوالات متداول مراجعه کنید. - برای هر مؤلفه آدرس، آن را یا در پارامتر
addressیا در فیلترcomponentsمشخص کنید، اما نه هر دو. تعیین مقادیر یکسان در هر دو ممکن است منجر بهZERO_RESULTSشود.
یک کد جغرافیایی برای "خیابان های، هستینگز" با components=country:GB نتیجه را به جای هستینگز-آن-هادسون، ایالات متحده، در هستینگز، انگلستان برمی‌گرداند.
درخواست:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
پاسخ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
درخواست کد جغرافیایی برای موقعیت مکانی "سانتا کروز" با components=country:ES سانتا کروز د تنریفه در جزایر قناری، اسپانیا را برمی‌گرداند.
درخواست:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
پاسخ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
فیلتر کردن کامپوننت فقط در صورتی پاسخ ZERO_RESULTS را برمی‌گرداند که فیلترهایی ارائه دهید که یکدیگر را مستثنی کنند.
درخواست:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
پاسخ:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
شما می‌توانید با استفاده از فیلتر components ، پرس‌وجوهای معتبری بدون پارامتر آدرس ایجاد کنید. (هنگام ژئوکدینگ یک آدرس کامل، اگر درخواست شامل نام و شماره ساختمان‌ها باشد، پارامتر address الزامی است.)
درخواست:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
پاسخ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}