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

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

اصطلاح ژئوکدینگ (geocoding) عموماً به ترجمه یک آدرس قابل خواندن توسط انسان به مکانی روی نقشه اشاره دارد. فرآیند انجام عکس این عمل، یعنی ترجمه یک مکان روی نقشه به آدرسی قابل خواندن توسط انسان، به عنوان ژئوکدینگ معکوس شناخته می‌شود.

درخواست‌های معکوس جغرافیایی

پارامترهای مورد نیاز

  • latlng — مختصات طول و عرض جغرافیایی که مکانی را که می‌خواهید نزدیکترین آدرس قابل خواندن توسط انسان را داشته باشید، مشخص می‌کند.
  • key — کلید API برنامه شما. این کلید، برنامه شما را برای اهداف مدیریت سهمیه شناسایی می‌کند. یاد بگیرید که چگونه یک کلید دریافت کنید .

پارامترهای اختیاری

اینها پارامترهای اختیاری هستند که می‌توانید در یک درخواست ژئوکدینگ معکوس وارد کنید:

  • language — زبانی که نتایج با آن برگردانده می‌شوند.
    • فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
    • اگر language ارائه نشود، geocoder تلاش می‌کند از زبان ترجیحی مشخص شده در سربرگ Accept-Language یا زبان مادری دامنه‌ای که درخواست از آن ارسال می‌شود، استفاده کند.
    • جئوکودر تمام تلاش خود را می‌کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به خطی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
    • اگر نامی به زبان ترجیحی موجود نباشد، ژئوکودر از نزدیکترین مورد منطبق استفاده می‌کند.
  • region — کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. این پارامتر همچنین می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.
  • result_type — فیلتری از یک یا چند نوع آدرس که با یک خط عمودی ( | ) از هم جدا شده‌اند. اگر پارامتر شامل چندین نوع آدرس باشد، API تمام آدرس‌هایی را که با هر یک از انواع مطابقت دارند، برمی‌گرداند. نکته‌ای در مورد پردازش: پارامتر result_type جستجو را به نوع(های) آدرس مشخص شده محدود نمی‌کند. در عوض، result_type به عنوان یک فیلتر پس از جستجو عمل می‌کند: API تمام نتایج را برای نوع(های) latlng مشخص شده دریافت می‌کند، سپس نتایجی را که با نوع(های) آدرس مشخص شده مطابقت ندارند، حذف می‌کند. مقادیر زیر پشتیبانی می‌شوند:

    انواع آدرس و انواع مؤلفه آدرس

    آرایه‌ی 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 در فرانسه) وجود ندارد.

  • location_type — فیلتری از یک یا چند نوع مکان که با یک خط عمودی ( | ) از هم جدا شده‌اند. اگر پارامتر شامل چندین نوع مکان باشد، API تمام آدرس‌هایی را که با هر یک از این نوع‌ها مطابقت دارند، برمی‌گرداند. نکته‌ای در مورد پردازش: پارامتر location_type جستجو را به انواع مکان مشخص شده محدود نمی‌کند. در عوض، location_type به عنوان یک فیلتر پس از جستجو عمل می‌کند: API تمام نتایج را برای latlng مشخص شده دریافت می‌کند، سپس نتایجی را که با انواع مکان مشخص شده مطابقت ندارند، حذف می‌کند. مقادیر زیر پشتیبانی می‌شوند:
    • "ROOFTOP" فقط آدرس‌هایی را برمی‌گرداند که گوگل اطلاعات مکانی دقیقی از آنها، حتی با دقت آدرس خیابان، دارد.
    • "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> ...

توجه داشته باشید که کد جغرافیایی معکوس بیش از یک نتیجه را برگردانده است. نتایج "formatted_address" فقط آدرس‌های پستی نیستند، بلکه هر روشی برای نامگذاری جغرافیایی یک مکان هستند. برای مثال، هنگام کد جغرافیایی یک نقطه در شهر شیکاگو، نقطه کد جغرافیایی شده ممکن است به عنوان آدرس خیابان، به عنوان شهر (شیکاگو)، به عنوان ایالت آن (ایلینوی) یا به عنوان یک کشور (ایالات متحده) مشخص شود. همه اینها برای کد جغرافیایی "آدرس" هستند. کد جغرافیایی معکوس هر یک از این نوع‌ها را به عنوان نتایج معتبر برمی‌گرداند.

ژئوکودر معکوس، موجودیت‌های سیاسی (کشورها، استان‌ها، شهرها و محله‌ها)، آدرس‌های خیابان‌ها و کدهای پستی را با هم تطبیق می‌دهد.

لیست کامل مقادیر 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 باشد.

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