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

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

درخواست کنید

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

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

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

json (توصیه می شود) خروجی را در نشانه گذاری شی جاوا اسکریپت (JSON) نشان می دهد. یا
xml خروجی را در XML نشان می دهد

HTTPS مورد نیاز است.

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

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

پارامترهای ژئوکدینگ (جستجوی طول و عرض جغرافیایی).

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

key - کلید API برنامه شما. این کلید درخواست شما را برای اهداف مدیریت سهمیه شناسایی می کند. نحوه گرفتن کلید را بیاموزید.
شما باید address یا components یا هر دو را در یک درخواست مشخص کنید:
- address - آدرس خیابان یا کد مثبتی که می‌خواهید به صورت جغرافیایی کدگذاری کنید. نشانی ها را مطابق با فرمت مورد استفاده سرویس پست ملی کشور مربوطه مشخص کنید. از عناصر آدرس اضافی مانند نام تجاری و شماره واحد، سوئیت یا طبقه باید اجتناب شود. عناصر آدرس خیابان باید با فاصله مشخص شوند (در اینجا به صورت url-escaped به %20 نشان داده شده است):
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
  کدهای بعلاوه را همانطور که در اینجا نشان داده شده است قالب بندی کنید (علائم بعلاوه به url-escape به %2B و فاصله ها به url-escape به %20 می شوند):
  - کد جهانی یک کد منطقه 4 کاراکتری و کد محلی 6 کاراکتری یا بیشتر است (849VCWC8+R9 849VCWC8%2BR9 است).
  - کد ترکیبی یک کد محلی 6 کاراکتری یا بیشتر با مکان صریح است (CWC8+R9 Mountain View, CA, USA CWC8%2BR9%20Mountain%20View%20CA%20USA است).
- components - یک فیلتر اجزا با عناصر جدا شده توسط یک لوله ( | ). در صورت ارائه address فیلتر اجزاء نیز به عنوان یک پارامتر اختیاری پذیرفته می شود. هر عنصر در فیلتر کامپوننت ها از یک جفت component:value تشکیل شده است و نتایج حاصل از ژئوکدر را به طور کامل محدود می کند. اطلاعات بیشتر در مورد فیلتر کردن اجزا را در زیر مشاهده کنید.

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

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

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

پاسخ ها

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

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

این درخواست با استفاده از پرچم 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، برگه های زیر را انتخاب کنید.

JSON

{
    "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"
}

توجه داشته باشید که پاسخ JSON شامل دو عنصر ریشه است:

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

به طور کلی، تنها یک ورودی در آرایه "results" برای جستجوی آدرس بازگردانده می‌شود، هرچند زمانی که جستارهای آدرس مبهم هستند، geocoder ممکن است چندین نتیجه را برگرداند.

XML

<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>

توجه داشته باشید که پاسخ XML از یک <GeocodeResponse> و دو عنصر سطح بالا تشکیل شده است:

<status> حاوی فراداده در مورد درخواست است. کدهای وضعیت را در زیر ببینید.
صفر یا چند عنصر <result> ، که هر کدام شامل یک مجموعه واحد از اطلاعات آدرس جغرافیایی و اطلاعات هندسی است.

پاسخ XML به طور قابل توجهی طولانی تر از پاسخ JSON است. به همین دلیل، توصیه می کنیم از json به عنوان پرچم خروجی ترجیحی استفاده کنید، مگر اینکه سرویس شما به دلایلی به xml نیاز داشته باشد. علاوه بر این، پردازش درخت‌های XML به دقت نیاز دارد تا به گره‌ها و عناصر مناسب ارجاع دهید. برای برخی از الگوهای طراحی توصیه شده برای پردازش خروجی، تجزیه XML با XPath را ببینید.

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

کدهای وضعیت

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

