این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

معکوس درخواست های geocoding

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

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

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

اینها پارامترهای اختیاری هستند که می توانید در یک درخواست معکوس جغرافیایی بگنجانید:

language - زبانی که نتایج را در آن برگرداند.
- لیست زبان های پشتیبانی شده را ببینید. Google اغلب زبان های پشتیبانی شده را به روز می کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر language ارائه نشده باشد، geocoder سعی می کند از زبان ترجیحی همانطور که در هدر Accept-Language یا زبان اصلی دامنه ای که درخواست از آن ارسال می شود، استفاده کند.
- geocoder تمام تلاش خود را می کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و به اسکریپتی که در صورت لزوم توسط کاربر قابل خواندن است، با رعایت زبان ترجیحی، ترجمه می‌شود. همه آدرس های دیگر به زبان ترجیحی برگردانده می شوند. اجزای آدرس همه به یک زبان بازگردانده می شوند که از جزء اول انتخاب شده است.
- اگر نامی در زبان ترجیحی موجود نباشد، geocoder از نزدیکترین تطابق استفاده می کند.
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`	نهاد سیاسی ملی، و معمولاً بالاترین نوع است که توسط 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" نهادهای محلی برجسته ای هستند که به راحتی در دسته بندی دیگری مانند "امپایر استیت بیلدینگ" یا "برج ایفل" قرار نمی گیرند.

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

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

توجه: هنگام عبور از پارامتر latlng ، اطمینان حاصل کنید که بین مقادیر طول و عرض جغرافیایی فاصله وجود ندارد.

کوئری بالا نتیجه زیر را برمی گرداند:

{
   "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 متر تضمین شده است.

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

معکوس درخواست های geocoding

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

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

انواع آدرس و انواع اجزای آدرس

نمونه ای از ژئوکدینگ معکوس

ژئوکدینگ معکوس بر اساس نوع فیلتر شده است

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

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

رمزگذاری جغرافیایی معکوس کدهای پلاس

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