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

درخواست

یک درخواست API مربوط به Geocoding به شکل زیر است:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

که در آن outputFormat می‌تواند یکی از مقادیر زیر باشد:

• json (توصیه می‌شود) خروجی را در قالب نشانه‌گذاری شیء جاوااسکریپت (JSON) نشان می‌دهد؛ یا
• xml خروجی را در XML نشان می‌دهد.

HTTPS الزامی است.

برخی از پارامترها الزامی و برخی اختیاری هستند. همانطور که در URLها استاندارد است، پارامترها با استفاده از کاراکتر & از هم جدا می‌شوند.

ادامه‌ی این صفحه، ژئوکدینگ و ژئوکدینگ معکوس را جداگانه توضیح می‌دهد، زیرا پارامترهای متفاوتی برای هر نوع درخواست در دسترس است.

پارامترهای جغرافیایی (جستجوی طول و عرض جغرافیایی)

پارامترهای مورد نیاز در یک درخواست geocoding:

• key — کلید API برنامه شما. این کلید، برنامه شما را برای اهداف مدیریت سهمیه شناسایی می‌کند. یاد بگیرید که چگونه یک کلید دریافت کنید .

• شما باید address یا components یا هر دو را در یک درخواست مشخص کنید:

  • address — آدرس خیابان یا کد پلاس که می‌خواهید ژئوکد کنید. آدرس‌ها را مطابق با قالب مورد استفاده توسط سرویس پستی ملی کشور مربوطه مشخص کنید. از عناصر آدرس اضافی مانند نام کسب و کار و شماره واحد، سوئیت یا طبقه باید اجتناب شود. عناصر آدرس خیابان باید با فاصله (که در اینجا به صورت url-escaped to %20 نشان داده شده است) از هم جدا شوند:

    address=24%20Sussex%20Drive%20Ottawa%20ON

    کدهای بعلاوه را مانند اینجا قالب‌بندی کنید (علامت‌های بعلاوه به صورت %2B و فاصله‌ها به صورت %20 با url-escaped نمایش داده می‌شوند):
    • کد جهانی یک کد منطقه‌ای ۴ کاراکتری و کد محلی ۶ کاراکتری یا بیشتر است (۸۴۹VCWC8+R9 849VCWC8%2BR9 است).
    • کد مرکب، یک کد محلی ۶ کاراکتری یا بیشتر با موقعیت مکانی مشخص است (CWC8+R9 مانتین ویو، کالیفرنیا، ایالات متحده آمریکا به صورت CWC8%2BR9%20Mountain%20View%20CA%20USA است).
  • components — یک فیلتر کامپوننت‌ها با عناصری که با یک خط عمودی ( | ) از هم جدا شده‌اند. فیلتر کامپوننت‌ها همچنین در صورت ارائه address ، به عنوان یک پارامتر اختیاری پذیرفته می‌شود. هر عنصر در فیلتر کامپوننت‌ها از یک جفت component:value تشکیل شده است و نتایج حاصل از ژئوکودر را به طور کامل محدود می‌کند. اطلاعات بیشتر در مورد فیلتر کامپوننت را در زیر ببینید.

برای راهنمایی بیشتر به سوالات متداول مراجعه کنید.

پارامترهای اختیاری در یک درخواست Geocoding:

• bounds — کادر محدودکننده‌ی نمای دید که در آن می‌توان نتایج geocode را به طور برجسته‌تری بایاس کرد. این پارامتر فقط بر نتایج geocoder تأثیر می‌گذارد، نه اینکه آنها را به طور کامل محدود کند. (برای اطلاعات بیشتر به Viewport Biasing در زیر مراجعه کنید.)
• language — زبانی که نتایج با آن برگردانده می‌شوند.
  • فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
  • اگر language ارائه نشود، geocoder تلاش می‌کند از زبان ترجیحی مشخص شده در سربرگ Accept-Language یا زبان مادری دامنه‌ای که درخواست از آن ارسال می‌شود، استفاده کند.
  • جئوکودر تمام تلاش خود را می‌کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به خطی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
  • اگر نامی به زبان ترجیحی موجود نباشد، ژئوکودر از نزدیکترین مورد منطبق استفاده می‌کند.
  • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها دارد. کدگذار جغرافیایی بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند. به عنوان مثال، utca و tér به ترتیب مترادف خیابان و میدان در زبان مجارستانی هستند.
