قبل‌از شروع

این سند پیش‌نیازها، روال‌های مطلوب، و خطاهای رایج هنگام کار با مجموعه‌داده‌ها را شرح می‌دهد.

پیش‌نیازها

هنگام ایجاد مجموعه داده:

• نام‌های نمایشی باید در پروژه Google Cloud شما یکتا باشند.
• نام نمایشی باید کمتر از ۶۴ بایت باشد (چون این نویسه‌ها در UTF-8 نمایش داده می‌شوند، در برخی زبان‌ها هر نویسه می‌تواند با چند بایت نمایش داده شود).
• شرح‌ها باید کمتر از ۱۰۰۰ بایت باشد.

هنگام بارگذاری داده‌ها:

• انواع فایل‌های پشتیبانی‌شده عبارت‌اند از CSV،‏ GeoJSON، و KML.
• حداکثر اندازه فایل پشتیبانی‌شده ۵۰۰ مگابایت است.
• نام ستون مشخصه نمی‌تواند با رشته «?_» شروع شود.
• هندسه‌های سه‌بعدی پشتیبانی نمی‌شوند. این شامل پسوند «Z» در قالب WKT، و مختصات ارتفاع در قالب GeoJSON می‌شود.

روال‌های مطلوب آماده‌سازی داده‌ها

اگر داده‌های منبع شما پیچیده یا بزرگ است، مانند نقاط متراکم، رشته‌های خطی طولانی یا چندضلعی‌ها (اغلب اندازه‌های فایل منبع بزرگ‌تر از ۵۰ مگابایت در این دسته قرار می‌گیرند)، ساده‌سازی داده‌های خود را قبل از بارگذاری برای دستیابی به بهترین عملکرد در نقشه بصری در نظر بگیرید.

در اینجا برخی‌از روال‌های مطلوب برای آماده‌سازی داده‌هایتان آورده شده است:

1. ویژگی‌های عارضه را کوچک کنید. فقط ویژگی‌های عارضه‌ای را که برای سبک‌بندی نقشه‌تان لازم است نگه دارید، برای مثال «شناسه» و «دسته». می‌توانید بااستفاده از سبک‌های داده‌محور در کلید شناسه یکتا، ویژگی‌های بیشتری را به عارضه‌ای در برنامه کارخواه اضافه کنید. برای مثال، دیدن داده‌ها به‌طور هم‌زمان با «سبک‌بندی داده‌محور» را ببینید.
2. درصورت امکان، برای اشیای ویژگی از انواع داده‌های ساده استفاده کنید، مانند اعداد صحیح، تا اندازه کاشی را به‌حداقل برسانید و عملکرد نقشه را بهبود بخشید.
3. پیش‌از بارگذاری فایل، هندسه‌های پیچیده را ساده کنید. می‌توانید این کار را در ابزار جغرافیایی-فضایی دلخواهتان، مثل ابزار کمکی متن‌باز Mapshaper.org، یا در BigQuery بااستفاده از ST_Simplify روی هندسه‌های چندضلعی پیچیده انجام دهید.
4. پیش‌از بارگذاری فایل، نقاط بسیار متراکم را خوشه‌بندی کنید. می‌توانید این کار را در ابزار جغرافیایی-فضایی انتخابی‌تان، مثل توابع خوشه‌ای turf.js متن‌باز، یا در BigQuery بااستفاده از ST_CLUSTERDBSCAN روی هندسه‌های نقطه‌ای متراکم انجام دهید.

برای راهنمایی بیشتر درباره روال‌های مطلوب مجموعه‌داده‌ها، به دیداری‌سازی داده‌ها با «مجموعه‌داده‌ها» و BigQuery مراجعه کنید.

الزامات GeoJSON

Maps Datasets API از مشخصات GeoJSON فعلی پشتیبانی می‌کند. Maps Datasets API از فایل‌های GeoJSON که حاوی هرکدام از انواع شیء زیر باشند نیز پشتیبانی می‌کند:

• اشیاء هندسی. شیء هندسی شکلی فضایی است که به‌عنوان اتحادی از نقاط، خطوط، و چندضلعی‌ها با سوراخ‌های اختیاری توصیف می‌شود.
• اشیاء ویژگی. یک شیء عارضه حاوی یک هندسه به‌علاوه جفت‌های نام/مقدار اضافی است که معنی آن مختص برنامه است.
• مجموعه‌های ویژه. مجموعه عارضه مجموعه‌ای از اشیای عارضه است.

