ژئوکدینگ مکان به شما امکان می‌دهد آدرس را از یک شناسه مکان بازیابی کنید.
شناسه‌های مکان، یک مکان را به طور منحصر به فرد در پایگاه داده Google Places و در Google Maps مشخص می‌کنند. هنگام کدگذاری جغرافیایی یک آدرس ، شناسه‌های مکان را بازیابی کنید. همچنین می‌توانید شناسه مکان را از بسیاری از APIهای دیگر، مانند جزئیات مکان (جدید) ، جستجوی متن (جدید) و جستجوی نزدیک (جدید) بازیابی کنید.
درخواست‌های مربوط به مختصات جغرافیایی را ثبت کنید
یک درخواست مختصات جغرافیایی مکان، یک درخواست HTTP GET به شکل زیر است:
https://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID
که در آن PLACE_ID شامل شناسه مکان مورد نظر است.
سایر پارامترها را به عنوان پارامترهای URL یا برای پارامترهایی مانند کلید API یا ماسک فیلد، در هدرها به عنوان بخشی از درخواست GET ارسال کنید. برای مثال:
https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY
یا در یک دستور curl:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
استفاده از OAuth برای ارسال درخواست
API ژئوکدینگ نسخه ۴ از OAuth 2.0 برای احراز هویت پشتیبانی می‌کند. برای استفاده از OAuth با API ژئوکدینگ، باید به توکن OAuth دامنه صحیح اختصاص داده شود. API ژئوکدینگ از دامنه‌های زیر برای استفاده با ژئوکدینگ مکان پشتیبانی می‌کند:
-
https://www.googleapis.com/auth/maps-platform.geocode— قابل استفاده با تمام نقاط پایانی API مربوط به Geocoding. -
https://www.googleapis.com/auth/maps-platform.geocode.place— فقط باGeocodePlaceبرای ژئوکدینگ مکان استفاده شود.
همچنین، می‌توانید از دامنه عمومی https://www.googleapis.com/auth/cloud-platform برای همه نقاط پایانی API ژئوکدینگ استفاده کنید. این دامنه در طول توسعه مفید است، اما نه در مرحله تولید، زیرا یک دامنه عمومی است که امکان دسترسی به همه نقاط پایانی را فراهم می‌کند.
برای اطلاعات بیشتر و مثال‌ها، به بخش «استفاده از OAuth» مراجعه کنید.
پاسخ‌های مکان‌یابی با استفاده از مختصات جغرافیایی
تابع مکان‌یابی جغرافیایی (Place geocoding) یک شیء GeocodeResult را برمی‌گرداند که نشان‌دهنده‌ی مکانی متناظر با شناسه‌ی مکان (place ID) است.
شیء کامل JSON به شکل زیر است:
{ "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw", "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "location": { "latitude": 37.4220541, "longitude": -122.08532419999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4209489697085, "longitude": -122.08846930000001 }, "high": { "latitude": 37.4236469302915, "longitude": -122.0829156 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] } ], "types": [ "establishment", "point_of_interest" ] }
پارامترهای مورد نیاز
-
place— شناسه مکان مکانی که می‌خواهید آدرس قابل خواندن توسط انسان را برای آن بدست آورید. شناسه مکان یک شناسه منحصر به فرد است که می‌تواند با سایر APIهای گوگل مورد استفاده قرار گیرد. به عنوان مثال، می‌توانید ازplaceIDبرگردانده شده توسط API Roads برای دریافت آدرس یک نقطه فشرده شده استفاده کنید. برای اطلاعات بیشتر در مورد شناسه‌های مکان، به شناسه‌های مکان مراجعه کنید.
پارامترهای اختیاری
زبانکد
زبانی که نتایج با آن برگردانده می‌شوند.
- فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر
languageCodeارائه نشود، API به طور پیش‌فرضenرا در نظر می‌گیرد. اگر کد زبان نامعتبری را مشخص کنید، API خطایINVALID_ARGUMENTرا برمی‌گرداند. - این API تمام تلاش خود را می‌کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به اسکریپتی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
- اگر نامی در زبان مورد نظر موجود نباشد، API از نزدیکترین مورد منطبق استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها دارد. کدگذار جغرافیایی بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
کد منطقه
کد منطقه به عنوان یک مقدار کد CLDR دو کاراکتری . مقدار پیش‌فرضی وجود ندارد. اکثر کدهای CLDR مشابه کدهای ISO 3166-1 هستند.
هنگام ژئوکدینگ یک آدرس، ژئوکدینگ رو به جلو ، این پارامتر می‌تواند بر نتایج سرویس به منطقه مشخص شده تأثیر بگذارد، اما نمی‌تواند آن را به طور کامل محدود کند. هنگام ژئوکدینگ یک مکان یا یک مکان، ژئوکدینگ معکوس یا ژئوکدینگ مکان ، این پارامتر می‌تواند برای قالب‌بندی آدرس استفاده شود. در همه موارد، این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.