روال‌های مطلوب Isochrones API

صاف کردن و وفاداری

بااستفاده از پارامترهای polygon_fidelity و enable_smoothing می‌توانید ظاهر و دقت چندضلعی‌های خروجی را سفارشی‌سازی کنید. اگرچه این گزینه‌ها مستقل هستند، اما باهم کار می‌کنند تا شکل نهایی را تعیین کنند.

• polygonFidelity (polygon_fidelity): وضوح. اندازه سلول‌های شبکه فضایی زیرین را که برای محاسبه منطقه قابل‌دسترس استفاده می‌شود کنترل می‌کند.

  • LOW: از بزرگ‌ترین سلول‌های جدولی (با پهنای چندصد متر) استفاده می‌کند. بهترین گزینه برای پوشش دادن مناطق بزرگ بدون شکاف و به‌حداقل رساندن تعداد رأس‌ها، که منجر به شکل تعمیم‌یافته‌ای می‌شود که می‌تواند منطقه قابل‌دسترس را درطول راهروهای باریک جاده بیش‌ازحد تخمین بزند.
  • MEDIUM: دقت و اندازه بار مفید متعادل.
  • HIGH: از کوچک‌ترین سلول‌های شبکه‌ای (تقریباً ۱۰۰ تا ۱۵۰ متر عرض) استفاده می‌کند. نتایج در تناسب دقیق‌تر با شبکه جاده‌ای، با رئوس بیشتر، اما ممکن است سوراخ‌های داخلی ایجاد کند که شبکه جاده‌ای پراکنده است.
  • پیش‌فرض (POLYGON_FIDELITY_UNSPECIFIED): اگر مشخص نشده باشد، سرویس به‌طور خودکار وضوح را براساس حالت سفر و مدت‌زمان انتخاب می‌کند، و از سلول‌های ریزتر برای مدت‌زمان‌های کوتاه و برای WALK، و از سلول‌های درشت‌تر برای مدت‌زمان‌های طولانی استفاده می‌کند. برای مقایسه هم‌زمان‌ها در مدت‌ها یا حالت‌های سفر مختلف، polygonFidelity را به‌طور صریح تنظیم کنید تا از وضوح یکسانی استفاده کنند.

  اندازه سلول‌ها تقریبی است. هم‌زمان‌های بسیار بزرگ ممکن است بیشتر تعمیم داده شوند تا اندازه پاسخ قابل‌مدیریت باقی بماند.

نکته: کاهش حفره‌ها در چندضلعی‌ها
ازآنجاکه هم‌زمان‌ها دسترسی‌پذیری را بااستفاده از شبکه جاده‌ای واقعی محاسبه می‌کنند، مناطقی با جاده‌های پراکنده، مانند پارک‌های بزرگ، مناطق خصوصی نقشه‌برداری‌نشده، یا مناطق صنعتی، می‌توانند به‌طور طبیعی به‌عنوان «حفره‌های» غیرقابل‌دسترس در داخل چندضلعی تولیدشده ظاهر شوند. اگر مورد استفاده شما به منطقه تحت پوشش یکپارچه و تعمیم‌یافته بدون این فاصله‌ها نیاز دارد، صریحاً polygonFidelity را روی MEDIUM یا LOW تنظیم کنید.

• enableSmoothing (enable_smoothing): زیبایی‌شناسی. کنترل می‌کند که آیا لبه‌های پله‌ای سلول‌های جدول که با دقت تعریف شده‌اند گرد شوند یا نه.
  • false (خام): مرز تراز جدولی را برمی‌گرداند. لبه‌ها دندانه‌دار یا پله‌ای به‌نظر می‌رسند که نشان‌دهنده سلول‌های جدولی است. بهترین گزینه برای دقت تحلیلی، مانند آزمایش‌های دقیق نقطه در چندضلعی.
  • true (هموارشده): گوشه‌ها را گرد می‌کند و درعین‌حال مساحت هر حلقه را تقریباً حفظ می‌کند. بهترین گزینه برای نمایش دیداری روی نقشه‌ها. چون مرز دیگر از سلول‌های شبکه پیروی نمی‌کند، از آن برای آزمایش‌های دقیق نقطه در چندضلعی استفاده نکنید.