• region — کد منطقه، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. این پارامتر فقط بر نتایج حاصل از geocoder تأثیر می‌گذارد، نه به طور کامل آنها را محدود می‌کند. (برای اطلاعات بیشتر به Region Biasing در زیر مراجعه کنید.) این پارامتر همچنین می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.
• components — یک فیلتر کامپوننت‌ها با عناصری که با یک خط عمودی ( | ) از هم جدا شده‌اند. فیلتر کامپوننت‌ها در صورتی مورد نیاز است که درخواست شامل address نباشد. هر عنصر در فیلتر کامپوننت‌ها از یک جفت component:value تشکیل شده است و نتایج حاصل از geocoder را به طور کامل محدود می‌کند. اطلاعات بیشتر در مورد فیلتر کامپوننت را در زیر ببینید.
• extra_computations — از این پارامتر برای مشخص کردن ویژگی‌های اضافی زیر در پاسخ استفاده کنید:
  • ADDRESS_DESCRIPTORS — برای جزئیات بیشتر به توصیف‌گرهای آدرس مراجعه کنید.
  • BUILDING_AND_ENTRANCES — برای جزئیات بیشتر به ورودی‌ها و طرح کلی ساختمان مراجعه کنید.
  برای فعال کردن چندین مورد از این ویژگی‌ها برای یک درخواست API یکسان، پارامتر extra_computations را در درخواست برای هر ویژگی وارد کنید، برای مثال:

  extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

پاسخ‌ها

پاسخ‌های ژئوکدینگ در قالبی که توسط پرچم output در درخواست URL مشخص شده است، یا به طور پیش‌فرض در قالب JSON بازگردانده می‌شوند.

در این مثال، API مربوط به Geocoding برای پرس‌وجویی در آدرس "1600 Amphitheatre Parkway, Mountain View, CA" درخواست پاسخ json می‌کند.

این درخواست استفاده از پرچم output JSON را نشان می‌دهد:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

این درخواست استفاده از پرچم output XML را نشان می‌دهد:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

برای مشاهده نمونه پاسخ‌های JSON و XML، تب‌های زیر را انتخاب کنید.

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

کدهای وضعیت

فیلد "status" در شیء پاسخ Geocoding شامل وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال‌زدایی باشد تا به شما در پیگیری دلیل عدم کارکرد geocoding کمک کند. فیلد "status" ممکن است حاوی مقادیر زیر باشد:

• "OK" نشان می‌دهد که هیچ خطایی رخ نداده است؛ آدرس با موفقیت تجزیه شده و حداقل یک کد جغرافیایی بازگردانده شده است.
• "ZERO_RESULTS" نشان می‌دهد که کد جغرافیایی موفقیت‌آمیز بوده اما هیچ نتیجه‌ای برنگردانده است. این ممکن است در صورتی رخ دهد که به کد جغرافیایی یک address ناموجود داده شده باشد.
• OVER_DAILY_LIMIT به هر یک از موارد زیر اشاره دارد:
  • کلید API موجود نیست یا نامعتبر است.
  • پرداخت در حساب شما فعال نشده است.
  • از سقف مصرف تعیین‌شده توسط خود کاربر، عبور شده است.
  • روش پرداخت ارائه شده دیگر معتبر نیست (برای مثال، اعتبار کارت اعتباری منقضی شده است).

  برای یادگیری نحوه رفع این مشکل، به سوالات متداول نقشه‌ها مراجعه کنید.

• "OVER_QUERY_LIMIT" نشان می‌دهد که از سهمیه خود فراتر رفته‌اید.
• "REQUEST_DENIED" نشان می‌دهد که درخواست شما رد شده است.
• "INVALID_REQUEST" عموماً نشان می‌دهد که عبارت جستجو ( address ، components یا latlng ) وجود ندارد.
• "UNKNOWN_ERROR" نشان می‌دهد که درخواست به دلیل خطای سرور قابل پردازش نیست. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.

پیام‌های خطا

وقتی geocoder کد وضعیتی غیر از OK را برمی‌گرداند، ممکن است یک فیلد error_message اضافی در شیء پاسخ Geocoding وجود داشته باشد. این فیلد حاوی اطلاعات دقیق‌تری در مورد دلایل کد وضعیت داده شده است.

نتایج

وقتی geocoder نتایج را برمی‌گرداند، آنها را در یک آرایه results (JSON) قرار می‌دهد. حتی اگر geocoder هیچ نتیجه‌ای برنگرداند (مثلاً اگر آدرس وجود نداشته باشد)، باز هم یک آرایه results خالی برمی‌گرداند. (پاسخ‌های XML شامل صفر یا چند عنصر <result> هستند.)

یک نتیجه‌ی معمول شامل فیلدهای زیر است:

• آرایه types[] نوع نتیجه برگشتی را نشان می‌دهد. این آرایه شامل مجموعه‌ای از صفر یا چند برچسب است که نوع ویژگی برگشتی در نتیجه را مشخص می‌کند. به عنوان مثال، یک کد جغرافیایی "شیکاگو" "locality" را برمی‌گرداند که نشان می‌دهد "شیکاگو" یک شهر است و همچنین "political" را برمی‌گرداند که نشان می‌دهد یک نهاد سیاسی است. وقتی هیچ نوع شناخته‌شده‌ای برای آن جزء آدرس وجود ندارد، ممکن است اجزا یک آرایه انواع خالی داشته باشند. API ممکن است در صورت نیاز مقادیر نوع جدیدی اضافه کند. برای اطلاعات بیشتر، به Address types و address components مراجعه کنید.
• formatted_address رشته‌ای است که حاوی آدرس قابل خواندن توسط انسان این مکان است.

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

  آدرس قالب‌بندی شده به طور منطقی از یک یا چند جزء آدرس تشکیل شده است. برای مثال، آدرس "111 خیابان هشتم، نیویورک، نیویورک" از اجزای زیر تشکیل شده است: "111" (شماره خیابان)، "خیابان هشتم" (مسیر)، "نیویورک" (شهر) و "NY" (ایالت ایالات متحده).

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

• address_components[] آرایه‌ای است که شامل اجزای جداگانه‌ای است که برای این آدرس قابل استفاده هستند.

  هر جزء آدرس معمولاً شامل فیلدهای زیر است:

  • types[] آرایه‌ای است که نوع مؤلفه آدرس را نشان می‌دهد. لیست انواع پشتیبانی شده را ببینید.
  • long_name توضیحات متنی کامل یا نام کامپوننت آدرس است که توسط Geocoder برگردانده می‌شود.
  • short_name یک نام متنی خلاصه شده برای کامپوننت آدرس است، در صورت وجود. برای مثال، یک کامپوننت آدرس برای ایالت آلاسکا ممکن است دارای یک long_name به شکل "Alaska" و یک short_name به شکل "AK" با استفاده از مخفف پستی دو حرفی باشد.

  به نکات زیر در مورد آرایه address_components[] توجه کنید:

  • آرایه اجزای آدرس ممکن است شامل اجزای بیشتری نسبت به formatted_address باشد.
  • این آرایه لزوماً شامل تمام موجودیت‌های سیاسی که حاوی یک آدرس هستند، به جز آنهایی که در formatted_address قرار دارند، نمی‌شود. برای بازیابی تمام موجودیت‌های سیاسی که حاوی یک آدرس خاص هستند، باید از geocoding معکوس استفاده کنید و طول/عرض جغرافیایی آدرس را به عنوان پارامتر به درخواست ارسال کنید.
  • تضمینی وجود ندارد که قالب پاسخ بین درخواست‌ها یکسان باقی بماند. به طور خاص، تعداد address_components بر اساس آدرس درخواستی متفاوت است و می‌تواند در طول زمان برای همان آدرس تغییر کند. یک جزء می‌تواند موقعیت خود را در آرایه تغییر دهد. نوع جزء می‌تواند تغییر کند. یک جزء خاص ممکن است در پاسخ بعدی وجود نداشته باشد.

  برای مدیریت آرایه‌ای از اجزا، باید پاسخ را تجزیه کرده و مقادیر مناسب را از طریق عبارات انتخاب کنید. به راهنمای تجزیه پاسخ مراجعه کنید.