"OK" نشان می دهد که هیچ خطایی رخ نداده است. آدرس با موفقیت تجزیه شد و حداقل یک ژئوکد برگردانده شد.
"ZERO_RESULTS" نشان می دهد که ژئوکد موفقیت آمیز بود اما هیچ نتیجه ای نداشت. این ممکن است در صورتی رخ دهد که geocoder یک address غیرموجود ارسال شده باشد.
OVER_DAILY_LIMIT هر یک از موارد زیر را نشان می دهد:
- کلید API وجود ندارد یا نامعتبر است.
- صورتحساب در حساب شما فعال نشده است.
- از حد مجاز استفاده از خود فراتر رفته است.
- روش پرداخت ارائه شده دیگر معتبر نیست (مثلاً اعتبار کارت اعتباری منقضی شده است).
برای آشنایی با نحوه رفع این مشکل، سؤالات متداول Maps را ببینید.
"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[] نوع نتیجه برگشتی را نشان می دهد. این آرایه حاوی مجموعه‌ای از صفر یا چند تگ است که نوع ویژگی برگردانده شده در نتیجه را مشخص می‌کند. برای مثال، ژئوکد «شیکاگو» «محلی» را برمی‌گرداند که نشان می‌دهد «شیکاگو» یک شهر است، و همچنین «سیاسی» را برمی‌گرداند که نشان می‌دهد یک نهاد سیاسی است. هنگامی که هیچ نوع شناخته شده ای برای آن جزء آدرس وجود ندارد، کامپوننت ها ممکن است یک آرایه انواع خالی داشته باشند. API ممکن است در صورت نیاز مقادیر نوع جدیدی را اضافه کند. برای اطلاعات بیشتر، انواع آدرس و اجزای آدرس را ببینید.
formatted_address رشته ای است که حاوی آدرس قابل خواندن توسط انسان این مکان است.
اغلب این آدرس معادل آدرس پستی است. توجه داشته باشید که برخی از کشورها، مانند بریتانیا، به دلیل محدودیت های صدور مجوز، اجازه توزیع آدرس های پستی واقعی را نمی دهند.
آدرس فرمت شده منطقاً از یک یا چند جزء آدرس تشکیل شده است. به عنوان مثال، آدرس "111 8th Avenue, New York, NY" از اجزای زیر تشکیل شده است: "111" (شماره خیابان)، "8th Avenue" (مسیر)، "New York" (شهر) و "NY". (ایالت آمریکا).
آدرس فرمت شده را به صورت برنامه نویسی تجزیه نکنید. در عوض شما باید از اجزای آدرس جداگانه استفاده کنید، که پاسخ API علاوه بر فیلد آدرس فرمت شده شامل می شود.
address_components[] آرایه‌ای است که شامل اجزای جداگانه قابل اعمال برای این آدرس است.
هر جزء آدرس معمولاً شامل فیلدهای زیر است:
- types[] آرایه ای است که نوع جزء آدرس را نشان می دهد. لیست انواع پشتیبانی شده را ببینید.
- long_name شرح متن کامل یا نام جزء آدرس است که توسط Geocoder برگردانده شده است.
- short_name یک نام متنی مختصر برای جزء آدرس است، در صورت وجود. به عنوان مثال، یک جزء آدرس برای ایالت آلاسکا ممکن است با استفاده از مخفف پستی 2 حرفی دارای یک long_name از "Alaska" و یک short_name از "AK" باشد.
به حقایق زیر در مورد آرایه address_components[] توجه کنید:
- آرایه اجزای آدرس ممکن است شامل اجزای بیشتری نسبت به formatted_address باشد.
- این آرایه لزوماً شامل همه نهادهای سیاسی که حاوی آدرس هستند، به غیر از آنهایی که در formatted_address هستند، نمی شود. برای بازیابی تمام نهادهای سیاسی که حاوی یک آدرس خاص هستند، باید از رمزگذاری جغرافیایی معکوس استفاده کنید و عرض/طول جغرافیایی آدرس را به عنوان پارامتری برای درخواست ارسال کنید.
- قالب پاسخ تضمین نمی شود که بین درخواست ها یکسان بماند. به طور خاص، تعداد address_components بر اساس آدرس درخواستی متفاوت است و می تواند در طول زمان برای همان آدرس تغییر کند. یک جزء می تواند موقعیت خود را در آرایه تغییر دهد. نوع جزء می تواند تغییر کند. ممکن است یک جزء خاص در پاسخ بعدی گم شده باشد.
برای مدیریت آرایه مولفه‌ها، باید پاسخ را تجزیه کنید و مقادیر مناسب را از طریق عبارت‌ها انتخاب کنید. راهنمای تجزیه یک پاسخ را ببینید.
postcode_localities[] آرایه‌ای است که حداکثر 100 محل موجود در یک کد پستی را نشان می‌دهد. این تنها زمانی وجود دارد که نتیجه یک کد پستی باشد که دارای چندین محل باشد.
geometry حاوی اطلاعات زیر است:
- location شامل طول جغرافیایی و مقدار طول جغرافیایی کد شده است. برای جستجوی آدرس های معمولی، این فیلد معمولاً مهم ترین است.
- location_type داده های اضافی را در مورد مکان مشخص شده ذخیره می کند. مقادیر زیر در حال حاضر پشتیبانی می شوند:
  - "ROOFTOP" نشان می دهد که نتیجه بازگشتی یک ژئوکد دقیق است که ما اطلاعات موقعیت مکانی را با دقت آدرس خیابان داریم.
  - "RANGE_INTERPOLATED" نشان می دهد که نتیجه برگشتی یک تقریب (معمولاً در یک جاده) را منعکس می کند که بین دو نقطه دقیق (مانند تقاطع ها) درون یابی شده است. نتایج درون یابی عموماً زمانی که ژئوکدهای روی پشت بام برای یک آدرس خیابان در دسترس نباشند، برمی گردند.
  - "GEOMETRIC_CENTER" نشان می دهد که نتیجه برگشتی مرکز هندسی نتیجه ای مانند چند خط (مثلاً یک خیابان) یا چند ضلعی (منطقه) است.
  - "APPROXIMATE" نشان می دهد که نتیجه برگشتی تقریبی است.
