قبل البدء

يصف هذا المستند المتطلبات الأساسية وأفضل الممارسات والأخطاء الشائعة عند العمل مع مجموعات البيانات.

المتطلبات الأساسية

عند إنشاء مجموعة بيانات:

  • يجب أن تكون الأسماء المعروضة فريدة ضمن مشروعك على Google Cloud.
  • يجب أن يقلّ عدد بايتات الأسماء المعروضة عن 64 بايتًا (لأنّ هذه الأحرف ممثّلة في UTF-8، في بعض اللغات، يمكن تمثيل كل حرف بعدة بايتات).
  • يجب أن يكون حجم الأوصاف أقل من 1000 بايت.

عند تحميل البيانات:

  • أنواع الملفات المتوافقة هي CSV وGeoJSON وKML.
  • الحد الأقصى لحجم الملف المسموح به هو 500 ميغابايت.
  • لا يمكن أن تبدأ أسماء أعمدة السمات بالسلسلة "?_".
  • لا تتوافق مع الأشكال الهندسية الثلاثية الأبعاد. ويشمل ذلك اللاحقة "Z" في تنسيق WKT، وإحداثيات الارتفاع في تنسيق GeoJSON.

أفضل الممارسات المتعلّقة بإعداد البيانات

إذا كانت بيانات المصدر معقّدة أو كبيرة، مثل النقاط الكثيفة أو السلاسل الخطية الطويلة أو المضلّعات (غالبًا ما تندرج أحجام ملفات المصدر التي تزيد عن 50 ميغابايت ضمن هذه الفئة)، ننصحك بتبسيط بياناتك قبل تحميلها لتحقيق أفضل أداء في خريطة مرئية.

في ما يلي بعض أفضل الممارسات لإعداد بياناتك:

  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 المتطلبات التالية:

  • يجب أن تكون جميع عناوين URL محلية (أو نسبية) بالنسبة إلى الملف نفسه.
  • تتوفّر أشكال هندسية للنقاط والخطوط والمضلّعات.
  • تُعتبر جميع سمات البيانات سلاسل.
ميزات 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. في حال استخدام وحدات خاطئة، قد يتم استيراد مجموعة البيانات بنجاح، ولكن قد تعرض البيانات المعروضة نقاط مجموعة البيانات في مواقع جغرافية غير متوقّعة.