# Vector Data Import

Import vector spatial data from files or URLs.

## Overview

Vector data import supports multiple file formats and import methods for point, line, and polygon data.

## Supported Formats

### GeoJSON

- **Extension**: `.geojson`, `.json`
- **Description**: GeoJSON Feature Collections
- **Features**: Full support for all geometry types and properties

### Shapefile

- **Extension**: `.shp`, `.zip` (containing shapefile components)
- **Description**: ESRI Shapefile format
- **Requirements**: ZIP archive must contain `.shp`, `.shx`, `.dbf` files
- **Note**: `.prj` file recommended for proper coordinate system

### KML

- **Extension**: `.kml`
- **Description**: Google Earth KML format
- **Features**: Supports placemarks, paths, and polygons

### CSV

- **Extension**: `.csv`
- **Description**: Comma-separated values with coordinates
- **Requirements**: Must have coordinate columns (lat/lon or x/y)
- **Features**: Automatic column detection

### GeoPackage

- **Extension**: `.gpkg`
- **Description**: OGC GeoPackage format
- **Features**: Supports multiple layers and raster data

### DXF

- **Extension**: `.dxf`
- **Description**: AutoCAD DXF format
- **Features**: Supports CAD drawings and annotations

### PBF

- **Extension**: `.pbf`
- **Description**: OpenStreetMap Protocol Buffer Format
- **Requirements**: `osm2pgsql` must be installed
- **Features**: High-performance OSM data import

## Import Methods

### File Upload

Upload files directly from your computer:

1. Navigate to upload page
2. Select file or drag and drop
3. Add optional description
4. Select target SRS (default: EPSG:4326)
5. Click "Upload"

**File Size Limit**: 50MB (configurable)

### URL Import

Import from web-accessible URLs:

1. Navigate to URL import page
2. Enter data URL
3. Configure import options
4. Optionally schedule import
5. Click "Import"

**Supported URL Types**:
- Direct file URLs
- GeoJSON service endpoints
- ArcGIS REST services
- WFS endpoints

### Scheduled Import

Set up recurring imports from URLs:

1. Configure URL import
2. Set schedule (daily, weekly, monthly)
3. Configure update mode (replace, append, upsert)
4. Save schedule

## Import Process

### Step 1: File Detection

The system automatically detects file type based on:
- File extension
- File content (for ambiguous extensions)
- ZIP archive contents

### Step 2: Metadata Extraction

Metadata is extracted including:
- Feature count
- Geometry types
- Bounding box
- Coordinate system
- Attribute fields

### Step 3: Data Processing

Data is processed based on file type:
- **GeoJSON**: Direct parsing and import
- **Shapefile**: Extraction from ZIP, coordinate transformation
- **CSV**: Coordinate column detection, geometry creation
- **KML**: Placemark and geometry extraction
- **PBF**: OSM data processing via osm2pgsql

### Step 4: PostGIS Import

Processed data is imported into PostGIS:
- Table creation: `spatial_data_{file_id}`
- Geometry conversion to PostGIS format
- Spatial index creation
- Attribute storage in JSONB

### Step 5: Registration

Dataset is registered in the system:
- Metadata stored in `spatial_files` table
- Access permissions set
- Version record created

## Configuration Options

### Target SRS

Select target spatial reference system:
- **EPSG:4326** (WGS84): Default, global coverage
- **EPSG:3857** (Web Mercator): Web mapping standard
- **Other**: Any valid EPSG code

### Update Mode

For scheduled imports:
- **Replace**: Replace all existing data
- **Append**: Add new data to existing
- **Upsert**: Update existing, insert new (requires key columns)

### Filters

Apply filters during import:
- **Spatial Filter**: Bounding box or geometry
- **Attribute Filter**: SQL WHERE clause
- **Feature Limit**: Maximum number of features

## Example: GeoJSON Import

```bash
# Via API
curl -X POST "https://example.com/upload.php" \
  -F "spatial_file=@data.geojson" \
  -F "description=Sample dataset" \
  -F "targetSRS=EPSG:4326"
```

## Example: URL Import

```bash
# Via API
curl -X POST "https://example.com/import_url.php" \
  -d "url=https://example.com/data.geojson" \
  -d "description=Imported from URL" \
  -d "targetSRS=EPSG:4326"
```

## Troubleshooting

### Common Issues

**File too large**
- Check file size limit configuration
- Consider splitting large files
- Use URL import for very large files

**Invalid geometry**
- Verify coordinate system
- Check for invalid geometries in source
- Use geometry validation tools

**Missing coordinate system**
- Ensure `.prj` file included for shapefiles
- Specify target SRS manually
- Check source data metadata

**Import timeout**
- Increase PHP execution time limit
- Use background import for large files
- Consider chunked upload for very large files

## Related Documentation

- [Raster Import](raster.md)
- [PostGIS Import](postgis.md)
- [ESRI Import](esri.md)
- [Installation Guide](../installation.md)