درخواست و پاسخ زمین‌کدیابی معکوس (جستجوی نشانی)

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

اصطلاح زمین‌کدیابی معمولاً به ترجمه نشانی قابل‌خواندن برای انسان به مکانی روی نقشه اشاره دارد. فرایند انجام عکس این کار، یعنی ترجمه کردن مکان روی نقشه به نشانی قابل‌خواندن برای انسان، زمین‌کدیابی معکوس نامیده می‌شود.

درخواست‌های زمین‌کدیابی معکوس

پارامترهای الزامی

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

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

این‌ها پارامترهای اختیاری‌ای هستند که می‌توانید در درخواست زمین‌کدیابی معکوس اضافه کنید:

  • language — زبانی که نتایج به آن برگردانده می‌شود.
    • فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین این فهرست ممکن است کامل نباشد.
    • اگر language ارائه نشده باشد، زمین‌کدیاب تلاش می‌کند از زبان ترجیحی مشخص‌شده در سرصفحه Accept-Language یا زبان بومی دامنه‌ای که درخواست از آن ارسال شده است استفاده کند.
    • زمین‌کدیاب تمام تلاش خود را می‌کند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل‌خواندن باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند، درصورت لزوم به نویسه‌ای که برای کاربر قابل‌خواندن باشد نویسه‌گردانی می‌کند، و زبان ترجیحی را رعایت می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبان برگردانده می‌شوند، که از مؤلفه اول انتخاب شده است.
    • اگر نامی به زبان ترجیحی دردسترس نباشد، زمین‌کدیاب از نزدیک‌ترین مطابقت استفاده می‌کند.
  • region — کد منطقه، که به‌عنوان مقدار دو نویسه‌ای ccTLD («دامنه سطح بالا») مشخص شده است. این پارامتر همچنین می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.
  • result_type — فیلتری از یک یا چند نوع نشانی، که با خط عمودی (|) از هم جدا شده‌اند. اگر پارامتر حاوی چندین نوع نشانی باشد، API همه نشانی‌هایی را که با هریک از انواع مطابقت داشته باشد برمی‌گرداند. نکته‌ای درباره پردازش: پارامتر result_type جستجو را به نوع(های) نشانی مشخص‌شده محدود نمی‌کند. بلکه result_type به‌عنوان فیلتر پس‌از جستجو عمل می‌کند: میانای برنامه‌سازی کاربردی همه نتایج را برای 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 مرجع مکان کدگذاری‌شده، برگرفته از عرض جغرافیایی و طول جغرافیایی. در جاهایی که نشانی خیابان وجود ندارد (ساختمان‌ها شماره ندارند یا خیابان‌ها نام ندارند)، می‌توان از Plus Code به‌جای نشانی خیابان استفاده کرد. برای جزئیات، به https://plus.codes بروید.
    postal_code کد پستی که برای نشانی پستی در کشور استفاده می‌شود.
    natural_feature عارضه طبیعی برجسته.
    airport فرودگاه.
    park پارک نام‌گذاری‌شده.
    point_of_interest نقطه موردعلاقه نام‌گذاری‌شده. معمولاً این «نقاط موردعلاقه» نهادهای محلی برجسته‌ای هستند که به‌راحتی در دسته دیگری قرار نمی‌گیرند، مثل «ساختمان امپایر استیت» یا «برج ایفل».

    فهرست خالی از انواع نشان می‌دهد که هیچ نوع شناخته‌شده‌ای برای مؤلفه نشانی خاص وجود ندارد (برای مثال، Lieu-dit در فرانسه).

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

توجه داشته باشید که زمین‌کدیاب معکوس بیش‌از یک نتیجه برگردانده است. نتایج "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"
}

این میانای برنامه‌سازی کاربردی انواع مختلفی از نشانی‌ها را برمی‌گرداند، از نشانی خیابان که دقیق‌ترین است تا نهادهای سیاسی با دقت کمتر مثل محله‌ها، شهرها، شهرستان‌ها، و ایالت‌ها. نشانی دقیق‌تر معمولاً برجسته‌ترین نتیجه است، همان‌طور که در این مورد نیز چنین است. اگر می‌خواهید نوع خاصی از نشانی را مطابقت دهید، بخش زیر را درباره محدود کردن نتایج براساس نوع ببینید. به همین دلیل، مکان نتایج نسبت به یکدیگر می‌تواند متفاوت باشد.

زمین‌کدیابی معکوس فیلترشده براساس نوع

مثال زیر نشانی‌های برگردانده‌شده را فیلتر می‌کند تا فقط نشانی‌هایی را دربرگیرد که نوع مکان آن‌ها 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" در شیء پاسخ «زمین‌کدیابی» حاوی وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال‌زدایی باشد تا به شما کمک کند دلیل کار نکردن زمین‌کدیابی معکوس را ردیابی کنید. فیلد "status" ممکن است حاوی مقادیر زیر باشد:

  • "OK" نشان می‌دهد که خطایی رخ نداده است و حداقل یک نشانی برگردانده شده است.
  • "ZERO_RESULTS" نشان می‌دهد که زمین‌کدیابی معکوس موفقیت‌آمیز بوده است اما نتیجه‌ای برنگردانده است. این اتفاق ممکن است زمانی رخ دهد که latlng در مکانی دورافتاده به زمین‌کدیاب ارسال شده باشد.
  • "OVER_QUERY_LIMIT" نشان می‌دهد که از سهمیه‌تان فراتر رفته‌اید.
  • "REQUEST_DENIED" نشان می‌دهد که درخواست رد شده است. احتمالاً به این دلیل که درخواست شامل پارامتر result_type یا location_type است اما شامل کلید میانای برنامه‌سازی کاربردی نیست.
  • "INVALID_REQUEST" معمولاً یکی از موارد زیر را نشان می‌دهد:
    • پُرسمان (address، components، یا latlng) وجود ندارد.
    • result_type یا location_type نامعتبر ارائه شده است.
  • "UNKNOWN_ERROR" نشان می‌دهد که درخواست به‌دلیل خطای سرور پردازش نشده است. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.

کدهای باز زمین‌کدیابی معکوس

فیلد plus_code در پاسخ «زمین‌کدیابی» حاوی کد پلاس است که بهترین تقریب را برای طول و عرض جغرافیایی موردپرسش ارائه می‌دهد. علاوه‌براین، آرایه نتایج JSON در اکثر موارد حاوی نتیجه کامل «زمین‌کدیابی» با نوع plus_code و نشانی حاوی Plus Code است. تضمین می‌شود که فاصله بین plus code رمزگشایی‌شده و نقطه درخواست کمتر از ۱۰ متر باشد.