Geocoding API v4 چندین روش جدید معرفی می‌کند که جایگزین عملکرد در نسخه ۳ این API می‌شود. این راهنما به شما نشان می‌دهد که چگونه برنامه خود را برای استفاده از روش‌های جدید v4 منتقل کنید.
می‌توانید از کلیدهای میانای API موجودتان با روش‌های جدید v4 استفاده کنید. بااین‌حال، اگر درخواست افزایش سهمیه برای نسخه ۳ میانای برنامه‌سازی کاربردی داده‌اید، باید برای میاناهای برنامه‌سازی کاربردی جدید نسخه ۴ درخواست افزایش سهمیه بدهید.
انتقال از «زمین‌کدیابی مستقیم» نسخه ۳
اگر از v3 Geocoding برای زمین‌کدیابی نشانی‌ها استفاده می‌کنید، باید به روش v4 Geocode an address مهاجرت کنید که درخواست GET را می‌پذیرد.
v4 API نام‌ها، ساختار، و پشتیبانی از چندین پارامتر را تغییر می‌دهد. توصیه می‌کنیم برای مشخص کردن فیلدهایی که می‌خواهید در پاسخ برگردانده شوند، از ماسک فیلد استفاده کنید.
درخواست کردن تغییرات پارامتر
| پارامتر v3 | پارامتر v4 | یادداشت‌ها |
|---|---|---|
address، components |
address |
نشانی غیرساختارمند (نسخه ۳ address) اکنون در مسیر نشانی وب ارسال می‌شود. عناصر نشانی ساختاریافته (v3 components) می‌توانند به‌عنوان پارامترهای پُرسمان address.* منتقل شوند. بازتولید فیلترهای مؤلفه نسخه ۳ را ببینید. |
bounds |
locationBias.rectangle |
تغییر نام داده شد؛ ساختار به شیء تغییر کرد. |
language |
languageCode |
نام تغییر کرد. وقتی حذف شود، v3 از سرصفحه Accept-Language استفاده می‌کند یا به‌طور پیش‌فرض به en می‌رود، درحالی‌که v4 به‌طور پیش‌فرض به زبان محلی و نویسه مکان می‌رود. |
region |
regionCode |
نام تغییر کرد. وقتی حذف شود، v3 به‌طور پیش‌فرض روی us قرار می‌گیرد، درحالی‌که v4 مقدار پیش‌فرض ندارد. |
extra_computations |
برداشته شد | با روش SearchDestinations جایگزین شده است. |
تغییرات فیلد پاسخ
| فیلد v3 | فیلد v4 | یادداشت‌ها |
|---|---|---|
status، error_message |
برداشته شد | نسخه ۴ از کدهای وضعیت HTTP و متن‌های خطا استفاده می‌کند. |
results.address_components.long_name / results.address_components.short_name |
results.addressComponents.longText / results.addressComponents.shortText |
نام تغییر کرد. |
results.geometry.location_type |
results.granularity |
نام تغییر کرد. |
results.geometry.location |
results.location |
نام‌های فیلد: lat/lng -> latitude/longitude. |
results.geometry.viewport |
results.viewport |
نام فیلدها: northeast/southwest -> high/low. |
results.postcode_localities |
results.postalCodeLocalities |
نام تغییر کرد. اکنون برای یک یا چند محل برگردانده شده است (نسخه ۳ به بیشتر از ۱ نیاز دارد). |
results.partial_match |
برداشته شد | |
| جدید | results.addressComponents.languageCode |
زبان عنصر نشانی خاص. |
| جدید | results.bounds |
کران‌های صریح بااستفاده از high/low. |
| جدید | results.place |
نام منبع برای مکان. |
| جدید | results.postalAddress |
شیء PostalAddress ساختاریافته. |
بازتولید فیلترهای عنصر v3
«زمین‌کدیابی پیش‌رو» در «زمین‌کدیابی» نسخه ۳ شامل پارامتر components بود که
فیلتر کردن سخت نتایج را برای مؤلفه‌های خاص (مثلاً
components=country:US) فعال می‌کرد. «زمین‌کدیابی پیش‌رو» در نسخه ۴ از این نوع
فیلتر کردن سخت در پارامترهای درخواست پشتیبانی نمی‌کند. در نسخه ۴، می‌توانید اطلاعات نشانی را به‌صورت یک رشته غیرساختاریافته در مسیر یا به‌صورت پارامترهای پُرسمان ساختاریافته مانند address.addressLines، address.locality، address.administrativeArea، address.postalCode، و address.regionCode ارائه دهید.
پارامترهای ساختاری به‌عنوان فیلترهای سخت عمل نمی‌کنند. درعوض، همه عناصر ارائه‌شده با هم ترکیب می‌شوند تا نشانی کاملی را تشکیل دهند که
میانای برنامه‌سازی کاربردی تلاش می‌کند آن را زمین‌کدگذاری کند. این «میانای برنامه‌سازی کاربردی» در همه عناصر، بهترین مطابقت را برای کل نشانی مشخص‌شده جستجو می‌کند. ارائه مؤلفه‌ها به‌صورت ساختاریافته می‌تواند به میانای برنامه‌سازی کاربردی کمک کند
تا قصد را بهتر درک کند، به‌ویژه زمانی که اطلاعات نشانی از فیلدهای فرم جداگانه جمع‌آوری می‌شود. این کار می‌تواند به میانای برنامه‌سازی کاربردی کمک کند تا غلط‌های املایی جزئی یا ابهامات موجود در هر مؤلفه را مدیریت کند، زیرا نوع اطلاعات در هر فیلد مشخص است.
برای دستیابی به رفتاری مشابه فیلترهای مؤلفه سخت v3، باید فیلتر کردن سمت کارخواه را در آرایه results که توسط میانای برنامه‌سازی کاربردی v4 براساس اشیاء postalAddress و addressComponents در پاسخ برگردانده شده است پیاده‌سازی کنید.
جدول زیر بهترین مطابقت بین فیلترهای v3 components و
فیلدهای v4 postalAddress را نشان می‌دهد:
| فیلتر عنصر v3 | فیلد پاسخ v4 |
|---|---|
country |
postalAddress.regionCode |
postal_code |
postalAddress.postalCode |
administrative_area |
postalAddress.administrativeArea یا addressComponents |
نمونه‌های فیلتر کردن سمت کارخواه
مثال‌های زیر نشان می‌دهند که چگونه نتایج را فیلتر کنید تا به رفتاری مشابه فیلتر کردن مؤلفه v3 برای فیلدهای پشتیبانی‌شده دست یابید: کشور، تقسیمات کشوری، و کد پستی. توصیه نمی‌شود که فیلتر کردن را روی فیلدهای دیگر انجام دهید زیرا معیار فیلتر کردن قابل‌اعتمادی وجود ندارد.
فیلتر کردن براساس کشور
address.regionCode را از درخواستتان با postalAddress.regionCode در هر نتیجه مطابقت دهید. توجه داشته باشید که اگرچه API کدهای منطقه حروف کوچک را در درخواست می‌پذیرد، اما همیشه آن‌ها را در پاسخ به‌صورت حروف بزرگ برمی‌گرداند، بنابراین باید ورودی خود را قبل‌از مقایسه به حروف بزرگ تبدیل کنید.
نمونه کد Python
def filter_by_country(results, region_code): return [ res for res in results if res.get('postalAddress', {}).get('regionCode') == region_code.upper() ] # Example usage: # v4_response = ... # API call response # filtered = filter_by_country(v4_response.get('results', []), 'US')
نمونه کد Node.js
function filterByCountry(results, regionCode) { return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase()); } // Example usage: // const v4Response = ... # API call response // const filtered = filterByCountry(v4Response.results, 'US');
فیلتر کردن براساس «تقسیمات کشوری»
address.administrativeArea را از درخواستتان با postalAddress.administrativeArea در هر نتیجه مطابقت دهید. مشابه کد کشور، باید ورودی خود را قبل‌از مقایسه به حروف بزرگ تبدیل کنید. این مورد فقط زمانی قابل‌اطمینان است که administrativeArea در درخواست شما با اختصار استاندارد ۲ حرفی ارائه شده باشد. postalAddress.administrativeArea در پاسخ ممکن است به دلایل مختلفی مستقیماً با پسوندهای کد ISO 3166-2 مطابقت نداشته باشد. اولاً، در برخی مناطق، بخش فرعی مربوط به کد ISO 3166-2 بخشی از نمایش استاندارد نشانی‌های پستی نیست. برای مثال، در اسپانیا، تقسیمات کشوری سطح ۱ (مثلاً «CN» برای جزایر قناری) ممکن است در addressComponents وجود داشته باشد، اما postalAddress.administrativeArea ممکن است حاوی منطقه سطح ۲ باشد (مثلاً «سانتا کروس د تنریف»). ثانیاً، در برخی مناطق، از مخفف بخش فرعی معمولاً استفاده نمی‌شود و در postalAddress.administrativeArea با نام طولانی‌تری نشان داده می‌شود (به دلایل مشابه، addressComponents.shortText برای مؤلفه نشانی مربوط به بخش فرعی ممکن است با پسوند کد ISO 3166-2 بخش فرعی مطابقت نداشته باشد). علاوه‌براین، در برخی موارد ممکن است بخش فرعی در مؤلفه نشانی برای administrative_area_level_n با n بزرگ‌تر از ۱ نشان داده شود.
برای جامع‌ترین نتایج، باید در هر دو postalAddress.administrativeArea و هر addressComponents با نوع administrative_area_level_n (برای نمونه administrative_area_level_1) به‌دنبال مطابقت بگردید.
نمونه کد Python
def filter_by_admin_area(results, admin_area): target = admin_area.upper() filtered = [] for res in results: # Check postalAddress pa_aa = res.get('postalAddress', {}).get('administrativeArea', '') if pa_aa == target: filtered.append(res) continue # Check all administrative area levels in addressComponents for comp in res.get('addressComponents', []): is_admin_level = any(t.startswith('administrative_area_level_') for t in comp.get('types', [])) if is_admin_level: short = comp.get('shortText', '') if short == target: filtered.append(res) break return filtered # Example usage: # filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')
نمونه کد Node.js
function filterByAdminArea(results, adminArea) { const target = adminArea.toUpperCase(); return results.filter(res => { // Check postalAddress.administrativeArea if (res.postalAddress?.administrativeArea === target) { return true; } // Check addressComponents for any administrative area level return res.addressComponents?.some(c => { const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_')); return isAdmin && c.shortText === target; }); }); } // Example usage: // const filtered = filterByAdminArea(v4Response.results, 'CA');
فیلتر کردن براساس کد پستی
address.postalCode را از درخواستتان با postalAddress.postalCode در هر نتیجه مطابقت دهید. باید هم کد پستی ورودی و هم کد پستی نتیجه را قبل‌از مقایسه نرمال‌سازی کنید. منطق عادی‌سازی به‌شدت به منطقه وابسته است. یک رویکرد پایه شامل برداشتن فاصله‌ها و خط تیره‌ها و تبدیل به یک حالت ثابت است.
برای مدیریت پیشوندهای کد پستی (برای نمونه، «L2» در پادشاهی متحد) یا پسوندها (برای نمونه، «+۴» در کد پستی ایالات متحده)، ممکن است به عادی‌سازی پیشرفته‌تری نیاز باشد. منطق عادی‌سازی خاص موردنیاز بسته به کشور و قالب‌های کد پستی مربوطه متفاوت خواهد بود. ممکن است لازم باشد توابع عادی‌سازی ارائه‌شده را تطبیق دهید یا منطق پیچیده‌تری را برای مناطقی که هدف‌یابی می‌کنید پیاده‌سازی کنید.
نمونه ارائه‌شده کدهای پستی ایالات متحده را مدیریت می‌کند و امکان مطابقت دادن با کد ۵ رقمی پایه را فراهم می‌کند، حتی اگر کد پستی ۹ رقمی ارائه یا برگردانده شده باشد.
نمونه کد Python (با تمرکز بر کد پستی ایالات متحده)
import re def normalize_postal_code_us(pc): # Basic normalization for US: uppercase, alphanumeric only if not pc: return "" normalized = re.sub(r'[^A-Z0-9]', '', pc.upper()) # Return only the first 5 digits for US ZIP codes return normalized[:5] def filter_by_postal_code_us(results, postal_code): normalized_input = normalize_postal_code_us(postal_code) if not normalized_input: return [] filtered_results = [] for res in results: pa_pc = res.get('postalAddress', {}).get('postalCode', '') if normalize_postal_code_us(pa_pc) == normalized_input: filtered_results.append(res) return filtered_results # Example usage: # Matches '94043', '94043-1351', '940431351' # filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043') # filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')
نمونه کد Node.js (متمرکز بر کد پستی ایالات متحده)
function normalizePostalCodeUs(pc) { // Basic normalization for US: uppercase, alphanumeric only const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, ''); // Return only the first 5 digits for US ZIP codes return normalized.substring(0, 5); } function filterByPostalCodeUs(results, postalCode) { const normalizedInput = normalizePostalCodeUs(postalCode); if (!normalizedInput) { return []; } return results.filter(res => { const paPc = res.postalAddress?.postalCode || ''; return normalizePostalCodeUs(paPc) === normalizedInput; }); } // Example usage: // Matches '94043', '94043-1351', '940431351' // const filtered = filterByPostalCodeUs(v4Response.results, '94043'); // const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');
انتقال از «زمین‌کدیابی معکوس نسخه ۳»
اگر از زمین‌کدیابی معکوس نسخه ۳ برای تبدیل مختصات به نشانی استفاده می‌کنید، باید به روش زمین‌کدیابی معکوس مکان نسخه ۴ که درخواست GET را می‌پذیرد مهاجرت کنید.
v4 API نام‌ها، ساختار، و پشتیبانی از چندین پارامتر را تغییر می‌دهد. توصیه می‌کنیم از ماسک فیلد استفاده کنید تا فیلدهایی را که می‌خواهید در پاسخ برگردانده شود مشخص کنید.
درخواست کردن تغییرات پارامتر
| پارامتر v3 | پارامتر v4 | یادداشت‌ها |
|---|---|---|
language |
languageCode |
نام تغییر کرد. وقتی حذف شود، v3 از سرصفحه Accept-Language استفاده می‌کند یا به‌طور پیش‌فرض از en استفاده می‌کند، درحالی‌که v4 به‌طور پیش‌فرض از زبان و خط محلی مکان استفاده می‌کند. |
region |
regionCode |
نام تغییر کرد. وقتی حذف شود، v3 به‌طور پیش‌فرض روی us تنظیم می‌شود، درحالی‌که v4 مقدار پیش‌فرض ندارد. |
result_type |
types |
تغییر نام داده شد؛ از پارامترهای پُرسمان تکراری استفاده می‌کند. |
location_type |
granularity |
تغییر نام داده شد؛ از پارامترهای پُرسمان تکراری استفاده می‌کند. |
extra_computations |
برداشته شد | با روش SearchDestinations جایگزین شده است. |
تغییرات فیلد پاسخ
| فیلد v3 | فیلد v4 | یادداشت‌ها |
|---|---|---|
status، error_message |
برداشته شد | نسخه ۴ از کدهای وضعیت HTTP و متن‌های خطا استفاده می‌کند. |
results.address_components.long_name / results.address_components.short_name |
results.addressComponents.longText / results.addressComponents.shortText |
نام تغییر کرد. |
results.geometry.location_type |
results.granularity |
نام تغییر کرد. |
results.geometry.location |
results.location |
نام‌های فیلد: lat/lng -> latitude/longitude. |
results.geometry.viewport |
results.viewport |
نام فیلدها: northeast/southwest -> high/low. |
| جدید | results.addressComponents.languageCode |
زبان عنصر نشانی خاص. |
| جدید | results.bounds |
کران‌های صریح بااستفاده از high/low. |
| جدید | results.place |
نام منبع برای مکان. |
| جدید | results.postalAddress |
شیء ساختاریافته PostalAddress. |
انتقال از توصیف‌کننده‌های نشانی نسخه ۳
اگر از address_descriptor برای دریافت اطلاعات بیشتر درباره مکان با Geocoding نسخه ۳ استفاده می‌کنید، باید به استفاده از فیلد landmarks از SearchDestinationsResponse مهاجرت کنید.
انتقال از زمین‌کدیابی «مکان» نسخه ۳
اگر از place_id برای دریافت نشانی شناسه مکان خاصی با Geocoding
نسخه ۳ استفاده می‌کنید، باید به روش Place
Geocoding نسخه ۴ که
درخواست GET را می‌پذیرد مهاجرت کنید.
v4 API نام‌ها، ساختار، و پشتیبانی از چندین پارامتر را تغییر می‌دهد. توصیه می‌کنیم از ماسک فیلد استفاده کنید تا فیلدهایی را که می‌خواهید در پاسخ برگردانده شود مشخص کنید.
درخواست کردن تغییرات پارامتر
| پارامتر v3 | پارامتر v4 | یادداشت‌ها |
|---|---|---|
place_id |
فیلد place در پروتکل درخواست |
«شناسه مکان» اکنون به‌عنوان پارامتر مسیر places/{place} ارائه می‌شود، برای مثال: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. این مورد به فیلد مکان در درخواست زیرین نگاشت می‌شود. |
language |
languageCode |
نام تغییر کرد. وقتی حذف شود، v3 از سرصفحه Accept-Language استفاده می‌کند یا به‌طور پیش‌فرض از en استفاده می‌کند، درحالی‌که v4 به‌طور پیش‌فرض از زبان و خط محلی مکان استفاده می‌کند. |
region |
regionCode |
نام تغییر کرد. وقتی حذف شود، v3 به‌طور پیش‌فرض روی us قرار می‌گیرد، درحالی‌که v4 مقدار پیش‌فرض ندارد. |
تغییرات فیلد پاسخ
| فیلد v3 | فیلد v4 | یادداشت‌ها |
|---|---|---|
status، error_message |
برداشته شد | نسخه ۴ از کدهای وضعیت HTTP و متن‌های خطا استفاده می‌کند. |
results |
(root) | نسخه ۴ یک شیء نتیجه واحد برمی‌گرداند، نه آرایه results. |
results.address_components.long_name / results.address_components.short_name |
addressComponents.longText / addressComponents.shortText |
نام تغییر کرد. |
results.geometry.location_type |
granularity |
نام تغییر کرد. |
results.geometry.location |
location |
نام‌های فیلد: lat/lng -> latitude/longitude. |
results.geometry.viewport |
viewport |
نام فیلدها: northeast/southwest -> high/low. |
results.postcode_localities |
postalCodeLocalities |
نام تغییر کرد. اکنون برای یک یا چند محل برگردانده شده است (نسخه ۳ به بیشتر از ۱ نیاز دارد). |
| جدید | addressComponents.languageCode |
زبان عنصر نشانی خاص. |
| جدید | bounds |
کران‌های صریح بااستفاده از high/low. |
| جدید | place |
نام منبع برای مکان. |
| جدید | postalAddress |
شیء ساختاریافته PostalAddress. |
انتقال از «داده‌های فرامحلی زمین‌کدیابی» به «مقصدها»
ویژگی‌های زیر در Geocoding API v3 با روش SearchDestinations در Geocoding API v4 جایگزین می‌شود:
- ورودی‌ها
- نقاط پیمایش
- طرح‌های ساختمان
- محوطه
اگر از Geocoding API v3 برای ویژگی‌های بالا استفاده می‌کردید، از این سند برای کمک به استفاده از روش SearchDestinations به‌جای آن برای دریافت این ویژگی‌ها استفاده کنید.
این سند توضیح می‌دهد که این ویژگی‌ها را در کجای پاسخ SearchDestinations پیدا کنید و تفاوت‌های نحوه نمایش این ویژگی‌ها در پاسخ‌های میانای برنامه‌سازی کاربردی بین Geocoding API v3 و روش SearchDestinations Geocoding API v4 را شرح می‌دهد.
ورودی‌ها
برای دریافت ورودی‌های مرتبط با
destination،
از فیلد destination.entrances استفاده کنید.
توجه داشته باشید که قالب
entrance
کمی با قالب ورودی در Geocoding API
نسخه ۳ متفاوت است. هر ورودی
در destination.entrances فیلدهای زیر را دارد:
displayName- این فیلد اختیاری جدیدی است که نامی قابل‌خواندن برای انسان برای ورودی خواهد داشت، برای مثال «دروازه ب».-
location- این مکان از نوعLatLngاست، که با قالب استفاده‌شده در Geocoding API v3 متفاوت است. tags- این همان فیلدtagsورودی‌های Geocoding API v3 است.place- مشابه فیلدbuildingPlaceIdورودی‌ها از Geocoding API v3. بااین‌حال، «شناسه مکان» در این فیلد می‌تواند برای «مکان» از هر نوعی باشد، نه لزوماً فقط ساختمان.
نقطه‌های ناوبری
برای دریافت نقاط ناوبری مرتبط با destination، از فیلد
destination.navigationPoints استفاده کنید.
توجه داشته باشید که قالب
navigationPoint
کمی با قالب نقطه پیمایش در Geocoding API
نسخه ۳ متفاوت است. هر نقطه ناوبری در destination.navigationPoints فیلدهای زیر را دارد:
displayName- این فیلد اختیاری جدیدی است که نامی قابل‌خواندن برای انسان برای نقطه پیمایش خواهد داشت، برای مثال «خیابان پنجم».location- این مکان از نوعLatLngاست، که با قالب استفاده‌شده در Geocoding API v3 متفاوت است.travelModes- این مورد مشابه فیلدrestrictedTravelModesاز نقاط پیمایش در Geocoding API v3 است. مقادیر ممکن enum یکسان هستند، تنها تفاوت این است که این فیلد اکنون حالت‌های سفر قابل‌قبول برای نقطه ناوبری را نشان می‌دهد، نه حالت‌های سفر محدودشده.usage- این فیلد جدیدی است که حاوی موارد استفاده پشتیبانی‌شده توسط نقطه ناوبری است.
طرح‌های ساختمان
برای دریافت رئوس ساختمان‌های منسوب به destination، باید از فیلد
displayPolygon
placeView
در destination که ساختمان‌ها را نشان می‌دهد استفاده کنید. برای هر placeView، می‌توانید بااستفاده از فیلد placeView.structureType بررسی کنید که آیا ساختمان است یا نه. اگر نوع ساختار BUILDING باشد، می‌توانید طرح کلی را از فیلد placeView.displayPolygon دریافت کنید. placeView همچنین فیلدهای اضافی برای ساختمان خواهد داشت که در Geocoding API v3 وجود نداشت.
destination می‌تواند شیء placeView داشته باشد که نشان‌دهنده ساختمان در فیلدهای زیر است:
destination.primary- این مکان اصلی برای مقصد است.destination.containingPlaces- این فیلد تکراری است که می‌تواند مکان‌های بزرگ‌تری را که مکان اصلی را «دربرمی‌گیرند» نگه دارد. برای مثال، اگر مکان اصلیsubpremiseباشد،containingPlacesمعمولاًplaceViewنشان‌دهنده ساختمان را نگه می‌دارد.destination.subDestinations- این فیلد تکراری است که می‌تواند زیرمقصدهای مکان اصلی را در خود جای دهد. برای مثال، واحدهای آپارتمانی مجزا در یک ساختمان. این فیلد معمولاًplaceViewندارد که نشان‌دهنده ساختمان باشد.
توجه داشته باشید که قالب placeView.displayPolygon با قالب طرح کلی ساختمان
در Geocoding API
نسخه ۳ مطابقت دارد، که قالب
GeoJSON بااستفاده از قالب RFC 7946 است.
محوطه
مشابه ساختن طرح کلی، برای دریافت دلایل مرتبط با destination، باید از فیلد displayPolygon اشیای placeView در destination که نشان‌دهنده دلایل هستند استفاده کنید. برای هر placeView، می‌توانید بااستفاده از فیلد placeView.structureType بررسی کنید که آیا زمین است یا نه. اگر نوع ساختار GROUNDS باشد، می‌توانید طرح کلی را از فیلد placeView.displayPolygon دریافت کنید. placeView همچنین فیلدهای اضافی برای زمین‌هایی خواهد داشت که در Geocoding API v3 نبودند.
destination می‌تواند شیء placeView داشته باشد که نشان‌دهنده محوطه در فیلدهای زیر است:
destination.primarydestination.containingPlacesdestination.subDestinations
توجه داشته باشید که قالب placeView.displayPolygon با قالب رئوس مطالب زمین
در Geocoding API v3 مطابقت دارد،
که قالب GeoJSON است و از قالب RFC 7946 استفاده می‌کند.
دقت نتایج
در Geocoding API v3، فیلد location_type در هندسه پاسخ
دقت نتایج را نشان می‌داد و برخی‌از مشتریان نتایج را براساس این مقادیر (ROOFTOP، RANGE_INTERPOLATED،
GEOMETRIC_CENTER، و APPROXIMATE) رتبه‌بندی یا فیلتر می‌کردند. در انتقال‌های استاندارد Geocoding API v4،
نام این فیلد به granularity تغییر کرده است.
در «میانای برنامه‌سازی کاربردی مقصدها» (نسخه ۴ SearchDestinations)، فیلد location_type
وجود ندارد. درعوض، اطلاعات فضایی به روش دیگری مدیریت می‌شود:
- بدون نیاز به فیلتر کردن دستی در سمت مشتری: درحالی‌که «مکان‌گذاری جغرافیایی» استاندارد
نتایج متعددی را در سطوح مختلف جزئیات ارائه می‌دهد،
روش
SearchDestinationsبا تبدیل به یک مقصد بهینه‌سازی‌شده واحد درصورت امکان، ابهام را به حداقل می‌رساند. این کار نیاز مشتریان را به فیلتر کردن براساس نوع مکان برای تعیین بهترین نتیجه برطرف می‌کند. - اطلاعات فضایی که با نوع ساختار و چندضلعی‌های نمایش نشان داده می‌شود:
هندسه و ساختار فضایی با موارد زیر نشان داده می‌شود:
-
displayPolygon(برای هندسه دقیق). - فیلد
structureTypeدر شیءplaceView.
-
- نگاشت نوع ساختار:
structureTypeازPOINT،BUILDING، یاSECTIONمعمولاً با آنچه قبلاًROOFTOPنامیده می‌شد مطابقت دارد.-
structureTypeازGROUNDSمعمولاً معادلGEOMETRIC_CENTERاست.
برای درخواست این ویژگی‌ها، از پوشش فیلد استفاده کنید
روش SearchDestinations به ماسک فیلد نیاز دارد، همان‌طور که در انتخاب فیلدها برای برگرداندن توضیح داده شده است. پوشش فیلد را می‌توان روی * تنظیم کرد تا همه فیلدها برگردانده شود، یا می‌توانید آن را روی فیلدهای خاصی که می‌خواهید دریافت کنید تنظیم کنید. برای مثال، درخواست API زیر ماسک فیلد را تنظیم می‌کند تا همه فیلدهای لازم برای دریافت ورودی‌ها، نقاط پیمایش، طرح‌های کلی ساختمان، و زمین‌های مقصد را دریافت کند:
curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
-H "X-Goog-Api-Key: API_KEY" \
-H "Content-Type: application/json" \
-H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
https://geocode.googleapis.com/v4/geocode/destinations
ملاحظات امنیتی
Geocoding API v4 به‌عنوان یک میانای برنامه‌سازی کاربردی سروربه‌سرور طراحی شده است. مسیر انتقال مستقیم برای کاربران جاوا اسکریپت از نسخه ۳ به نسخه ۴ وجود ندارد. فراخوانی روش‌های v4 مستقیماً از جاوا اسکریپت سمت کارخواه (برای مثال، در مرورگر) بااستفاده از کلید میانای برنامه‌سازی کاربردی، کلید میانای برنامه‌سازی کاربردی شما را درمعرض خطر بالای سرقت و سوءاستفاده قرار می‌دهد.
محدودیت‌های ارجاع‌دهنده HTTP، اگرچه مفید هستند، اما محافظت کافی برای نقاط پایانی سرویس وب نیستند زیرا مهاجمانی که سرصفحه Referer را در درخواست‌های خود جعل می‌کنند، می‌توانند به‌راحتی از آن‌ها عبور کنند.
رویکرد توصیه‌شده
روش توصیه‌شده برای استفاده از Geocoding API v4 از سرور زیرینه خودتان است. برنامه کارخواه شما باید درخواست‌ها را به این سرور واسطه ارسال کند، که سپس بااستفاده از کلید میانای برنامه‌سازی کاربردی محافظت‌شده (برای مثال، کلیدی که در متغیر محیطی یا مدیر مخفی ذخیره شده است) به‌طور ایمن با Google API تماس می‌گیرد. این کار تضمین می‌کند که کلید API شما هرگز در کد نمای جلویی فاش نشود.
جایگزین‌هایی برای نیازهای سمت کارخواه
اگر نیازهای سمت کارخواه دارید که به زمین‌کدیابی نیاز دارند، از یکی از راه‌حل‌های موجود سمت کارخواه استفاده کنید:
- Geocoding Service در Maps JavaScript API: Geocoding Service همچنان از باطن نسخه ۳ استفاده می‌کند و برای استفاده در محیط مرورگر طراحی شده است.
- کیت میانای کاربر «جاها»: برای عناصر میانای کاربر مرتبط با نشانی، از کیت میانای کاربر «جاها»، ازجمله عناصر «تکمیل خودکار جا»، استفاده کنید.