• postcode_localities[] آرایه‌ای است که حداکثر ۱۰۰ منطقه‌ی موجود در یک کد پستی را نشان می‌دهد. این فقط زمانی وجود دارد که نتیجه یک کد پستی باشد که شامل چندین منطقه‌ی محلی باشد.
• geometry شامل اطلاعات زیر است:
  • location شامل مقدار طول و عرض جغرافیایی با کد جغرافیایی است. برای جستجوی آدرس‌های معمولی، این فیلد معمولاً مهمترین است.

  • location_type داده‌های اضافی در مورد مکان مشخص شده را ذخیره می‌کند. مقادیر زیر در حال حاضر پشتیبانی می‌شوند:

    • "ROOFTOP" نشان می‌دهد که نتیجه‌ی برگردانده شده یک کد جغرافیایی دقیق است که برای آن اطلاعات مکانی دقیقی تا دقت آدرس خیابان داریم.
    • "RANGE_INTERPOLATED" نشان می‌دهد که نتیجه‌ی برگردانده شده، تقریبی (معمولاً در یک جاده) را نشان می‌دهد که بین دو نقطه‌ی دقیق (مانند تقاطع‌ها) درون‌یابی شده است. نتایج درون‌یابی شده معمولاً زمانی بازگردانده می‌شوند که کدهای جغرافیایی پشت بام برای آدرس خیابان در دسترس نباشند.
    • "GEOMETRIC_CENTER" نشان می‌دهد که نتیجه‌ی برگردانده شده، مرکز هندسی یک نتیجه مانند یک چندخطی (مثلاً یک خیابان) یا چندضلعی (منطقه) است.
    • "APPROXIMATE" نشان می‌دهد که نتیجه‌ی برگشتی تقریبی است.
  • viewport شامل viewport پیشنهادی برای نمایش نتیجه‌ی برگشتی است که به صورت دو مقدار طول و عرض جغرافیایی مشخص شده و گوشه‌ی southwest و northeast کادر محدوده‌ی viewport را تعریف می‌کند. عموماً از viewport برای قاب‌بندی نتیجه هنگام نمایش آن به کاربر استفاده می‌شود.
  • bounds (که به صورت اختیاری برگردانده می‌شود) کادر مرزی را ذخیره می‌کند که می‌تواند به طور کامل نتیجه‌ی برگشتی را در خود جای دهد. توجه داشته باشید که این مرزها ممکن است با نمای پیشنهادی مطابقت نداشته باشند. (برای مثال، سانفرانسیسکو شامل جزایر فارالون است که از نظر فنی بخشی از شهر هستند، اما احتمالاً نباید در نمای دید برگردانده شوند.)
• plus_code (به Open Location Code و Plus codes مراجعه کنید) یک مرجع مکانی کدگذاری شده است که از مختصات طول و عرض جغرافیایی گرفته شده و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچکتر. کدهای پلاس می‌توانند به عنوان جایگزینی برای آدرس خیابان‌ها در مکان‌هایی که آدرس وجود ندارد (جایی که ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نامگذاری نشده‌اند) استفاده شوند. API همیشه کدهای پلاس را برنمی‌گرداند.

  وقتی سرویس یک کد پلاس برمی‌گرداند، به صورت یک کد سراسری و یک کد مرکب قالب‌بندی می‌شود:

  • global_code یک کد ناحیه‌ای ۴ کاراکتری و یک کد محلی ۶ کاراکتری یا بیشتر است (۸۴۹VCWC8+R9).
  • compound_code یک کد محلی ۶ کاراکتری یا بیشتر با موقعیت مکانی صریح (CWC8+R9، مانتین ویو، کالیفرنیا، ایالات متحده) است. این محتوا را به صورت برنامه‌نویسی تجزیه نکنید.
  در صورت وجود، API هم کد سراسری و هم کد ترکیبی را برمی‌گرداند. با این حال، اگر نتیجه در یک مکان دورافتاده (مثلاً اقیانوس یا بیابان) باشد، فقط کد سراسری ممکن است برگردانده شود.

• partial_match نشان می‌دهد که geocoder تطابق دقیقی برای درخواست اصلی برنگردانده است، اگرچه توانسته بخشی از آدرس درخواستی را مطابقت دهد. شما می‌توانید درخواست اصلی را از نظر غلط املایی و/یا آدرس ناقص بررسی کنید.

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

• place_id یک شناسه منحصر به فرد است که می‌تواند با سایر APIهای گوگل مورد استفاده قرار گیرد. برای مثال، می‌توانید از place_id در یک درخواست Places API برای دریافت جزئیات یک کسب و کار محلی، مانند شماره تلفن، ساعات کاری، نظرات کاربران و موارد دیگر استفاده کنید. به نمای کلی شناسه مکان مراجعه کنید.

انواع آدرس و انواع مؤلفه آدرس

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

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

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

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

علاوه بر موارد فوق، اجزای آدرس ممکن است شامل انواع ذکر شده در زیر باشند.

بایاس کردن ویوپورت

در یک درخواست Geocoding، می‌توانید به سرویس Geocoding دستور دهید که نتایج درون یک نمای مشخص (که به صورت یک کادر محصورکننده بیان می‌شود) را ترجیح دهد. شما این کار را با تنظیم پارامتر bounds در URL درخواست انجام می‌دهید.

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

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

درخواست:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

پاسخ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

با این حال، اضافه کردن یک آرگومان bounds که یک کادر مرزی را در اطراف بخش شمال شرقی ایالات متحده تعریف می‌کند، منجر به این ژئوکد می‌شود که شهر واشنگتن دی سی را برمی‌گرداند:

درخواست:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

پاسخ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

بایاس منطقه

