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

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

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

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

شیء کامل 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"
}

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