روش‌های Geocoding API نسخه ۴ سهمیه پیش‌فرض ۲۵ پرس‌وجو در ثانیه (QPS) دارند. برای اطلاعات بیشتر در مورد درخواست سهمیه بالاتر، به بخش «مشاهده و مدیریت سهمیه‌ها» مراجعه کنید و Geocoding API را به عنوان سرویس انتخاب کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

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

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

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

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

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

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

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

نوع پرس و جو	مثال
مختصات طول و عرض جغرافیایی. به جای آن از کدگذاری جغرافیایی معکوس استفاده کنید.	«۳۷.۴۲۲۱۳۱، -۱۲۲.۰۸۴۸۰۱»
مفاهیم یا محدودیت‌های بسیار زیاد، مانند نام چندین مکان، جاده یا شهر در یک پرس‌وجو	«خیابان مارکت، سانفرانسیسکو، فرودگاه سن خوزه»
عناصر آدرس پستی که در نقشه‌های گوگل نمایش داده نمی‌شوند	«دفتر مرکزی جان اسمیت، خیابان اصلی ۱۲۳» «صندوق پستی ۱۳ سانفرانسیسکو»
نام کسب‌وکارها، زنجیره‌ها یا دسته‌بندی‌ها به همراه مکان‌هایی که این نهادها در آنها در دسترس نیستند	«تسکو نزدیک دالاس، تگزاس»
پرسش‌های مبهم با تفاسیر متعدد	"تحویل شارژر"
نام‌های تاریخی دیگر استفاده نمی‌شوند	«میدلسکس، بریتانیا»
عناصر یا مقاصد غیرمکان‌محور	«چند قایق در بندر ونتورا وجود دارد؟»
نام‌های غیررسمی یا خیالی	"جنگا" "هلتر اسکلتر"

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

https://geocode.googleapis.com/v4/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/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

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

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

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

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

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

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

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

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

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

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

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

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

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

پاسخ ژئوکد

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

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

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

شیء کامل 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 — آدرس خیابان یا Plus Code که می‌خواهید ژئوکد کنید. توجه: ژئوکد آدرس، مختصات طول و عرض جغرافیایی یا سایر رشته‌های بدون ساختار که نشان‌دهنده آدرس یا Plus Code نیستند را حل نمی‌کند. برای جزئیات بیشتر و نمونه‌هایی از پرس‌وجوهای پشتیبانی نشده، به Pass an unstructured address string مراجعه کنید. آدرس‌ها را مطابق با قالبی که توسط سرویس پستی ملی کشور مربوطه استفاده می‌شود، مشخص کنید. از عناصر آدرس اضافی مانند نام کسب و کار و شماره واحد، سوئیت یا طبقه باید اجتناب شود. عناصر آدرس خیابان باید با فاصله‌هایی که 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 مشخص می‌کند. این مکان به عنوان یک بایاس عمل می‌کند، به این معنی که نتایج اطراف مکان مشخص شده، از جمله نتایج نزدیک اما خارج از ناحیه، می‌توانند بازگردانده شوند.
نکته: اگر آدرس درخواستی شامل یک مکان صریح مانند Barcelona, Spain باشد، می‌توان پارامتر locationBias را نادیده گرفت. در این حالت، locationBias نادیده گرفته می‌شود.
منطقه را به عنوان یک نمای مستطیلی مشخص کنید. مستطیل، یک نمای طول و عرض جغرافیایی است که به صورت دو نقطه پایین و بالا که به صورت مورب روبروی هم قرار دارند، نمایش داده می‌شود. نقطه پایین، گوشه جنوب غربی مستطیل و نقطه بالا، گوشه شمال شرقی مستطیل را نشان می‌دهد.
یک منظره یاب یک منطقه بسته در نظر گرفته می‌شود، به این معنی که مرز خود را شامل می‌شود. محدوده عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه و محدوده طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشد:
- اگر 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 هستند.
هنگام جغرافیایی کردن یک آدرس، جغرافیایی کردن رو به جلو ، این پارامتر می‌تواند بر نتایج سرویس به منطقه مشخص شده تأثیر بگذارد، اما نمی‌تواند آن را به طور کامل محدود کند. هنگام جغرافیایی کردن یک مکان یا یک مکان، جغرافیایی کردن معکوس یا جغرافیایی کردن مکان ، این پارامتر می‌تواند برای قالب‌بندی آدرس استفاده شود. در همه موارد، این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.
فیلد ماسک
یک ماسک فیلد پاسخ ایجاد کنید تا فیلدهایی که باید در پاسخ برگردانده شوند را مشخص کنید. ماسک فیلد پاسخ را با استفاده از پارامتر 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/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
```
پاسخ این است:
```
{
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}
```
برای جزئیات بیشتر به «انتخاب فیلدها برای بازگشت» مراجعه کنید.
مهم: پوشش فیلد یک روش طراحی خوب برای اطمینان از عدم درخواست داده‌های غیرضروری است که به جلوگیری از زمان پردازش غیرضروری کمک می‌کند.

سوگیری مکانی

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

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

https://geocode.googleapis.com/v4/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/v4/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/v4/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/v4/geocode/address/Toledo?regionCode=es&key=API_KEY