Geocoding API سرویسی وب است که نشانیها را به مختصات و «شناسههای مکان» تبدیل میکند و مختصات یا «شناسههای مکان» را به نشانی تبدیل میکند. روش v4 SearchDestinations آن نیز جزئیات مقصد مانند ورودیهای ساختمان، نقاط ناوبری، طرحهای کلی ساختمان و زمین، و نشانگرهای مکانی اطراف را برمیگرداند.
Geocoding API: حقایق کلیدی
- محصول: Geocoding API
- دسته: مکانها
- پلاتفرم: سرویس وب (REST)
- اجرا در: سرور (کد پسین)
- مرحله راهاندازی: GA
- چرخه حیات: فعال
- نمای کلی: نمای کلی Geocoding API
Geocoding API: زمان استفاده از آن
در شرایط زیر از Geocoding API استفاده کنید:
- باید نشانی خیابان را به مختصات طول/عرض جغرافیایی و «شناسه مکان» در سرور زیرینه خود تبدیل کنید.
- برای مختصات GPS یا «شناسه مکان» شناختهشده، به نشانی نمایشی یا تقسیمات کشوری (شهر، کد پستی) نیاز دارید.
- برای مسیریابی رانندگان یا پیکها به مقصد، به ورودیهای ساختمان، نقاط ناوبری قابلمسیریابی، یا طرحهای کلی ساختمان/زمین نیاز دارید.
- باید مقصد را در داخل مجتمعی بزرگ (فرودگاه، مرکز خرید، پردیس) به زیرمقصدها یا نشانگرهای مکانی اطراف تبدیل کنید.
در موارد زیر از Geocoding API استفاده نکنید:
- به زمینکدیابی از جاوا اسکریپت مرورگر سمت کارخواه نیاز دارید؛ فراخوانی v4 با کلید میانای برنامهسازی کاربردی لورفته یک خطر امنیتی است. بهجای آن از Maps JavaScript API استفاده کنید.
- باید مسیر یا زمان تخمینی رسیدن به مقصد زمینکدیابیشده را محاسبه کنید. درعوض از Routes API استفاده کنید.
- به راهنمایی گامبهگام برای رسیدن به یک کد نقطه ناوبری در برنامه Android نیاز دارید. درعوض از کیت توسعه نرمافزار ناوبری برای Android استفاده کنید.
- به راهنمایی گامبهگام برای رسیدن به یک کد نقطه ناوبری در برنامه iOS نیاز دارید. بهجای آن از کیت توسعه نرمافزار ناوبری برای iOS استفاده کنید.
Geocoding API: setup
- سرویس برای فعال کردن:
geocoding-backend.googleapis.com - اصالتسنجی: کلید میانای API، OAuth 2.0، حساب سرویس
- شروع به کار: راهاندازی Geocoding API
- مرجع: مرجع Geocoding API
- قیمتگذاری: استفاده و صورتحساب Geocoding API
- خطمشیها: خطمشیهای Geocoding API
- یادداشتهای انتشار: یادداشتهای انتشار Geocoding API
Geocoding API: related products
- اغلب با این موارد استفاده میشود: Routes API، کیت توسعه نرمافزار پیمایش برای Android، کیت توسعه نرمافزار پیمایش برای iOS
Geocoding API: اشتباهات رایج
- مشکل: درخواستهای
SearchDestinationsبدون پوشش فیلد با خطا مواجه میشوند؛ برخلافGeocodeAddress،GeocodeLocation، وGeocodePlace، پوشش فیلد الزامی است. اصلاح: سرصفحهX-Goog-FieldMaskیا پارامتر$fieldsرا در هر درخواستSearchDestinationsتنظیم کنید. /maps/documentation/geocoding/choose-fields را ببینید. - مشکل: v4
GeocodeAddressفیلتر مؤلفه سخت ندارد (v3components=country:US). پارامترهای ساختاریافتهaddress.*در یک نشانی ترکیب میشوند و نتایج را فیلتر نمیکنند؛regionCodeهمچنین در v4 پیشفرضی ندارد (v3 بهطور پیشفرض رویusبود). راهحل: فیلتر کردنresultsدر سمت کارخواه:regionCodeبا حروف بزرگ را باpostalAddress.regionCodeمطابقت دهید؛ مناطق اداری ۲ حرفی با حروف بزرگ را باpostalAddress.administrativeAreaوadministrative_area_level_naddressComponents(shortText) مطابقت دهید؛ هم ورودی و همpostalAddress.postalCodeرا نرمالسازی کنید (فاصلهها/خط تیرهها را حذف کنید و قوانین منطقه را اعمال کنید). /maps/documentation/geocoding/geocoding-v4-migrate را ببینید. - مشکل: فراخوانی Geocoding API v4 مستقیماً از جاوا اسکریپت مرورگر، کلید میانای برنامهسازی کاربردی را افشا میکند؛ محدودیتهای ارجاعدهنده HTTP را میتوان با جعل سرصفحه
Refererدور زد. اصلاح: نسخه ۴ را از پسای خودتان با کلید محافظتشده فراخوانی کنید، یا از Maps JavaScript API Geocoding Service (پسا نسخه ۳) برای نیازهای سمت کارخواه استفاده کنید. /maps/documentation/geocoding/geocoding-v4-migrate را ببینید. - مشکل: برخلاف v3 و دیگر روشهای v4،
SearchDestinationsمیتواند نتایجی را برگرداند که نشانی اصلی دقیقی ندارند. اصلاح: وقتی فقط به نتایجی با نشانیهای اصلی دقیق نیاز دارید،placeFilter.addressabilityرا رویPRIMARYتنظیم کنید. /maps/documentation/geocoding/geocoding-v4-migrate را ببینید. - مشکل: کدی که برای Geocoding API نسخه ۳ نوشته شده است در پاسخهای REST نسخه ۴ ازکار میافتد: نسخه ۴ از نامهای فیلد lowerCamelCase (
addressComponents، نهaddress_components) استفاده میکند،statusوerror_messageرا برمیدارد، و بهجای آرایهresults، یک شیء ریشه تکی ازGeocodePlaceبرمیگرداند. اصلاح: رمزهای وضعیت HTTP و متنهای خطا را در تماسهای REST نسخه ۴ بررسی کنید، فیلدهای lowerCamelCase (addressComponents،postalAddress) را بخوانید، و توجه داشته باشید که پاسخهای gRPC همچنان از snake_case استفاده میکنند. /maps/documentation/geocoding/geocoding-v4-migrate را ببینید.
Geocoding API: legacy and deprecated features
- دادههای محلی Geocoding API v3 (
extra_computations:BUILDING_AND_ENTRANCES،NAVIGATION_POINTS،GROUNDS؛ فیلدهای پاسخbuildings.entrances،navigation_points،buildings.building_outlines،grounds): از ۲۰۲۵/۰۸/۱۳ منسوخ شده است. جایگزین: روش (POST /v4/geocode/destinations) Geocoding API v4SearchDestinations. راهنمای انتقال را ببینید.
کارهایی که میتوانید با Geocoding API انجام دهید
برای هر تکلیف، راهنماهای پیوندشده در زیر را ببینید یا محصولات را در کاوشگر قابلیتها با یکدیگر مقایسه کنید.
- برگرداندن مختصات عرض جغرافیایی/طول جغرافیایی یک نشانی (زمینکدیابی).
- برگرداندن نشانی برای مجموعهای از مختصات عرض جغرافیایی/طول جغرافیایی (زمینکدیابی معکوس).
- محدود کردن درخواست زمینکدیابی برای برگرداندن نتایج در یک ناحیه نمایش خاص. توجه: در Geocoding API نسخه ۴، locationBias نتایج را بهسمت نمای هدف مشخصشده متمایل میکند و آنها را بهطور دقیق محدود نمیکند.
- درخواست زمینکدیابی یا زمینکدیابی معکوس را محدود کنید تا فقط نتایج مربوط به منطقه، کشور، یا کد پستی خاصی را برگرداند. توجه: در Geocoding API نسخه ۴، regionCode نتایج را بهسمت منطقه CLDR مشخصشده متمایل میکند و آنها را بهطور دقیق محدود نمیکند؛ برای فیلتر کردن مؤلفه نسخه ۳ قدیمی براساس کشور یا کد پستی، به https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering مراجعه کنید.
- درخواست زمینکدیابی معکوس را محدود کنید تا فقط نتایج مربوط به انواع نشانی مشخصشده را برگرداند. توجه: در Geocoding API نسخه ۴، پارامتر types نتایج زمینکدیابی معکوس برگرداندهشده را براساس نوع نشانی پساز جستجو فیلتر میکند، نه اینکه جستجوی اصلی را محدود کند.
- اطلاعات مربوط به مجاورت با نشانگرهای مکانی یا مناطق را برای نشانی برمیگرداند.
- اطلاعات مربوط به مجاورت با نشانگرهای مکان یا مناطق را برای مجموعهای از مختصات طول/عرض جغرافیایی برمیگرداند.
- اطلاعات مربوط به مجاورت با نشانگرهای مکان یا مناطق را برای شناسه مکان Google برمیگرداند.
- نشانی شناسه مکان Google را برگردانید.
- مختصات عرض جغرافیایی/طول جغرافیایی طرح کلی ساختمان را برای نشانی برگردانید.
- مختصات عرض جغرافیایی/طول جغرافیایی طرح کلی ساختمان را برای مجموعهای از مختصات عرض جغرافیایی/طول جغرافیایی برمیگرداند.
- مختصات طول/ عرض جغرافیایی طرح کلی ساختمان را برای شناسه «مکان Google» برمیگرداند.
- مختصات عرض جغرافیایی/طول جغرافیایی ورودی ساختمان را برای نشانی برگردانید.
- مختصات عرض جغرافیایی/طول جغرافیایی ورودی ساختمان را برای مجموعهای از مختصات عرض جغرافیایی/طول جغرافیایی برمیگرداند.
- مختصات طول/ عرض جغرافیایی ورودی ساختمان را برای شناسه «مکان Google» برگردانید.