SpatialKey accepts many vector formats (Shapefile, GeoJSON, KML, GPKG, and more), but all are converted to Shapefile during import. Preparing your data as simple, single‑type 2D geometry ensures clean conversion and reliable performance. The sections that follow provide detailed tips to help you prepare your dataset effectively.
Use a Supported Coordinate System
Shapefiles work best when your vector data is stored in a commonly used geographic coordinate system. For maximum compatibility, reproject your dataset to WGS84 (EPSG:4326) before import. Avoid obscure or unsupported projections because these may cause your data to appear in the wrong location or fail during conversion.
Prepare Attribute Fields for Shapefile Compatibility
Keep Attribute Names Simple: Shapefiles have strict limits on field names, so simplify your attribute names before import. Use names that are short (10 characters or fewer) and avoid spaces, special characters, or complex JSON structures that may appear in formats such as GeoJSON. Clean, simple field names prevent truncation and ensure attributes load correctly.
Limit Attribute Size and Complexity: Shapefile attribute fields allow only limited text lengths and basic numeric formats. If your input format contains long text fields or nested structures, trim or restructure them before import. This helps ensure the converted Shapefile displays your data correctly.
Prepare and Clean Geometry
Use Simple and Consistent Geometry Types: Many vector formats support mixed or complex geometry types such as geometry collections, multipolygons, splines (curved line features), or 3D coordinates. Shapefiles only support one geometry type per file. Convert your data to simple 2D geometry and avoid mixing points, lines, and polygons in a single dataset. Flatten or split multi-geometry features as needed.
Geometry types that should be converted or simplified
- Curved features such as arcs, splines, and Bezier curves. Convert these to straight polylines.
- 3D geometry including Z or M values, 3D polylines, meshes, and surfaces. Flatten these to 2D points, lines, or polygons.
- TINs or surface models (common in engineering or terrain‑related datasets). Convert these to 2D polygons or polylines if needed.
- Topology-based formats, including TopoJSON, which rely on shared arcs and topology structures that Shapefiles do not support. Convert these to standard GeoJSON or directly to 2D polygons or polylines before import.
- Annotation or symbolic geometry that represents labels, markers, or other non‑spatial objects. Convert to simple point features or remove them if they are not needed.
- Mixed geometry files containing points, lines, and polygons together. Split them into separate layers so each dataset contains only one geometry type.
Validate and Clean Up Geometry: Before importing, run your data through a geometry validation or repair tool. Fixing issues such as self-intersections, null geometries, invalid rings, or unclosed polygons helps prevent conversion errors and ensures SpatialKey can render your shapes correctly.
Reduce Excessive Vertices: Very dense shapes—such as boundaries with thousands of vertices—can slow rendering and create large files. Simplify your geometry where possible while maintaining the overall shape. Simplified data imports faster and performs better.
Watch File Size and Complexity: File size alone does not determine whether a vector dataset will perform well. Geometry density and spatial distribution matter more. Datasets with extremely detailed shapes—or individual features containing more than 20,000 vertices, which is the maximum supported per geometry—may fail to import or render slowly. When working with highly complex features, simplify the geometry or split the dataset into smaller geographic areas to ensure smooth conversion and efficient performance.
Special Considerations
Special handling for KML: KML description attributes, and all other attributes from KML, are truncated to the first 255 characters during import and will render as raw HTML. This means tags such as <b>, <br>, or <i> may appear in the field instead of being formatted. If you rely on longer descriptions or need plain text, consider pre-processing these fields before import.
Geodatabase Considerations: A ZIP file that contains multiple file geodatabases may not upload correctly because geodatabases are actually folders, and ZIP uploads do not always preserve folder structures reliably. To avoid problems, include only one geodatabase per ZIP file, or export the layer you need to a standalone format such as Shapefile or GeoPackage before uploading.
Was this helpful?