معکوس ژئوکد یک مکان

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

سایر پارامترها را به عنوان پارامترهای URL یا برای پارامترهایی مانند کلید 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 برای ارسال درخواست

API ژئوکدینگ نسخه ۴ از OAuth 2.0 برای احراز هویت پشتیبانی می‌کند. برای استفاده از OAuth با API ژئوکدینگ، باید به توکن OAuth دامنه صحیح اختصاص داده شود. API ژئوکدینگ از دامنه‌های زیر برای استفاده با ژئوکدینگ معکوس پشتیبانی می‌کند:

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

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

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

پاسخ جغرافیایی معکوس

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

  • آرایه results اشیاء GeocodeResult که مکان را نشان می‌دهد.

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

    1. GeocodeResult.types : این آرایه نوع(های) کلی نتیجه را نشان می‌دهد. مقادیر ممکن از جدول A و جدول B در صفحه Place Types (جدید) استخراج شده‌اند.
    2. GeocodeResult.addressComponents[].types : هر جزء آدرس دارای یک آرایه types است که نوع آن بخش خاص از آدرس را نشان می‌دهد. این مقادیر از جدول انواع آدرس و انواع جزء آدرس در صفحه Place Types (جدید) استخراج می‌شوند.

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

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

    نکته: API همیشه کدهای پلاس را برنمی‌گرداند.

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

  • کد منطقه

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

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

  • دانه‌بندی

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

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

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

    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 را مشخص کنید، API فقط نتایجی را برمی‌گرداند که با هر دو مطابقت دارند. برای مثال:

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

  • فیلد ماسک

    یک ماسک فیلد پاسخ ایجاد کنید تا فیلدهایی که باید در پاسخ برگردانده شوند را مشخص کنید. ماسک فیلد پاسخ را با استفاده از پارامتر URL $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"
    },
    ...
  ]
}

    برای جزئیات بیشتر به «انتخاب فیلدها برای بازگشت» مراجعه کنید.