ژئوکد یک آدرس، ژئوکد یک آدرس، ژئوکد یک آدرس، ژئوکد یک آدرس

ژئوکدینگ (Geocoding) یک آدرس را به مکانی روی نقشه تبدیل می‌کند. وقتی یک آدرس را ژئوکدینگ می‌کنید، پاسخ شامل موارد زیر است:

• شناسه مکان
• مختصات طول و عرض جغرافیایی محل مورد نظر
• کد پلاس محل
• جزئیات آدرس گسترش‌یافته

درخواست کد جغرافیایی

درخواست geocode یک درخواست HTTP GET است. می‌توانید آدرس را به صورت یک رشته بدون ساختار مشخص کنید:

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

یا به عنوان مجموعه‌ای ساختاریافته از اجزای آدرس که توسط پارامترهای پرس‌وجو نمایش داده می‌شوند:

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

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

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

ارسال یک رشته آدرس بدون ساختار

یک آدرس بدون ساختار، آدرسی است که به صورت رشته یا کد پلاس قالب‌بندی شده است. برای مثال، مثال زیر رشته آدرس کدگذاری شده URL "1600 Amphitheatre Parkway, Mountain View, CA" را ارسال می‌کند:

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

توجه داشته باشید که کاراکتر "+" در URL به یک فاصله تبدیل می‌شود.

همچنین می‌توانید با استفاده از دستور curl درخواست را انجام دهید:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

آدرس‌ها می‌توانند شامل انواع مختلفی از کاراکترهای خاص باشند. برای مثال، یک "/" مانند "7/1 King St, Concord West". URL "/" را به صورت %2F کدگذاری می‌کند:

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

مثال رایج دیگر کاراکتر "#" است، مانند "9500 W Bryn Mawr Ave #650, Rosemont". URL کاراکتر "#" را به صورت %2FE کدگذاری می‌کند:

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

در مثال بعدی، یک رشته آدرس بدون ساختار را به عنوان Plus Code 849VCWC8+R4 مشخص می‌کنید. مطمئن شوید که کاراکتر "+" را به صورت %2B در URL-encode می‌کنید:

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

یک آدرس ساختاریافته ارسال کنید

با استفاده از پارامتر پرس‌وجوی address ، از نوع PostalAddress یک آدرس ساختاریافته مشخص کنید. شیء PostalAddress به شما امکان می‌دهد برخی یا تمام اجزای آدرس را در درخواست به عنوان پارامترهای پرس‌وجوی مجزا مشخص کنید.

برای مثال، برای مشخص کردن فقط کد پستی آدرس، از PostalAddress.postalCode استفاده می‌کنید:

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

برای مشخص کردن چندین مؤلفه آدرس، مانند مؤلفه‌های آدرس ثبت شده در یک فرم HTML، از چندین پارامتر پرس و جو استفاده کنید:

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&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.address — فقط با GeocodeAddress برای ژئوکدینگ رو به جلو استفاده شود.

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

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

پاسخ ژئوکد

تابع Geocoding یک شیء GeocodeAddressResponse برمی‌گرداند که شامل آرایه results اشیاء GeocodeResult است. هر شیء GeocodeResult نشان‌دهنده یک مکان واحد است.

شیء کامل JSON به شکل زیر است:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "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"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

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

• address — آدرس خیابان یا پلاس کدی که می‌خواهید ژئوکد کنید. آدرس‌ها را مطابق با قالب مورد استفاده توسط سرویس پستی ملی کشور مربوطه مشخص کنید. از عناصر آدرس اضافی مانند نام کسب و کار و شماره واحد، سوئیت یا طبقه باید اجتناب شود. عناصر آدرس خیابان باید با فاصله‌هایی که URL آنها را با %20 کدگذاری کرده است، جدا شوند. به عنوان مثال، آدرس "24 Sussex Drive Ottawa ON" را به صورت زیر وارد کنید:

  24%20Sussex%20Drive%20Ottawa%20ON

  کدهای پلاس را مطابق شکل زیر قالب‌بندی کنید. علامت‌های پلاس در URL به %2B و فاصله‌ها در URL به %20 کدگذاری می‌شوند:
  • یک کد جهانی ، یک کد منطقه‌ای ۴ کاراکتری و یک کد محلی ۶ کاراکتری یا بیشتر است. برای مثال، "849VCWC8+R9" را به صورت 849VCWC8%2BR9 کدگذاری کنید.
  • یک کد ترکیبی، یک کد محلی ۶ کاراکتری یا بیشتر با موقعیت مکانی مشخص است. برای مثال، "CWC8+R9 Mountain View, CA, USA" را به صورت CWC8%2BR9%20Mountain%20View%20CA%20USA کدگذاری کنید.

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

• موقعیت مکانی

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

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

  یک منظره یاب یک منطقه بسته در نظر گرفته می‌شود، به این معنی که مرز خود را شامل می‌شود. محدوده عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه و محدوده طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشد:

  • اگر low = high ، نمای دید از آن نقطه واحد تشکیل شده است.
  • اگر low.longitude > high.longitude باشد، محدوده طول جغرافیایی معکوس می‌شود (صفحه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند).
  • اگر low.longitude = -180 درجه و high.longitude = 180 درجه باشد، صفحه نمایش شامل تمام طول‌های جغرافیایی می‌شود.
  • اگر low.longitude = 180 درجه و high.longitude = -180 درجه باشد، محدوده طول جغرافیایی خالی است.
  • اگر low.latitude > high.latitude باشد، محدوده عرض جغرافیایی خالی است.

  هر دو پارامتر low و high باید پر شوند و کادر نمایش داده شده نمی‌تواند خالی باشد. یک viewport خالی منجر به خطا می‌شود.

  برای مثال، این رشته پرس‌وجو، یک نمای دید (viewport) را تعریف می‌کند که شهر نیویورک را به طور کامل در بر می‌گیرد:

  ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

• زبانکد

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

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

• کد منطقه

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

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

سوگیری مکانی

از پارامتر locationBias برای تنظیم اولویت نتایج درون یک نمای مشخص (که به صورت یک کادر مرزی بیان می‌شود) به سرویس Geocoding استفاده کنید. پارامتر locationBias مختصات عرض/طول جغرافیایی گوشه‌های جنوب غربی و شمال شرقی این کادر مرزی را تعریف می‌کند.

برای مثال، یک درخواست کد جغرافیایی برای آدرس "واشنگتن" می‌تواند نتایجی برای واشنگتن دی سی و ایالت واشنگتن ایالات متحده را برگرداند:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

پاسخ به این شکل است:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

با این حال، اضافه کردن یک پارامتر locationBias که یک کادر مرزی در اطراف بخش شمال شرقی ایالات متحده تعریف می‌کند، منجر به این می‌شود که این geocode فقط شهر واشنگتن دی سی را برگرداند:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

بایاس منطقه

در یک درخواست geocoding، می‌توانید با استفاده از پارامتر regionCode به سرویس Geocoding دستور دهید تا نتایج بایاس شده به یک منطقه خاص را برگرداند. این پارامتر یک مقدار کد CLDR دو کاراکتری می‌گیرد که بایاس منطقه را مشخص می‌کند. اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند.

هیچ مقدار پیش‌فرضی برای regionCode وجود ندارد. برای مثال، یک geocode برای "Toledo" نتایج را برای ایالات متحده و اسپانیا برمی‌گرداند:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

پاسخ:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

یک درخواست مختصات جغرافیایی برای "تولدو" با regionCode=es (اسپانیا) فقط نتایج مربوط به اسپانیا را برمی‌گرداند:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY