اصطلاح geocoding به طور کلی به ترجمه یک آدرس قابل خواندن توسط انسان به یک مکان روی نقشه اشاره دارد. فرآیند انجام برعکس، ترجمه یک مکان روی نقشه به یک آدرس قابل خواندن توسط انسان، به عنوان معکوس جغرافیایی شناخته می شود.
معکوس درخواست های geocoding
پارامترهای مورد نیاز
-
latlng
- مختصات طول و عرض جغرافیایی که مکانی را مشخص می کند که شما می خواهید نزدیک ترین آدرس و قابل خواندن برای انسان را برای آن داشته باشید. -
key
- کلید API برنامه شما. این کلید درخواست شما را برای اهداف مدیریت سهمیه شناسایی می کند. نحوه گرفتن کلید را بیاموزید.
پارامترهای اختیاری
اینها پارامترهای اختیاری هستند که می توانید در یک درخواست معکوس جغرافیایی بگنجانید:
-
language
- زبانی که نتایج را در آن برگرداند.- لیست زبان های پشتیبانی شده را ببینید. Google اغلب زبان های پشتیبانی شده را به روز می کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر
language
ارائه نشده باشد، geocoder سعی می کند از زبان ترجیحی همانطور که در هدرAccept-Language
یا زبان اصلی دامنه ای که درخواست از آن ارسال می شود، استفاده کند. - geocoder تمام تلاش خود را می کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرسهای خیابان را به زبان محلی برمیگرداند و به اسکریپتی که در صورت لزوم توسط کاربر قابل خواندن است، با رعایت زبان ترجیحی، ترجمه میشود. همه آدرس های دیگر به زبان ترجیحی برگردانده می شوند. اجزای آدرس همه به یک زبان بازگردانده می شوند که از جزء اول انتخاب شده است.
- اگر نامی در زبان ترجیحی موجود نباشد، geocoder از نزدیکترین تطابق استفاده می کند.
-
region
- کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. این پارامتر همچنین می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد. -
result_type
- فیلتری از یک یا چند نوع آدرس که با یک لوله (|
) از هم جدا شده اند. اگر پارامتر شامل چندین نوع آدرس باشد، API همه آدرسهایی را که با هر یک از انواع مطابقت دارند برمیگرداند. نکته ای در مورد پردازش: پارامترresult_type
جستجو را به نوع(های) آدرس مشخص شده محدود نمی کند. در عوض،result_type
بهعنوان یک فیلتر پس از جستجو عمل میکند: API همه نتایج را برایlatlng
مشخص شده واکشی میکند، سپس نتایجی را که با نوع(های) آدرس مشخص شده مطابقت ندارند، کنار میگذارد. مقادیر زیر پشتیبانی میشوند:-
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" نهادهای محلی برجسته ای هستند که به راحتی در دسته بندی دیگری مانند "امپایر استیت بیلدینگ" یا "برج ایفل" قرار نمی گیرند.
-
-
location_type
- فیلتری از یک یا چند نوع مکان که توسط یک لوله جدا شده است (|
). اگر پارامتر دارای چندین نوع مکان باشد، API همه آدرسهایی را که با هر یک از انواع مطابقت دارند برمیگرداند. نکته ای در مورد پردازش: پارامترlocation_type
جستجو را به انواع مکان های مشخص شده محدود نمی کند. در عوض،location_type
بهعنوان یک فیلتر پس از جستجو عمل میکند: API همه نتایج را برایlatlng
مشخص شده واکشی میکند، سپس آن دسته از نتایجی را که با انواع مکانهای مشخص شده مطابقت ندارند، کنار میگذارد. مقادیر زیر پشتیبانی می شوند:-
"ROOFTOP"
فقط آدرسهایی را برمیگرداند که Google اطلاعات مکان را تا حد دقیق آدرس خیابان دارد. -
"RANGE_INTERPOLATED"
فقط آدرس هایی را برمی گرداند که یک تقریب (معمولاً در یک جاده) بین دو نقطه دقیق (مانند تقاطع ها) را منعکس می کنند. یک محدوده درون یابی به طور کلی نشان می دهد که ژئوکدهای پشت بام برای یک آدرس خیابان در دسترس نیستند. -
"GEOMETRIC_CENTER"
فقط مراکز هندسی یک مکان مانند چند خط (به عنوان مثال، یک خیابان) یا چند ضلعی (منطقه) را برمی گرداند. -
"APPROXIMATE"
فقط آدرس هایی را برمی گرداند که به عنوان تقریبی مشخص می شوند.
-
-
extra_computations
- از این پارامتر برای مشخص کردن ویژگی های اضافی زیر در پاسخ استفاده کنید:-
ADDRESS_DESCRIPTORS
- برای جزئیات بیشتر به توصیفگرهای آدرس مراجعه کنید. -
BUILDING_AND_ENTRANCES
— برای جزئیات بیشتر ورودی ها و خطوط کلی ساختمان را ببینید.
extra_computations
را در درخواست هر ویژگی بگنجانید، برای مثال:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
-
اگر هر دو فیلتر result_type
و location_type
وجود داشته باشند، API فقط نتایجی را برمیگرداند که هم با مقدار result_type
و هم location_type
مطابقت دارند. اگر هیچ یک از مقادیر فیلتر قابل قبول نباشد، API ZERO_RESULTS
برمی گرداند.
نمونه ای از ژئوکدینگ معکوس
جستار زیر حاوی مقدار طول و عرض جغرافیایی برای مکانی در بروکلین است:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY
کوئری بالا نتیجه زیر را برمی گرداند:
{
"results" : [
{
"address_components" : [
{
"long_name" : "277",
"short_name" : "277",
"types" : [ "street_number" ]
},
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
"types" : [ "route" ]
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
"types" : [ "neighborhood", "political" ]
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "sublocality", "political" ]
},
{
"long_name" : "Kings",
"short_name" : "Kings",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "New York",
"short_name" : "NY",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "11211",
"short_name" : "11211",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.714232,
"lng" : -73.9612889
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 40.7155809802915,
"lng" : -73.9599399197085
},
"southwest" : {
"lat" : 40.7128830197085,
"lng" : -73.96263788029151
}
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
"types" : [ "street_address" ]
},
... Additional <code>results[]</code> ...
توجه داشته باشید که geocoder معکوس بیش از یک نتیجه را برگرداند. نتایج "formatted_address"
فقط آدرسهای پستی نیستند، بلکه هر روشی برای نامگذاری جغرافیایی یک مکان هستند. به عنوان مثال، هنگام کدگذاری جغرافیایی یک نقطه در شهر شیکاگو، نقطه جغرافیایی ممکن است به عنوان آدرس خیابان، به عنوان شهر (شیکاگو)، به عنوان ایالت آن (ایلینویز) یا به عنوان یک کشور (ایالات متحده) مشخص شود. همه "آدرس" به geocoder هستند. ژئوکدر معکوس هر یک از این انواع را به عنوان نتایج معتبر برمی گرداند.
ژئوکدر معکوس با نهادهای سیاسی (کشورها، استان ها، شهرها و محله ها)، آدرس خیابان ها و کدهای پستی مطابقت دارد.
لیست کامل مقادیر formatted_address
بازگردانده شده توسط پرس و جو قبلی در زیر نشان داده شده است.
{
"plus_code" : {
"compound_code" : "P27Q+MCM New York, NY, USA",
"global_code" : "87G8P27Q+MCM"
},
"results" : [
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "street_address" ]
},
{
"formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "premise" ]
},
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "establishment", "point_of_interest" ]
},
{
"formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "route" ]
},
{
"formatted_address" : "P27Q+MC New York, NY, USA",
...
"types" : [ "plus_code" ]
},
{
"formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Brooklyn, NY 11211, USA",
...
"types" : [ "postal_code" ]
},
{
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Kings County, Brooklyn, NY, USA",
...
"types" : [ "administrative_area_level_2", "political" ]
},
{
"formatted_address" : "Brooklyn, NY, USA",
...
"types" : [ "political", "sublocality", "sublocality_level_1" ]
},
{
"formatted_address" : "New York, NY, USA",
...
"types" : [ "locality", "political" ]
},
{
"formatted_address" : "New York, USA",
...
"types" : [ "administrative_area_level_1", "political" ]
},
{
"formatted_address" : "United States",
...
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
این API انواع مختلفی از آدرسها را برمیگرداند، از مشخصترین آدرس خیابان گرفته تا نهادهای سیاسی کمتر خاص مانند محلهها، شهرها، شهرستانها و ایالتها. آدرس دقیقتر عموماً برجستهترین نتیجه است، همانطور که در این مورد نیز وجود دارد. اگر میخواهید نوع خاصی از آدرس را مطابقت دهید، بخش زیر را در مورد محدود کردن نتایج بر اساس نوع ببینید. به همین دلیل، مکان نتایج نسبت به یکدیگر می تواند متفاوت باشد.
ژئوکدینگ معکوس بر اساس نوع فیلتر شده است
مثال زیر آدرسهای برگشتی را فیلتر میکند تا فقط آدرسهایی را که نوع مکان ROOFTOP
و نوع آدرس street_address
address دارند را شامل شود.
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY
توجه: این فیلترها فقط برای ژئوکدینگ معکوس معتبر هستند.
پاسخهای ژئوکدینگ معکوس
فرمت پاسخ ژئوکدینگ معکوس مانند پاسخ ژئوکدینگ است. پاسخ های کدگذاری جغرافیایی را ببینید. در زیر کدهای وضعیت ممکن در پاسخ کدگذاری جغرافیایی معکوس وجود دارد.
کدهای وضعیت جغرافیایی معکوس
فیلد "status"
در شیء پاسخ Geocoding حاوی وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال زدایی باشد تا به شما در ردیابی چرایی عدم کارکرد رمزگذاری معکوس جغرافیایی کمک کند. فیلد "status"
ممکن است حاوی مقادیر زیر باشد:
-
"OK"
نشان می دهد که هیچ خطایی رخ نداده و حداقل یک آدرس برگردانده شده است. -
"ZERO_RESULTS"
نشان می دهد که رمزگذاری جغرافیایی معکوس موفقیت آمیز بود اما هیچ نتیجه ای نداشت. این ممکن است در صورتی اتفاق بیفتد که ژئوکددر یکlatlng
در یک مکان از راه دور عبور داده شود. -
"OVER_QUERY_LIMIT"
نشان می دهد که شما بیش از سهمیه خود هستید. -
"REQUEST_DENIED"
نشان می دهد که درخواست رد شده است. احتمالاً به این دلیل که درخواست شامل پارامترresult_type
یاlocation_type
است اما شامل کلید API نیست. -
"INVALID_REQUEST"
به طور کلی یکی از موارد زیر را نشان می دهد:- پرس و جو (
address
،components
یاlatlng
) وجود ندارد. - یک
result_type
یاlocation_type
نامعتبر داده شده است.
- پرس و جو (
-
"UNKNOWN_ERROR"
نشان می دهد که درخواست به دلیل یک خطای سرور قابل پردازش نیست. اگر دوباره تلاش کنید ممکن است درخواست با موفقیت انجام شود.
رمزگذاری جغرافیایی معکوس کدهای پلاس
فیلد plus_code
در پاسخ Geocoding حاوی یک کد مثبت است که به بهترین وجه طول و عرض جغرافیایی مورد نظر را تقریب میکند. علاوه بر این، آرایه نتایج JSON در بیشتر موارد حاوی یک نتیجه Geocoding کامل با نوع plus_code
و یک آدرس حاوی یک کد مثبت است. فاصله بین کد پلاس رمزگشایی شده و نقطه درخواست زیر 10 متر تضمین شده است.