ژئوکدینگ معکوس، موقعیت مکانی روی نقشه را به آدرسی قابل خواندن برای انسان تبدیل می‌کند. شما موقعیت مکانی روی نقشه را با مختصات طول و عرض جغرافیایی آن مکان نمایش می‌دهید.
وقتی یک مکان را به صورت معکوس ژئوکد می‌کنید، پاسخ شامل موارد زیر است:
- شناسه مکان آدرس
- کدهای اضافی آدرس
- جزئیات آدرس
این API انواع مختلفی از آدرس‌ها را برمی‌گرداند، از خاص‌ترین آدرس خیابان گرفته تا نهادهای سیاسی کمتر خاص مانند محله‌ها، شهرها، شهرستان‌ها و ایالت‌ها. دقیق‌ترین آدرس معمولاً اولین نتیجه است. اگر می‌خواهید نوع خاصی از آدرس را مطابقت دهید، از پارامتر types استفاده کنید.
درخواست معکوس کردن مختصات جغرافیایی
یک درخواست ژئوکدینگ معکوس، یک درخواست HTTP GET است. می‌توانید مکان را به عنوان یک رشته بدون ساختار مشخص کنید:
https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE
یا به عنوان مجموعه‌ای ساختاریافته از مختصات طول و عرض جغرافیایی که توسط پارامترهای پرس‌وجو نمایش داده می‌شوند:
https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE
شما معمولاً هنگام پردازش اجزای موقعیت مکانی ثبت شده در فرم HTML از قالب ساختاریافته استفاده می‌کنید.
سایر پارامترها را به عنوان پارامترهای URL یا برای پارامترهایی مانند کلید API یا ماسک فیلد، در هدرها به عنوان بخشی از درخواست GET ارسال کنید. برای مثال:
یک رشته مکان بدون ساختار ارسال کنید
یک مکان بدون ساختار، مکانی است که به صورت رشته‌ای از مختصات طول و عرض جغرافیایی که با کاما از هم جدا شده‌اند، قالب‌بندی شده است:
https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?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/location/37.4225508,-122.0846338"
از یک مکان ساختار یافته عبور کنید
مکان ساختار یافته را با استفاده از پارامتر جستجوی location ، از نوع LatLng ، مشخص کنید. شیء LatLng به شما امکان می‌دهد طول و عرض جغرافیایی را به عنوان پارامترهای جستجوی جداگانه مشخص کنید:
https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338 &key=API_KEY
استفاده از 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.location— فقط باGeocodeLocationبرای ژئوکدینگ معکوس استفاده شود.
همچنین، می‌توانید از دامنه عمومی https://www.googleapis.com/auth/cloud-platform برای همه نقاط پایانی API ژئوکدینگ استفاده کنید. این دامنه در طول توسعه مفید است، اما نه در مرحله تولید، زیرا یک دامنه عمومی است که امکان دسترسی به همه نقاط پایانی را فراهم می‌کند.
برای اطلاعات بیشتر و مثال‌ها، به بخش «استفاده از OAuth» مراجعه کنید.
پاسخ جغرافیایی معکوس
ژئوکدینگ معکوس یک شیء GeocodeLocationResponse را برمی‌گرداند که شامل موارد زیر است:
آرایه
resultsاشیاءGeocodeResultکه مکان را نشان می‌دهد.ژئوکودر معکوس بیش از یک نتیجه را در آرایه
resultsبرمی‌گرداند. نتایج فقط آدرس‌های پستی نیستند، بلکه هر روشی برای نامگذاری جغرافیایی یک مکان هستند. برای مثال، هنگام ژئوکودر کردن یک نقطه در شهر شیکاگو، نقطه ژئوکودر شده ممکن است به عنوان آدرس خیابان، به عنوان شهر (شیکاگو)، به عنوان ایالت آن (ایلینوی) یا به عنوان یک کشور (ایالات متحده) مشخص شود. همه اینها برای ژئوکودر "آدرس" هستند. ژئوکودر معکوس هر یک از این انواع را به عنوان نتایج معتبر برمی‌گرداند.فیلد
plusCode، از نوعPlusCode، شامل Plus Code ای است که به بهترین شکل طول و عرض جغرافیایی در درخواست را تقریب می‌زند. علاوه بر این، هر عنصر از آرایهresultsشامل یک Plus Code است. فاصله بین Plus Code رمزگشایی شده و نقطه درخواست کمتر از 10 متر است.
شیء کامل JSON به شکل زیر است:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU", "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU", "location": { "latitude": 37.422588300000008, "longitude": -122.0846489 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.421239319708512, "longitude": -122.0859978802915 }, "high": { "latitude": 37.423937280291511, "longitude": -122.08329991970851 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "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": [ "street_address" ], "plusCode": { "globalCode": "849VCW83+PM", "compoundCode": "CW83+PM Mountain View, CA, USA" } }, { "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw", "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "location": { "latitude": 37.4220541, "longitude": -122.08532419999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4207051197085, "longitude": -122.08667318029148 }, "high": { "latitude": 37.423403080291493, "longitude": -122.08397521970851 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "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" ], "plusCode": { "globalCode": "849VCWC7+RV", "compoundCode": "CWC7+RV Mountain View, CA, USA" } }, ... ], "plusCode": { "globalCode": "849VCWF8+24H", "compoundCode": "CWF8+24H Mountain View, CA, USA" } }
پارامترهای مورد نیاز
مکان
مختصات طول و عرض جغرافیایی که مشخص می‌کنند نزدیکترین آدرس قابل خواندن برای انسان را کجا می‌خواهید.
پارامترهای اختیاری
زبانکد
زبانی که نتایج با آن برگردانده می‌شوند.
- فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر
languageCodeارائه نشود، API به طور پیش‌فرضenرا در نظر می‌گیرد. اگر کد زبان نامعتبری را مشخص کنید، API خطایINVALID_ARGUMENTرا برمی‌گرداند. - این API تمام تلاش خود را می‌کند تا آدرسی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به اسکریپتی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
- اگر نامی در زبان مورد نظر موجود نباشد، API از نزدیکترین مورد منطبق استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها دارد. کدگذار جغرافیایی بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
کد منطقه
کد منطقه به عنوان یک مقدار کد CLDR دو کاراکتری . مقدار پیش‌فرضی وجود ندارد. اکثر کدهای CLDR مشابه کدهای ISO 3166-1 هستند.
هنگام ژئوکدینگ یک آدرس، ژئوکدینگ رو به جلو ، این پارامتر می‌تواند بر نتایج سرویس به منطقه مشخص شده تأثیر بگذارد، اما نمی‌تواند آن را به طور کامل محدود کند. هنگام ژئوکدینگ یک مکان یا یک مکان، ژئوکدینگ معکوس یا ژئوکدینگ مکان ، این پارامتر می‌تواند برای قالب‌بندی آدرس استفاده شود. در همه موارد، این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.
دانه‌بندی
یک یا چند جزئیات مکانی، که به عنوان پارامترهای پرس و جوی جداگانه، همانطور که توسط
Granularityتعریف شده است، مشخص شده‌اند. اگر چندین پارامترgranularityمشخص کنید، API تمام آدرس‌هایی را که با هر یک از جزئیات مکانی مطابقت دارند، برمی‌گرداند.پارامتر
granularityجستجو را به جزئیات مکان مشخص شده محدود نمی‌کند. در عوض،granularityبه عنوان یک فیلتر پس از جستجو عمل می‌کند. API تمام نتایج مربوط بهlocationمشخص شده را دریافت می‌کند، سپس نتایجی را که با جزئیات مکان مشخص شده مطابقت ندارند، حذف می‌کند.اگر هر دو
typesوgranularityرا مشخص کنید، API فقط نتایجی را برمی‌گرداند که با هر دو مطابقت دارند. برای مثال:https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP
&granularity=GEOMETRIC_CENTER &key=API_KEY انواع
یک یا چند نوع آدرس، که به عنوان پارامترهای پرس و جوی جداگانه مشخص شده‌اند. اگر چندین پارامتر
typesرا مشخص کنید، API تمام آدرس‌هایی را که با هر یک از انواع مطابقت دارند، برمی‌گرداند.پارامتر
typesجستجو را به نوع(های) آدرس مشخص شده محدود نمی‌کند. در عوض،typesبه عنوان یک فیلتر پس از جستجو عمل می‌کند. API تمام نتایج را برای مکان مشخص شده دریافت می‌کند، سپس نتایجی را که با نوع(های) آدرس مشخص شده مطابقت ندارند، حذف می‌کند.اگر هر دو
typesوgranularityرا مشخص کنید، API فقط نتایجی را برمی‌گرداند که با هر دو مطابقت دارند. برای مثال:https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2
&types=locality &key=API_KEY مقادیر زیر پشتیبانی می‌شوند:
انواع آدرس و انواع مؤلفه آدرس
آرایه‌ی
typesدر بدنه‌یGeocodeResultدر پاسخ، نوع آدرس را نشان می‌دهد. نمونه‌هایی از انواع آدرس شامل آدرس خیابان، کشور یا یک نهاد سیاسی است. آرایه‌یtypesدر فیلدAddressComponentsاز بدنه‌یGeocodeResultنوع هر بخش از آدرس را نشان می‌دهد. مثال‌هایی از جمله شماره خیابان یا کشور.آدرس‌ها ممکن است انواع مختلفی داشته باشند. این انواع ممکن است به عنوان «برچسب» در نظر گرفته شوند. برای مثال، بسیاری از شهرها با انواع
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 در فرانسه) وجود ندارد.