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

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

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

وقتی مکانی را زمین‌کدیابی معکوس می‌کنید، پاسخ حاوی موارد زیر است:

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

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

درخواست زمین‌کدیابی معکوس یک درخواست HTTP GET است. می‌توانید مکان را به‌صورت رشته غیرساختاریافته مشخص کنید:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

یا به‌عنوان مجموعه‌ای ساختاریافته از مختصات طول و عرض جغرافیایی که با پارامترهای پُرسمان نشان داده می‌شود:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

معمولاً هنگام پردازش مؤلفه‌های مکان ضبط‌شده در فرم HTML، از قالب ساختاریافته استفاده می‌کنید.

همه پارامترهای دیگر را به‌عنوان پارامترهای نشانی وب یا، برای پارامترهایی مثل کلید میانای برنامه‌سازی کاربردی یا ماسک فیلد، در سرصفحه‌ها به‌عنوان بخشی از درخواست GET ارسال کنید. برای مثال:

رشته مکان ساختارنیافته را ارسال کنید

مکان بدون ساختار مکانی است که به‌صورت رشته‌ای از مختصات طول و عرض جغرافیایی جداشده با کاما قالب‌بندی شده است:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

یا در فرمان curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

ارسال مکان ساختاریافته

مکان ساختاریافته را بااستفاده از پارامتر پُرسمان location از نوع LatLng مشخص کنید. شیء LatLng به شما امکان می‌دهد عرض و طول جغرافیایی را به‌عنوان پارامترهای پُرسمان جداگانه مشخص کنید:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

استفاده از OAuth برای درخواست کردن

Geocoding API v4 از OAuth 2.0 برای اصالت‌سنجی پشتیبانی می‌کند. برای استفاده از OAuth با Geocoding API، باید دامنه صحیح به کد OAuth اختصاص داده شود. Geocoding API از دامنه‌های زیر برای استفاده با زمین‌کدیابی معکوس پشتیبانی می‌کند:

  • https://www.googleapis.com/auth/maps-platform.geocode — با همه روش‌های Geocoding API استفاده کنید.
  • https://www.googleapis.com/auth/maps-platform.geocode.location — فقط با GeocodeLocation برای زمین‌کدیابی معکوس استفاده شود.

همچنین، می‌توانید از گستره عمومی https://www.googleapis.com/auth/cloud-platform برای همه روش‌های Geocoding API استفاده کنید. این دامنه درطول توسعه مفید است، اما نه در تولید، زیرا دامنه‌ای عمومی است که اجازه دسترسی به همه روش‌ها را می‌دهد.

برای اطلاعات بیشتر و مثال‌ها، به استفاده از OAuth مراجعه کنید.

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

زمین‌کدیابی معکوس یک شیء GeocodeLocationResponse برمی‌گرداند که حاوی موارد زیر است:

  • آرایه results از اشیای GeocodeResult که نشان‌دهنده مکان است.

    پاسخ‌های Geocoding API شامل آرایه‌های types در دو مکان اصلی در GeocodeResult است:

    1. GeocodeResult.types: این آرایه نوع(انواع) کلی نتیجه را نشان می‌دهد. مقادیر ممکن از انواع «مکان» استفاده‌شده توسط Places API گرفته می‌شود. برای اطلاعات بیشتر، به جدول‌های الف و ب انواع مکان مراجعه کنید.
    2. GeocodeResult.addressComponents[].types: هر مؤلفه نشانی دارای یک آرایه types است که نوع آن بخش خاص از نشانی را نشان می‌دهد. این مقادیر از جدول انواع نشانی و مؤلفه نشانی که توسط Places API استفاده می‌شود گرفته شده است.

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

  • فیلد plusCode، از نوع PlusCode، حاوی Plus Code است که بهترین تقریب را برای طول و عرض جغرافیایی در درخواست ارائه می‌دهد. علاوه‌براین، هر عنصر آرایه results حاوی یک Plus Code است. فاصله بین Plus Code رمزگشایی‌شده و نقطه درخواست کمتر از ۱۰ متر است.

    توجه: میانای برنامه‌سازی کاربردی همیشه Plus Codes را برنمی‌گرداند.