در یک درخواست Geocoding، می‌توانید با استفاده از پارامتر region به سرویس Geocoding دستور دهید تا نتایجی را که به یک منطقه خاص متمایل هستند، برگرداند. این پارامتر یک آرگومان ccTLD (دامنه سطح بالای کد کشور) می‌گیرد که گرایش منطقه را مشخص می‌کند. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، به جز برخی استثنائات قابل توجه. به عنوان مثال، ccTLD بریتانیا "uk" ( .co.uk ) است در حالی که کد ISO 3166-1 آن "gb" است (از نظر فنی برای موجودیت "بریتانیای کبیر و ایرلند شمالی").

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

برای مثال، یک کد جغرافیایی برای "تولدو" این نتیجه را برمی‌گرداند، زیرا دامنه پیش‌فرض برای API کد جغرافیایی روی ایالات متحده تنظیم شده است. درخواست:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

پاسخ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

یک درخواست ژئوکدینگ برای "تولدو" با region=es (اسپانیا)، شهر اسپانیایی را برمی‌گرداند.

درخواست:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

پاسخ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

فیلتر کردن کامپوننت

در یک پاسخ Geocoding، API مربوط به Geocoding می‌تواند نتایج آدرس محدود به یک منطقه خاص را برگرداند. می‌توانید این محدودیت را با استفاده از فیلتر components مشخص کنید. یک فیلتر شامل لیستی از جفت‌های component:value که با یک pipe ( | ) از هم جدا شده‌اند. مقادیر فیلتر از همان روش‌های تصحیح املا و تطبیق جزئی مانند سایر درخواست‌های Geocoding پشتیبانی می‌کنند. اگر geocoder یک تطبیق جزئی برای یک فیلتر component پیدا کند، پاسخ شامل یک فیلد partial_match خواهد بود.

components که می‌توانند فیلتر شوند عبارتند از:

• postal_code با postal_code و postal_code_prefix مطابقت دارد.
• country با نام کشور یا کد دو حرفی ISO 3166-1 کشور مطابقت دارد. این API از استاندارد ISO برای تعریف کشورها پیروی می‌کند و فیلتر کردن زمانی که از کد ISO مربوطه برای کشور استفاده می‌شود، بهترین عملکرد را دارد.

components زیر ممکن است برای تأثیرگذاری بر نتایج مورد استفاده قرار گیرند، اما اجرا نخواهند شد:

• route با نام بلند یا کوتاه یک مسیر مطابقت دارد.
• تطابق locality با انواع locality و sublocality .
• administrative_area با تمام سطوح administrative_area مطابقت دارد.

نکاتی در مورد فیلتر کردن اجزا:

• این فیلترهای کامپوننت را در درخواست‌ها تکرار نکنید، در غیر این صورت API Invalid_request برمی‌گرداند: country ، postal_code ، route
• اگر درخواست شامل فیلترهای کامپوننت تکراری باشد، API آن فیلترها را به عنوان AND ارزیابی می‌کند، نه OR.
• نتایج با نقشه‌های گوگل سازگار است، که گاهی اوقات پاسخ‌های غیرمنتظره ZERO_RESULTS می‌دهد. استفاده از تکمیل خودکار مکان ممکن است در برخی موارد نتایج بهتری ارائه دهد. برای کسب اطلاعات بیشتر، به این سوالات متداول مراجعه کنید.
• برای هر مؤلفه آدرس، آن را یا در پارامتر address یا در فیلتر components مشخص کنید، اما نه هر دو. تعیین مقادیر یکسان در هر دو ممکن است منجر به ZERO_RESULTS شود.

یک کد جغرافیایی برای "خیابان های، هستینگز" با components=country:GB نتیجه را به جای هستینگز-آن-هادسون، ایالات متحده، در هستینگز، انگلستان برمی‌گرداند.

درخواست:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

پاسخ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

درخواست کد جغرافیایی برای موقعیت مکانی "سانتا کروز" با components=country:ES سانتا کروز د تنریفه در جزایر قناری، اسپانیا را برمی‌گرداند.

درخواست:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

پاسخ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

فیلتر کردن کامپوننت فقط در صورتی پاسخ ZERO_RESULTS را برمی‌گرداند که فیلترهایی ارائه دهید که یکدیگر را مستثنی کنند.

درخواست:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

پاسخ:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

شما می‌توانید با استفاده از فیلتر components ، پرس‌وجوهای معتبری بدون پارامتر آدرس ایجاد کنید. (هنگام ژئوکدینگ یک آدرس کامل، اگر درخواست شامل نام و شماره ساختمان‌ها باشد، پارامتر address الزامی است.)

درخواست:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

پاسخ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}