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

توسعه‌دهندگان منطقه اقتصادی اروپا (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، از قالب ساختاریافته استفاده می‌کنید.

همه پارامترهای دیگر را به‌عنوان پارامترهای نشانی وب یا، برای پارامترهایی مثل کلید API یا پوشش فیلد، در سرایندها به‌عنوان بخشی از درخواست 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 نسخه ۴ از OAuth 2.0 برای اصالت‌سنجی پشتیبانی می‌کند. برای استفاده از OAuth با Geocoding API، باید محدوده صحیح به کد OAuth اختصاص داده شود. ‫Geocoding API از دامنه‌های زیر برای استفاده با geocoding معکوس پشتیبانی می‌کند:

  • 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 گرفته می‌شود. برای اطلاعات بیشتر، جدول‌های A و B انواع مکان را ببینید.
    2. GeocodeResult.addressComponents[].types: هر مؤلفه نشانی دارای یک آرایه types است که نوع آن بخش خاص از نشانی را نشان می‌دهد. این مقادیر از جدول انواع نشانی و انواع مؤلفه نشانی که توسط Places API استفاده می‌شود گرفته شده‌اند.

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

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

    توجه: «میانای برنامه‌سازی کاربردی» همیشه «کدهای پلاس» را برنمی‌گرداند.

شیء 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 به‌طور پیش‌فرض از زبان محلی و نویسه‌های مکان استفاده می‌کند. اگر کد زبان نامعتبری را مشخص کنید، API خطای INVALID_ARGUMENT را برمی‌گرداند.
    • این API تلاش می‌کند نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی خوانا باشد. برای رسیدن به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، با رعایت زبان ترجیحی کاربر، آن را به خطی که کاربر بتواند بخواند آوانویسی می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبانی برگردانده می‌شوند که از مؤلفه اول انتخاب شده است.
    • اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
    • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که در آن برگردانده می‌شوند. کدبند براساس زبان، مخفف‌ها را به‌شکل متفاوتی تفسیر می‌کند، برای مثال، مخفف‌های انواع خیابان، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.

  • regionCode

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

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

  • دانه‌بندی

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

    پارامتر 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"
    },
    ...
  ]
}

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