- viewport حاوی نمای پیشنهادی برای نمایش نتیجه برگشتی است که به عنوان دو مقدار طول و عرض جغرافیایی مشخص شده است که گوشه southwest و northeast کادر محدودکننده دیدگاه را مشخص می کند. به طور کلی از viewport برای قاب بندی نتیجه هنگام نمایش آن به کاربر استفاده می شود.
- bounds (به صورت اختیاری برگردانده می شود) کادر محدود کننده را ذخیره می کند که می تواند به طور کامل حاوی نتیجه برگشتی باشد. توجه داشته باشید که این کران ممکن است با نمای پیشنهادی مطابقت نداشته باشد. (به عنوان مثال، سانفرانسیسکو شامل جزایر فارالون است که از نظر فنی بخشی از شهر هستند، اما احتمالاً نباید در نمای دید بازگردانده شوند.)
plus_code (به کد مکان باز و کدهای بعلاوه مراجعه کنید) یک مرجع مکان رمزگذاری شده است که از مختصات طول و عرض جغرافیایی مشتق شده است که مساحتی را نشان می دهد: 1/8000 درجه در 1/8000 درجه (حدود 14 متر در 14 متر در خط استوا) یا کوچکتر کدهای پلاس را می توان به عنوان جایگزینی برای آدرس های خیابان در مکان هایی که آدرس وجود ندارد (جایی که ساختمان ها شماره گذاری نمی شوند یا خیابان ها نام گذاری نمی شوند) استفاده می شود. API همیشه کدهای پلاس را بر نمی گرداند.
هنگامی که سرویس یک کد مثبت را برمی گرداند، به عنوان یک کد جهانی و یک کد ترکیبی قالب بندی می شود:
- global_code یک کد منطقه ای 4 کاراکتری و کد محلی 6 کاراکتری یا بیشتر است (849VCWC8+R9).
- compound_code یک کد محلی 6 کاراکتری یا بیشتر با مکان صریح است (CWC8+R9, Mountain View, CA, USA). این محتوا را به صورت برنامه نویسی تجزیه نکنید.
در صورت وجود، API هم کد جهانی و هم کد ترکیبی را برمی گرداند. با این حال، اگر نتیجه در یک مکان دور افتاده باشد (به عنوان مثال، یک اقیانوس یا بیابان)، تنها کد جهانی ممکن است برگردانده شود.
partial_match نشان می دهد که geocoder مطابقت دقیقی با درخواست اصلی برنگردانده است، اگرچه می تواند بخشی از آدرس درخواستی را مطابقت دهد. ممکن است بخواهید درخواست اصلی برای غلط املایی و/یا آدرس ناقص را بررسی کنید.
تطابق جزئی اغلب برای آدرس‌های خیابانی رخ می‌دهد که در محلی که در درخواست عبور می‌کنید وجود ندارد. زمانی که درخواستی با دو یا چند مکان در همان محل مطابقت داشته باشد، مسابقات جزئی نیز ممکن است برگردانده شوند. به عنوان مثال، "Hillpar St, Bristol, UK" یک مسابقه جزئی را برای خیابان هنری و خیابان هنریتا برمی گرداند. توجه داشته باشید که اگر یک درخواست شامل یک جزء آدرس غلط املایی باشد، سرویس کدگذاری جغرافیایی ممکن است یک آدرس جایگزین پیشنهاد دهد. پیشنهادهایی که از این طریق فعال می شوند نیز به عنوان تطابق جزئی علامت گذاری می شوند.
place_id یک شناسه منحصر به فرد است که می تواند با سایر API های Google استفاده شود. برای مثال، می‌توانید از place_id در درخواست Places API برای دریافت جزئیات یک کسب‌وکار محلی، مانند شماره تلفن، ساعات کاری، نظرات کاربران و موارد دیگر استفاده کنید. نمای کلی شناسه مکان را ببینید.

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