Maps Datasets API از فایل‌های GeoJSON که داده‌هایشان در سیستم مرجع مختصات (CRS) دیگری به‌غیراز WGS84 است پشتیبانی نمی‌کند.

برای اطلاعات بیشتر درباره GeoJSON، به مطابق با RFC 7946 مراجعه کنید.

الزامات KML

Maps Datasets API الزامات زیر را دارد:

• همه نشانی‌های وب باید محلی (یا مرتبط) با خود فایل باشند.
• از هندسه‌های نقطه‌ای، خطی، و چندضلعی پشتیبانی می‌شود.
• همه مشخصه‌های داده رشته درنظر گرفته می‌شوند.

از ویژگی‌های KML زیر پشتیبانی نمی‌شود:

• نمادها یا <styleUrl> خارج از فایل تعریف شده‌اند.
• پیوندهای شبکه، مثل <NetworkLink>
• رونهادهای زمین، مثل <GroundOverlay>
• هندسه‌های سه‌بعدی یا هر برچسب مرتبط با ارتفاع مانند <altitudeMode>
• مشخصات دوربین مانند <LookAt>
• سبک‌های تعریف‌شده در فایل KML.

الزامات CSV

برای فایل‌های CSV، نام‌های ستون پشتیبانی‌شده به‌ترتیب اولویت در زیر فهرست شده‌اند:

• latitude، longitude
• lat، long
• x، y
• wkt (Well-Known Text)
• address،‏ city،‏ state،‏ zip
• address
• یک ستون حاوی همه اطلاعات نشانی، مثل 1600 Amphitheatre Parkway Mountain View, CA 94043

برای مثال، فایل شما حاوی ستون‌هایی با نام x، y، و wkt است. چون x و y اولویت بالاتری دارند، همان‌طور که با ترتیب نام‌های ستون پشتیبانی‌شده در فهرست بالا تعیین شده است، از مقادیر ستون‌های x و y استفاده می‌شود و ستون wkt نادیده گرفته می‌شود.

علاوه‌براین:

• هر نام ستون باید به یک ستون تکی تعلق داشته باشد. یعنی نمی‌توانید ستونی به‌نام xy داشته باشید که حاوی داده‌های مختصات x و y باشد. مختصات x و y باید در ستون‌های جداگانه باشد.
• نام ستون‌ها حروف‌حساس نیست.
• ترتیب نام ستون‌ها اهمیتی ندارد. برای مثال، اگر فایل CSV شما حاوی ستون‌های lat و long باشد، این ستون‌ها می‌توانند به هر ترتیبی قرار بگیرند.

رسیدگی به خطاهای بارگذاری داده

هنگام بارگذاری داده‌ها در مجموعه داده، ممکن است یکی از خطاهای رایج شرح داده‌شده در این بخش را تجربه کنید.

خطاهای GeoJSON

خطاهای رایج GeoJSON شامل موارد زیر است:

• فیلد type وجود ندارد یا type رشته نیست. فایل داده GeoJSON بارگذاری‌شده باید حاوی فیلد رشته‌ای به‌نام type به‌عنوان بخشی از هر تعریف شیء Feature و شیء Geometry باشد.

خطاهای KML

خطاهای رایج KML شامل موارد زیر است:

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

خطاهای CSV

خطاهای رایج CSV شامل موارد زیر است:

• برخی‌از ردیف‌ها فاقد مقادیر ستون هندسی هستند. همه ردیف‌ها در فایل CSV باید حاوی مقادیر غیرخالی برای ستون‌های هندسی باشند. ستون‌های هندسی شامل موارد زیر است:
  • latitude، longitude
  • lat، long
  • x، y
  • wkt
  • address،‏ city،‏ state،‏ zip
  • address
  • یک ستون حاوی همه اطلاعات نشانی، مثل 1600 Amphitheatre Parkway Mountain View, CA 94043
• اگر x و y ستون‌های هندسی شما هستند، مطمئن شوید که واحدها طول و عرض جغرافیایی باشند. برخی‌از مجموعه‌های داده عمومی از سیستم‌های مختصات متفاوتی تحت سرصفحه‌های x و y استفاده می‌کنند. اگر از واحدهای نادرست استفاده شود، ممکن است مجموعه داده با موفقیت وارد شود، اما داده‌های ارائه‌شده ممکن است نقاط مجموعه داده را در مکان‌های غیرمنتظره نشان دهد.