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

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

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

هنگامی که ژئوکد مکانی را معکوس می کنید، پاسخ شامل موارد زیر است:

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

درخواست ژئوکدینگ معکوس

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

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

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

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

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

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

یک رشته مکان بدون ساختار را پاس کنید

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

https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338"

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

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

https://geocode.googleapis.com/v4beta/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 از حوزه های زیر برای استفاده با 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 scope عمومی برای تمام نقاط پایانی Geocoding API استفاده کنید. این محدوده در طول توسعه مفید است، اما نه تولید، زیرا یک محدوده کلی است که اجازه دسترسی به تمام نقاط پایانی را می دهد.

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

پاسخ ژئوکدینگ معکوس

ژئوکدینگ معکوس یک شی GeocodeLocationResponse را برمی گرداند که حاوی:

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

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

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

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

پارامترهای مورد نیاز

  • مکان

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

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

  • کد زبان

    زبانی که در آن نتایج را برگرداند.

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

  • منطقه کد

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

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

  • دانه بندی

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

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

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

    https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    مقادیر زیر پشتیبانی می شوند:

    انواع آدرس و انواع اجزای آدرس

    آرایه types در بدنه GeocodeResult در پاسخ نشان دهنده نوع آدرس است. نمونه‌هایی از انواع آدرس‌ها عبارتند از آدرس خیابان، کشور یا یک نهاد سیاسی. آرایه types در قسمت AddressComponents بدنه GeocodeResult نوع هر قسمت از آدرس را نشان می دهد. به عنوان مثال می توان به شماره خیابان یا کشور اشاره کرد.

    آدرس ها ممکن است انواع مختلفی داشته باشند. انواع ممکن است "برچسب" در نظر گرفته شوند. به عنوان مثال، بسیاری از شهرها با انواع political و locality برچسب گذاری شده اند.

    انواع زیر در هر دو آرایه نوع آدرس و نوع جزء آدرس پشتیبانی و برگردانده می شوند:

    نوع آدرس توضیحات
    street_address آدرس خیابان دقیق
    route یک مسیر نامگذاری شده (مانند "US 101").
    intersection یک تقاطع اصلی، معمولاً از دو جاده اصلی.
    political یک نهاد سیاسی معمولاً این نوع نشان دهنده چند ضلعی برخی از مدیریت شهری است.
    country نهاد سیاسی ملی، و معمولاً بالاترین نوع است که توسط Geocoder بازگردانده می شود.
    administrative_area_level_1 یک نهاد مدنی درجه یک زیر سطح کشور. در داخل ایالات متحده، این سطوح اداری ایالت ها هستند. همه کشورها این سطوح اداری را نشان نمی دهند. در بیشتر موارد، نام‌های کوتاه administrative_area_level_1 با زیربخش‌های ISO 3166-2 و سایر فهرست‌های پرتیراژ بسیار مطابقت دارند. با این حال، این تضمین نمی شود، زیرا نتایج جغرافیایی ما بر اساس سیگنال های مختلف و داده های مکان است.
    administrative_area_level_2 یک نهاد مدنی درجه دوم زیر سطح کشور. در داخل ایالات متحده، این سطوح اداری شهرستان ها هستند. همه کشورها این سطوح اداری را نشان نمی دهند.
    administrative_area_level_3 یک نهاد مدنی درجه سوم زیر سطح کشور. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
    administrative_area_level_4 یک نهاد مدنی درجه چهارم زیر سطح کشور. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
    administrative_area_level_5 یک نهاد مدنی درجه پنجم زیر سطح کشور. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
    administrative_area_level_6 یک نهاد مدنی درجه شش زیر سطح کشور. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
    administrative_area_level_7 یک نهاد مدنی درجه هفتم زیر سطح کشور. این نوع نشان دهنده یک تقسیم مدنی جزئی است. همه کشورها این سطوح اداری را نشان نمی دهند.
    colloquial_area یک نام جایگزین رایج برای نهاد.
    locality یک نهاد سیاسی یک شهر یا شهرک.
    sublocality یک نهاد مدنی درجه یک در زیر یک منطقه. برای برخی مکان‌ها ممکن است یکی از انواع اضافی دریافت شود: sublocality_level_1 تا sublocality_level_5 . هر سطح فرعی یک نهاد مدنی است. اعداد بزرگتر نشان دهنده یک منطقه جغرافیایی کوچکتر است.
    neighborhood محله ای به نام
    premise یک مکان نامگذاری شده، معمولاً یک ساختمان یا مجموعه ای از ساختمان ها با نام مشترک.
    subpremise موجودی قابل آدرس دهی در زیر سطح محل، مانند آپارتمان، واحد یا سوئیت.
    plus_code مرجع مکان کدگذاری شده، برگرفته از طول و عرض جغرافیایی. کدهای پلاس می توانند به عنوان جایگزینی برای آدرس های خیابان ها در مکان هایی که وجود ندارند (جایی که ساختمان ها شماره گذاری نشده اند یا خیابان ها نامگذاری نشده اند) استفاده شود. برای جزئیات بیشتر به https://plus.codes مراجعه کنید.
    postal_code کد پستی که برای آدرس دهی نامه های پستی در داخل کشور استفاده می شود.
    natural_feature یک ویژگی طبیعی بارز.
    airport یک فرودگاه
    park پارکی به نام
    point_of_interest یک نقطه مورد علاقه با نام به طور معمول، این "POI" نهادهای محلی برجسته ای هستند که به راحتی در دسته بندی دیگری مانند "امپایر استیت بیلدینگ" یا "برج ایفل" قرار نمی گیرند.

    یک لیست خالی از انواع نشان می دهد که هیچ نوع شناخته شده ای برای جزء آدرس خاص وجود ندارد (به عنوان مثال، Lieu-dit در فرانسه).