شیء JSON کامل در فرم است:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

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

  • مکان

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

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

  • languageCode

    زبانی که نتایج به آن برگردانده می‌شود.

    • فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین ممکن است این فهرست کامل نباشد.
    • اگر languageCode ارائه نشده باشد، API به‌طور پیش‌فرض از زبان محلی و نویسه‌های مکان استفاده می‌کند. اگر کد زبان نامعتبری را مشخص کنید، میانای برنامه‌سازی کاربردی خطای INVALID_ARGUMENT را برمی‌گرداند.
    • این API تمام تلاش خود را می‌کند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل‌خواندن باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، با رعایت زبان ترجیحی، آن‌ها را به نویسه‌ای که برای کاربر خوانا باشد نویسه‌گردانی می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبانی برگردانده می‌شوند که از مؤلفه اول انتخاب شده است.
    • اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
    • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که در آن برگردانده می‌شوند. زمین‌کدیاب اختصارات را بسته به زبان به‌طور متفاوتی تفسیر می‌کند، مانند اختصارات برای انواع خیابان‌ها، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.

  • regionCode

    کد منطقه به‌عنوان مقدار کد CLDR دو نویسه‌ای. مقدار پیش‌فرضی وجود ندارد. بیشتر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند.

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

  • جزئیات

    یک یا چند دانه موقعیت مکانی، که به‌عنوان پارامترهای پرسمان جداگانه مشخص شده‌اند، همان‌طور که توسط Granularity تعریف شده است. اگر چند پارامتر granularity را مشخص کنید، API همه نشانی‌هایی را که با هریک از دانه‌بندی‌ها مطابقت دارد برمی‌گرداند.

    پارامتر granularity جستجو را به جزئیات مکان مشخص‌شده محدود نمی‌کند. بلکه granularity به‌عنوان فیلتر پس‌از جستجو عمل می‌کند. ‫API همه نتایج را برای location مشخص‌شده واکشی می‌کند، سپس نتایجی را که با دانه‌بندی‌های مکان مشخص‌شده مطابقت ندارند حذف می‌کند.

    اگر هم types و هم granularity را مشخص کنید، میانای برنامه‌سازی کاربردی فقط نتایجی را برمی‌گرداند که با هر دو مطابقت داشته باشد. برای مثال:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • انواع

    یک یا چند نوع نشانی که به‌عنوان پارامترهای پرسمان جداگانه مشخص شده‌اند. مقادیر ممکن از جدول انواع نشانی و انواع مؤلفه نشانی در صفحه «انواع مکان (جدید)» گرفته می‌شود. اگر چند پارامتر types را مشخص کنید، API همه نشانی‌هایی را که با هریک از انواع مطابقت داشته باشد برمی‌گرداند.

    پارامتر types جستجو را به نوع(های) نشانی مشخص‌شده محدود نمی‌کند. بلکه types به‌عنوان فیلتر پس‌از جستجو عمل می‌کند. ‫API همه نتایج را برای مکان مشخص‌شده واکشی می‌کند، سپس نتایجی را که با نوع(های) نشانی مشخص‌شده مطابقت ندارند کنار می‌گذارد.

    اگر هم types و هم granularity را مشخص کنید، میانای برنامه‌سازی کاربردی فقط نتایجی را برمی‌گرداند که با هر دو مطابقت داشته باشد. برای مثال:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    ماسک فیلد پاسخ ایجاد کنید تا فیلدهایی را که باید در پاسخ برگردانده شوند مشخص کنید. ماسک فیلد پاسخ را بااستفاده از پارامتر نشانی وب $fields یا fields، یا بااستفاده از سرایند HTTP X-Goog-FieldMask به روش ارسال کنید. برای مثال، درخواست زیر فقط فیلدهای placeID پاسخ را برمی‌گرداند.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    پاسخ: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    برای جزئیات بیشتر، انتخاب فیلدها برای برگرداندن را ببینید.