آرایه types[] در نتیجه نشان دهنده نوع آدرس است. نمونه‌هایی از انواع آدرس‌ها عبارتند از آدرس خیابان، کشور یا یک نهاد سیاسی. همچنین یک آرایه types[] در address_components[] وجود دارد که نوع هر قسمت از آدرس را نشان می‌دهد. به عنوان مثال می توان به شماره خیابان یا کشور اشاره کرد. (در زیر لیست کاملی از انواع ارائه شده است.) آدرس ها ممکن است چندین نوع داشته باشند. انواع ممکن است "برچسب" در نظر گرفته شوند. به عنوان مثال، بسیاری از شهرها با نوع political و locality برچسب گذاری شده اند.

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

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 در فرانسه.

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

floor نشان دهنده طبقه یک ساختمان است.
establishment معمولاً مکانی را نشان می دهد که هنوز طبقه بندی نشده است.
landmark مکان نزدیکی را نشان می دهد که به عنوان مرجع برای کمک به ناوبری استفاده می شود.
point_of_interest یک نقطه مورد علاقه نامگذاری شده را نشان می دهد.
parking نشان دهنده یک پارکینگ یا سازه پارکینگ است.
post_box یک صندوق پستی خاص را نشان می دهد.
postal_town نشان‌دهنده گروه‌بندی مناطق جغرافیایی، مانند locality و sublocality است که برای آدرس‌های پستی در برخی کشورها استفاده می‌شود.
room نشان دهنده اتاق یک ساختمان است.
street_number شماره دقیق خیابان را نشان می دهد.
bus_station ، train_station و transit_station مکان اتوبوس، قطار یا ایستگاه حمل و نقل عمومی را نشان می دهد.

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

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

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

نتایج ژئوکدینگ می‌تواند برای هر دامنه‌ای که برنامه اصلی Google Maps در آن به طور رسمی راه‌اندازی شده است، سوگیری داشته باشد. توجه داشته باشید که بایاسینگ فقط نتایج را برای یک دامنه خاص ترجیح می دهد . اگر نتایج مرتبط تری در خارج از این دامنه وجود داشته باشد، ممکن است آنها را شامل شود.

به عنوان مثال، یک geocode برای "Toledo" این نتیجه را برمی گرداند، زیرا دامنه پیش فرض برای Geocoding 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"
}

درخواست ژئوکدینگ برای "Toledo" با 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 که توسط یک لوله ( | ) از هم جدا شده‌اند. مقادیر فیلتر از همان روش‌های تصحیح املا و تطبیق جزئی مانند سایر درخواست‌های Geocoding پشتیبانی می‌کنند. اگر geocoder یک تطابق جزئی برای یک فیلتر جزء پیدا کند، پاسخ حاوی یک قسمت partial_match خواهد بود.

components قابل فیلتر عبارتند از:

postal_code با postal_code و postal_code_prefix مطابقت دارد.
country با نام کشور یا کد کشور ISO 3166-1 دو حرفی مطابقت دارد. API از استاندارد ISO برای تعریف کشورها پیروی می کند و فیلتر هنگام استفاده از کد ISO مربوطه کشور بهترین عملکرد را دارد.
توجه: اگر نتایج غیرمنتظره‌ای را با کد کشور دریافت کردید، بررسی کنید که از کدی استفاده می‌کنید که شامل کشورها، مناطق وابسته و مناطق خاص جغرافیایی مورد نظر شما می‌شود. اطلاعات کد را می‌توانید در ویکی‌پدیا بیابید: فهرست کدهای کشورها ISO 3166 یا پلتفرم مرور آنلاین ISO .

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

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

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

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

یک ژئوکد برای "High St, Hastings" با 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"
}