مرجع سریع Geocoding API

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 API: اشتباهات رایج

  • مشکل: درخواست‌های SearchDestinations بدون پوشش فیلد با خطا مواجه می‌شوند؛ برخلاف GeocodeAddress، GeocodeLocation، و GeocodePlace، پوشش فیلد الزامی است. اصلاح: سرصفحه X-Goog-FieldMask یا پارامتر $fields را در هر درخواست SearchDestinations تنظیم کنید. /maps/documentation/geocoding/choose-fields را ببینید.
  • مشکل: v4 GeocodeAddress فیلتر مؤلفه سخت ندارد (v3 components=country:US). پارامترهای ساختاریافته address.* در یک نشانی ترکیب می‌شوند و نتایج را فیلتر نمی‌کنند؛ regionCode همچنین در v4 پیش‌فرضی ندارد (v3 به‌طور پیش‌فرض روی us بود). راه‌حل: فیلتر کردن results در سمت کارخواه: regionCode با حروف بزرگ را با postalAddress.regionCode مطابقت دهید؛ مناطق اداری ۲ حرفی با حروف بزرگ را با postalAddress.administrativeArea و administrative_area_level_n addressComponents (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 v4 SearchDestinations. راهنمای انتقال را ببینید.

کارهایی که می‌توانید با Geocoding API انجام دهید

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