לפני שמתחילים

במסמך הזה מפורטים התנאים המוקדמים, השיטות המומלצות והשגיאות הנפוצות שקשורות לעבודה עם מערכי נתונים.

דרישות מוקדמות

כשיוצרים מערך נתונים:

  • השמות לתצוגה צריכים להיות ייחודיים בפרויקט Google Cloud.
  • השמות המוצגים צריכים להיות באורך של פחות מ-64 בייט (מכיוון שהתווים האלה מיוצגים ב-UTF-8, בשפות מסוימות כל תו יכול להיות מיוצג על ידי כמה בייטים).
  • התיאורים צריכים להיות באורך של עד 1,000 בייט.

כשמעלים נתונים:

  • סוגי הקבצים הנתמכים הם CSV,‏ GeoJSON ו-KML.
  • הגודל המקסימלי של קובץ שנתמך הוא 500MB.
  • שמות של עמודות מאפיינים לא יכולים להתחיל במחרוזת '?_'.
  • אין תמיכה בגיאומטריות תלת-ממדיות. כולל הסיומת 'Z' בפורמט WKT, ואת קואורדינטת הגובה בפורמט GeoJSON.

שיטות מומלצות להכנת נתונים

אם נתוני המקור שלכם מורכבים או גדולים, למשל נקודות צפופות, קווים ארוכים או מצולעים (לרוב קבצים בגודל של יותר מ-50MB נכללים בקטגוריה הזו), מומלץ לפשט את הנתונים לפני ההעלאה כדי להשיג את הביצועים הטובים ביותר במפה חזותית.

ריכזנו כאן כמה שיטות מומלצות להכנת הנתונים:

  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. אם משתמשים ביחידות שגויות, יכול להיות שמערך הנתונים ייווה בהצלחה, אבל הנתונים המעובדים יציגו את הנקודות במערך הנתונים במיקומים לא צפויים.