نحوه تعامل آن‌ها: «وفاداری» جزئیات خط مبنا را تنظیم می‌کند که الگوریتم هموارسازی براساس آن عمل می‌کند.

• وفاداری بالا + هموارسازی: شکلی دقیق و طبیعی تولید می‌کند که به‌دقت انتهای جاده‌ها را دنبال می‌کند.
• وفاداری پایین + هموارسازی: شکلی پهن و کلی به‌صورت «حباب» تولید می‌کند.

اندازه بار و پردازش

هم‌زمان‌های بزرگ (به‌ویژه درخواست‌های طولانی‌مدت با وفاداری HIGH) می‌توانند حاوی ده‌ها هزار مختصات باشند و پاسخ JSON فشرده‌نشده می‌تواند چند صد کیلوبایت یا بیشتر باشد.

• پهنای باند: توجه داشته باشید که اندازه پاسخ JSON برای درخواست‌های حداکثر مدت با وفاداری بالا قابل‌توجه است.
• پرداز زدن: پرداز زدن چندضلعی‌های بسیار دقیق بر عملکرد کارخواه تأثیر می‌گذارد. برای کاهش تعداد رأس‌ها و اندازه بار، polygonFidelity: MEDIUM یا LOW را انتخاب کنید، یا هندسه را در کارخواه قبل‌از ارائه بااستفاده از الگوریتم ساده‌سازی خط مانند Douglas-Peucker ساده کنید.

تأخیر و اتمام مهلت کارخواه

تأخیر پاسخ با اندازه شبکه جاده‌ای پیموده‌شده افزایش می‌یابد: مدت‌های کوتاه و حالت‌های WALK و BICYCLE سریع‌ترین هستند، درحالی‌که درخواست‌های طولانی DRIVE و TWO_WHEELER (به‌ویژه با TRAFFIC_AWARE) بیشترین زمان را می‌برند.

• زمان اتمام کارخواه توصیه‌شده: مهلت‌های کارخواه HTTP یا gRPC را حداقل روی ۳۰ ثانیه پیکربندی کنید تا درخواست‌های طولانی به‌دلیل زمان اتمام کوتاه کارخواه زودتر از موعد لغو نشوند.

مدیریت کردن خطا

منطق امتحان مجدد را با عقب‌نشینی نمایی و لرزش برای پاسخ‌های محدودیت نرخ 429 RESOURCE_EXHAUSTED و خطاهای سرور 5xx پیاده‌سازی کنید. خطاهای کارخواه 400، 403، یا 404 را بدون تغییر درخواستتان دوباره امتحان نکنید:

• INVALID_ARGUMENT (400): بررسی کنید که travelDuration بین 1s و 3600s (DRIVE/TWO_WHEELER) یا 7200s (WALK/BICYCLE) باشد، location حذف نشده باشد و (0, 0) نباشد (یا place شناسه مکان معتبری باشد)، و TRAFFIC_AWARE فقط با DRIVE یا TWO_WHEELER استفاده شود. latitude یا longitude حذف‌شده به‌عنوان 0.0 درنظر گرفته می‌شود، بنابراین حذف کردن فقط یکی از آن‌ها معمولاً باعث خطای 400 نمی‌شود (مگر اینکه مقدار دیگر نیز 0.0 باشد). اگر هم‌زمان در مکان اشتباهی ظاهر شد، هر دو مقدار را دوباره بررسی کنید.
• PERMISSION_DENIED (403): مطمئن شوید کلید میانای برنامه‌سازی کاربردی یا کد OAuth شما گنجانده شده باشد و Isochrones API و صورت‌حساب در پروژه Google Cloud شما فعال باشد.
• ‫NOT_FOUND (404): place به مکان تبدیل نشد، یا مبدأ به جاده‌ای نزدیک که برای حالت سفر قابل‌استفاده باشد (در حدود ۲۰۰ متر، یا کمتر برای WALK و BICYCLE) متصل نشد.
• ‫RESOURCE_EXHAUSTED (429): پروژه شما از سهمیه درخواست در دقیقه (به‌طور پیش‌فرض ۳۰۰ درخواست در دقیقه) فراتر رفته است. با عقب‌گرد نمایی دوباره امتحان کنید.