زمین‌کدیابی مکان

زمین‌کدیابی مکان به شما امکان می‌دهد نشانی را از شناسه مکان بازیابی کنید.

«شناسه مکان» به‌طور منحصربه‌فرد مکانی را در پایگاه داده Google Places و در Google Maps شناسایی می‌کند. وقتی نشانی‌ای را زمین‌کدیابی می‌کنید، شناسه‌های مکان را بازیابی کنید. همچنین می‌توانید شناسه جا را از بسیاری از میاناهای برنامه‌سازی کاربردی دیگر بازیابی کنید، ازجمله جزئیات جا (جدید)، جستجوی نوشتار (جدید)، و جستجوی اطراف (جدید).

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

درخواست زمین‌کدیابی مکان یک درخواست HTTP GET به این شکل است:

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

که PLACE_ID حاوی شناسه جای مکان موردنظر است.

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

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?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/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

استفاده از 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.place — فقط با GeocodePlace برای زمین‌کدیابی مکان استفاده شود.

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

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

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

زمین‌کدیابی مکان یک شیء GeocodeResult برمی‌گرداند که نشان‌دهنده مکان متناظر با شناسه مکان است.

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

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

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

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "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"
  ]
}

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

• place — شناسه مکانی که می‌خواهید نشانی قابل‌خواندن برای انسان را برای آن دریافت کنید. شناسه مکان شناسه یکتایی است که می‌توان از آن با دیگر میاناهای برنامه‌سازی کاربردی Google استفاده کرد. برای مثال، می‌توانید از placeID برگردانده‌شده توسط Roads API برای دریافت نشانی نقطه چسبیده استفاده کنید. برای اطلاعات بیشتر درباره شناسه مکان، به شناسه مکان مراجعه کنید.

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

• languageCode

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

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

• regionCode

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

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

• FieldMask

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

  curl -X GET -H 'Content-Type: application/json' \
  -H 'X-Goog-FieldMask: formattedAddress' \
  -H "X-Goog-Api-Key: API_KEY" \
  "https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
  

  پاسخ:

  {
    "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
  }

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