درخواست و پاسخ ژئوکدینگ معکوس (جستجوی آدرس).

اصطلاح 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 - از این پارامتر برای مشخص کردن ویژگی های اضافی زیر در پاسخ استفاده کنید: برای فعال کردن چندین مورد از این ویژگی‌ها برای یک درخواست API، پارامتر 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 متر تضمین شده است.