درخواست کنید
درخواست Geocoding API به شکل زیر است:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
که در آن outputFormat
ممکن است یکی از مقادیر زیر باشد:
-
json
(توصیه می شود) خروجی را در نشانه گذاری شی جاوا اسکریپت (JSON) نشان می دهد. یا -
xml
خروجی را در XML نشان می دهد
HTTPS مورد نیاز است.
برخی از پارامترها مورد نیاز هستند در حالی که برخی اختیاری هستند. همانطور که در URL ها استاندارد است، پارامترها با استفاده از علامت علامت ( &
) از هم جدا می شوند.
در ادامه این صفحه ژئوکدینگ و ژئوکدینگ معکوس به طور جداگانه توضیح داده شده است، زیرا پارامترهای مختلفی برای هر نوع درخواست موجود است.
پارامترهای ژئوکدینگ (جستجوی طول و عرض جغرافیایی).
پارامترهای مورد نیاز در درخواست ژئوکدینگ:
-
key
- کلید API برنامه شما. این کلید درخواست شما را برای اهداف مدیریت سهمیه شناسایی می کند. نحوه گرفتن کلید را بیاموزید. شما باید
address
یاcomponents
یا هر دو را در یک درخواست مشخص کنید:-
address
- آدرس خیابان یا کد مثبتی که میخواهید به صورت جغرافیایی کدگذاری کنید. نشانی ها را مطابق با فرمت مورد استفاده سرویس پست ملی کشور مربوطه مشخص کنید. از عناصر آدرس اضافی مانند نام تجاری و شماره واحد، سوئیت یا طبقه باید اجتناب شود. عناصر آدرس خیابان باید با فاصله مشخص شوند (در اینجا به صورت url-escaped به%20
نشان داده شده است):address=24%20Sussex%20Drive%20Ottawa%20ON
کدهای بعلاوه را همانطور که در اینجا نشان داده شده است قالب بندی کنید (علائم بعلاوه به url-escape به%2B
و فاصله ها به url-escape به%20
می شوند):- کد جهانی یک کد منطقه 4 کاراکتری و کد محلی 6 کاراکتری یا بیشتر است (849VCWC8+R9
849VCWC8%2BR9
است). - کد ترکیبی یک کد محلی 6 کاراکتری یا بیشتر با مکان صریح است (CWC8+R9 Mountain View, CA, USA
CWC8%2BR9%20Mountain%20View%20CA%20USA
است).
- کد جهانی یک کد منطقه 4 کاراکتری و کد محلی 6 کاراکتری یا بیشتر است (849VCWC8+R9
-
components
- یک فیلتر اجزا با عناصر جدا شده توسط یک لوله (|
). در صورت ارائهaddress
فیلتر اجزاء نیز به عنوان یک پارامتر اختیاری پذیرفته می شود. هر عنصر در فیلتر کامپوننت ها از یک جفتcomponent:value
تشکیل شده است و نتایج حاصل از ژئوکدر را به طور کامل محدود می کند. اطلاعات بیشتر در مورد فیلتر کردن اجزا را در زیر مشاهده کنید.
-
برای راهنمایی بیشتر به سوالات متداول مراجعه کنید.
پارامترهای اختیاری در یک درخواست Geocoding:
-
bounds
- کادر مرزی درگاه دید که در آن ژئوکد بایاس به وضوح بیشتر می شود. این پارامتر فقط بر نتایج geocoder تأثیر می گذارد، نه کاملاً محدود. (برای اطلاعات بیشتر به Viewport Biasing در زیر مراجعه کنید.) -
language
- زبانی که نتایج را در آن برگرداند.- لیست زبان های پشتیبانی شده را ببینید. Google اغلب زبان های پشتیبانی شده را به روز می کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر
language
ارائه نشده باشد، geocoder سعی می کند از زبان ترجیحی همانطور که در هدرAccept-Language
یا زبان اصلی دامنه ای که درخواست از آن ارسال می شود، استفاده کند. - geocoder تمام تلاش خود را می کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرسهای خیابان را به زبان محلی برمیگرداند و به اسکریپتی که در صورت لزوم توسط کاربر قابل خواندن است، با رعایت زبان ترجیحی، ترجمه میشود. همه آدرس های دیگر به زبان ترجیحی برگردانده می شوند. اجزای آدرس همه به یک زبان بازگردانده می شوند که از جزء اول انتخاب شده است.
- اگر نامی در زبان ترجیحی موجود نباشد، geocoder از نزدیکترین تطابق استفاده می کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن آنها انتخاب میکند و ترتیب بازگرداندن آنها دارد. geocoder بسته به زبان، اختصارات را متفاوت تفسیر می کند، مانند اختصارات انواع خیابان، یا مترادف هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نیستند. به عنوان مثال، utca و tér به ترتیب مترادف خیابان و میدان در مجارستانی هستند.
-
region
- کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. این پارامتر فقط بر نتایج geocoder تأثیر می گذارد، نه کاملاً محدود. (برای اطلاعات بیشتر به منطقه Biasing در زیر مراجعه کنید.) این پارامتر همچنین می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد. -
components
- یک فیلتر اجزا با عناصر جدا شده توسط یک لوله (|
). اگر درخواست شاملaddress
نباشد، فیلتر اجزا لازم است. هر عنصر در فیلتر کامپوننت ها از یک جفتcomponent:value
تشکیل شده است و نتایج حاصل از ژئوکدر را به طور کامل محدود می کند. اطلاعات بیشتر در مورد فیلتر کردن اجزا را در زیر مشاهده کنید. -
extra_computations
- از این پارامتر برای مشخص کردن ویژگی های اضافی زیر در پاسخ استفاده کنید:-
ADDRESS_DESCRIPTORS
- برای جزئیات بیشتر به توصیفگرهای آدرس مراجعه کنید. -
BUILDING_AND_ENTRANCES
— برای جزئیات بیشتر ورودی ها و خطوط کلی ساختمان را ببینید.
extra_computations
را در درخواست هر ویژگی بگنجانید، برای مثال:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
-
پاسخ ها
پاسخهای کدگذاری جغرافیایی در قالبی که با پرچم output
در درخواست URL نشان داده شده است، یا به صورت پیشفرض در قالب JSON برگردانده میشوند.
در این مثال، Geocoding API یک پاسخ json
برای یک پرس و جو در آدرس "1600 Amphitheatre Parkway, Mountain View, CA" درخواست می کند.
این درخواست با استفاده از پرچم 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، برگه های زیر را انتخاب کنید.
JSON
{ "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"
برای جستجوی آدرس بازگردانده میشود، هرچند زمانی که جستارهای آدرس مبهم هستند، geocoder ممکن است چندین نتیجه را برگرداند.
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 حاوی وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال زدایی باشد تا به شما در ردیابی علت کار نکردن کد جغرافیایی کمک کند. فیلد "status"
ممکن است حاوی مقادیر زیر باشد:
-
"OK"
نشان می دهد که هیچ خطایی رخ نداده است. آدرس با موفقیت تجزیه شد و حداقل یک ژئوکد برگردانده شد. -
"ZERO_RESULTS"
نشان می دهد که ژئوکد موفقیت آمیز بود اما هیچ نتیجه ای نداشت. این ممکن است در صورتی رخ دهد که geocoder یکaddress
غیرموجود ارسال شده باشد. -
OVER_DAILY_LIMIT
هر یک از موارد زیر را نشان می دهد:- کلید API وجود ندارد یا نامعتبر است.
- صورتحساب در حساب شما فعال نشده است.
- از حد مجاز استفاده از خود فراتر رفته است.
- روش پرداخت ارائه شده دیگر معتبر نیست (مثلاً اعتبار کارت اعتباری منقضی شده است).
برای آشنایی با نحوه رفع این مشکل، سؤالات متداول Maps را ببینید.
-
"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[]
نوع نتیجه برگشتی را نشان می دهد. این آرایه حاوی مجموعهای از صفر یا چند تگ است که نوع ویژگی برگردانده شده در نتیجه را مشخص میکند. برای مثال، ژئوکد «شیکاگو» «محلی» را برمیگرداند که نشان میدهد «شیکاگو» یک شهر است، و همچنین «سیاسی» را برمیگرداند که نشان میدهد یک نهاد سیاسی است. هنگامی که هیچ نوع شناخته شده ای برای آن جزء آدرس وجود ندارد، کامپوننت ها ممکن است یک آرایه انواع خالی داشته باشند. API ممکن است در صورت نیاز مقادیر نوع جدیدی را اضافه کند. برای اطلاعات بیشتر، انواع آدرس و اجزای آدرس را ببینید. -
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
بر اساس آدرس درخواستی متفاوت است و می تواند در طول زمان برای همان آدرس تغییر کند. یک جزء می تواند موقعیت خود را در آرایه تغییر دهد. نوع جزء می تواند تغییر کند. ممکن است یک جزء خاص در پاسخ بعدی گم شده باشد.
برای مدیریت آرایه مولفهها، باید پاسخ را تجزیه کنید و مقادیر مناسب را از طریق عبارتها انتخاب کنید. راهنمای تجزیه یک پاسخ را ببینید.
-
-
postcode_localities[]
آرایهای است که حداکثر 100 محل موجود در یک کد پستی را نشان میدهد. این تنها زمانی وجود دارد که نتیجه یک کد پستی باشد که دارای چندین محل باشد. -
geometry
حاوی اطلاعات زیر است:-
location
شامل طول جغرافیایی و مقدار طول جغرافیایی کد شده است. برای جستجوی آدرس های معمولی، این فیلد معمولاً مهم ترین است. location_type
داده های اضافی را در مورد مکان مشخص شده ذخیره می کند. مقادیر زیر در حال حاضر پشتیبانی می شوند:-
"ROOFTOP"
نشان می دهد که نتیجه بازگشتی یک ژئوکد دقیق است که ما اطلاعات موقعیت مکانی را با دقت آدرس خیابان داریم. -
"RANGE_INTERPOLATED"
نشان می دهد که نتیجه برگشتی یک تقریب (معمولاً در یک جاده) را منعکس می کند که بین دو نقطه دقیق (مانند تقاطع ها) درون یابی شده است. نتایج درون یابی عموماً زمانی که ژئوکدهای روی پشت بام برای یک آدرس خیابان در دسترس نباشند، برمی گردند. -
"GEOMETRIC_CENTER"
نشان می دهد که نتیجه برگشتی مرکز هندسی نتیجه ای مانند چند خط (مثلاً یک خیابان) یا چند ضلعی (منطقه) است. -
"APPROXIMATE"
نشان می دهد که نتیجه برگشتی تقریبی است.
-
-
viewport
حاوی نمای پیشنهادی برای نمایش نتیجه برگشتی است که به عنوان دو مقدار طول و عرض جغرافیایی مشخص شده است که گوشهsouthwest
وnortheast
کادر محدودکننده دیدگاه را مشخص می کند. به طور کلی از viewport برای قاب بندی نتیجه هنگام نمایش آن به کاربر استفاده می شود. -
bounds
(به صورت اختیاری برگردانده می شود) کادر محدود کننده را ذخیره می کند که می تواند به طور کامل حاوی نتیجه برگشتی باشد. توجه داشته باشید که این کران ممکن است با نمای پیشنهادی مطابقت نداشته باشد. (به عنوان مثال، سانفرانسیسکو شامل جزایر فارالون است که از نظر فنی بخشی از شهر هستند، اما احتمالاً نباید در نمای دید بازگردانده شوند.)
-
-
plus_code
(به کد مکان باز و کدهای بعلاوه مراجعه کنید) یک مرجع مکان رمزگذاری شده است که از مختصات طول و عرض جغرافیایی مشتق شده است که مساحتی را نشان می دهد: 1/8000 درجه در 1/8000 درجه (حدود 14 متر در 14 متر در خط استوا) یا کوچکتر کدهای پلاس را می توان به عنوان جایگزینی برای آدرس های خیابان در مکان هایی که آدرس وجود ندارد (جایی که ساختمان ها شماره گذاری نمی شوند یا خیابان ها نام گذاری نمی شوند) استفاده می شود. API همیشه کدهای پلاس را بر نمی گرداند.هنگامی که سرویس یک کد مثبت را برمی گرداند، به عنوان یک کد جهانی و یک کد ترکیبی قالب بندی می شود:
-
global_code
یک کد منطقه ای 4 کاراکتری و کد محلی 6 کاراکتری یا بیشتر است (849VCWC8+R9). -
compound_code
یک کد محلی 6 کاراکتری یا بیشتر با مکان صریح است (CWC8+R9, Mountain View, CA, USA). این محتوا را به صورت برنامه نویسی تجزیه نکنید.
-
partial_match
نشان می دهد که geocoder مطابقت دقیقی با درخواست اصلی برنگردانده است، اگرچه می تواند بخشی از آدرس درخواستی را مطابقت دهد. ممکن است بخواهید درخواست اصلی برای غلط املایی و/یا آدرس ناقص را بررسی کنید.تطابق جزئی اغلب برای آدرسهای خیابانی رخ میدهد که در محلی که در درخواست عبور میکنید وجود ندارد. زمانی که درخواستی با دو یا چند مکان در همان محل مطابقت داشته باشد، مسابقات جزئی نیز ممکن است برگردانده شوند. به عنوان مثال، "Hillpar St, Bristol, UK" یک مسابقه جزئی را برای خیابان هنری و خیابان هنریتا برمی گرداند. توجه داشته باشید که اگر یک درخواست شامل یک جزء آدرس غلط املایی باشد، سرویس کدگذاری جغرافیایی ممکن است یک آدرس جایگزین پیشنهاد دهد. پیشنهادهایی که از این طریق فعال می شوند نیز به عنوان تطابق جزئی علامت گذاری می شوند.
-
place_id
یک شناسه منحصر به فرد است که می تواند با سایر API های Google استفاده شود. برای مثال، میتوانید ازplace_id
در درخواست Places API برای دریافت جزئیات یک کسبوکار محلی، مانند شماره تلفن، ساعات کاری، نظرات کاربران و موارد دیگر استفاده کنید. نمای کلی شناسه مکان را ببینید.
نقاط ناوبری
قسمتnavigation_points
در پاسخ Geocoding حاوی لیستی از نقاطی است که برای پیمایش به مکان مفید هستند. به طور خاص، آنها باید به عنوان نقطه شروع یا پایان هنگام مسیریابی در یک شبکه جاده ای از یا به مکان مورد استفاده قرار گیرند. هر نقطه ناوبری حاوی مقادیر زیر است:-
location
شامل مقدار طول و عرض جغرافیایی نقطه ناوبری است. این مکان همیشه بسیار نزدیک به شبکه جاده خواهد بود و نشان دهنده یک توقف یا نقطه شروع ایده آل برای پیمایش به و از یک مکان است. این نقطه عمداً کمی از خط مرکزی جاده منحرف شده است تا به وضوح کنار جاده که مکان در آن قرار دارد مشخص شود. -
restricted_travel_modes
فهرستی از حالتهای سفر است که نقطه ناوبری از آنها قابل دسترسی نیست: -
"DRIVE"
حالت سفر مربوط به مسیرهای رانندگی است. -
"WALK"
حالت سفر مربوط به مسیرهای پیاده روی است.
انواع آدرس و انواع اجزای آدرس
آرایه types[]
در نتیجه نشان دهنده نوع آدرس است. نمونههایی از انواع آدرسها عبارتند از آدرس خیابان، کشور یا یک نهاد سیاسی. همچنین یک آرایه types[]
در address_components[]
وجود دارد که نوع هر قسمت از آدرس را نشان میدهد. به عنوان مثال می توان به شماره خیابان یا کشور اشاره کرد. (در زیر لیست کاملی از انواع ارائه شده است.) آدرس ها ممکن است چندین نوع داشته باشند. انواع ممکن است "برچسب" در نظر گرفته شوند. به عنوان مثال، بسیاری از شهرها با نوع 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
مکان اتوبوس، قطار یا ایستگاه حمل و نقل عمومی را نشان می دهد.
بایاس پورت دید
در یک درخواست Geocoding، میتوانید به سرویس Geocoding دستور دهید که نتایج را در یک viewport (که به صورت یک کادر محدود بیان میشود) ترجیح دهد. شما این کار را در URL درخواست با تنظیم پارامتر bounds
انجام می دهید.
پارامتر 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، می توانید به سرویس Geocoding دستور دهید تا با استفاده از پارامتر region
، نتایج بایاس شده را به یک منطقه خاص بازگرداند. این پارامتر یک آرگومان ccTLD (دامنه سطح بالای کد کشور) را می گیرد که بایاس منطقه را مشخص می کند. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با برخی استثناهای قابل توجه. به عنوان مثال، ccTLD بریتانیا "uk" ( .co.uk
) است در حالی که کد ISO 3166-1 آن "gb" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی").
نتایج کدگذاری جغرافیایی میتواند برای هر دامنهای که برنامه اصلی Google Maps در آن به طور رسمی راهاندازی شده است، سوگیری داشته باشد. توجه داشته باشید که بایاسینگ فقط نتایج را برای یک دامنه خاص ترجیح می دهد . اگر نتایج مرتبط تری در خارج از این دامنه وجود داشته باشد، ممکن است آنها را شامل شود.
به عنوان مثال، یک geocode برای "Toledo" این نتیجه را برمی گرداند، زیرا دامنه پیش فرض برای Geocoding 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"
}
درخواست ژئوکدینگ برای "Toledo" با 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
که توسط یک لوله ( |
) از هم جدا شدهاند. مقادیر فیلتر از همان روشهای تصحیح املا و تطبیق جزئی مانند سایر درخواستهای Geocoding پشتیبانی میکنند. اگر geocoder یک تطابق جزئی برای یک فیلتر جزء پیدا کند، پاسخ حاوی یک قسمت 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.
- نتایج با Google Maps سازگار است، که گاهی اوقات
ZERO_RESULTS
پاسخ غیرمنتظره می دهد. استفاده از تکمیل خودکار مکان ممکن است نتایج بهتری در برخی موارد استفاده ارائه دهد. برای کسب اطلاعات بیشتر، این سؤالات متداول را ببینید. - برای هر جزء آدرس، یا آن را در پارامتر
address
یا در فیلترcomponents
مشخص کنید، اما نه هر دو. تعیین مقادیر یکسان در هر دو ممکن است منجر بهZERO_RESULTS
شود.
یک ژئوکد برای "High St, Hastings" با 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"
}