AR1/docs/api/datasets.md

# Datasets API

Endpoints for managing and querying spatial datasets.

## List Datasets

**Endpoint**: `GET /api/datasets/list.php`

List all datasets accessible to the current user.

### Parameters

- `has_geometry` (optional): Filter datasets with geometry (0 or 1)

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "Sample Dataset",
      "original_name": "sample.geojson",
      "file_type": "geojson",
      "metadata": { ... }
    }
  ]
}
```

### Example

```bash
curl -X GET "https://example.com/api/datasets/list.php?has_geometry=1" \
  -H "Cookie: PHPSESSID=..."
```

## Get Dataset

**Endpoint**: `GET /api/datasets/get.php`

Get detailed information about a specific dataset.

### Parameters

- `id` (required): Dataset ID

### Response

```json
{
  "success": true,
  "data": {
    "id": 123,
    "name": "Sample Dataset",
    "original_name": "sample.geojson",
    "file_type": "geojson",
    "file_size": 1024000,
    "description": "Dataset description",
    "metadata": {
      "feature_count": 1000,
      "geometry_type": "Point",
      "bbox": [-180, -90, 180, 90]
    },
    "uploaded_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Example

```bash
curl -X GET "https://example.com/api/datasets/get.php?id=123" \
  -H "Cookie: PHPSESSID=..."
```

## Query Dataset

**Endpoint**: `GET /api/basic/index.php/datasets/{id}/query`

Query features from a dataset with filtering and pagination.

### Parameters

- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 100, max: 1000)
- `bbox` (optional): Bounding box filter (minX,minY,maxX,maxY)
- `properties` (optional): Property filters (JSON object)
- `geometry_type` (optional): Filter by geometry type

### Response

```json
{
  "success": true,
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "id": 1,
        "properties": { ... },
        "geometry": { ... }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 100,
      "total": 1000,
      "pages": 10
    }
  }
}
```

### Example

```bash
curl -X GET "https://example.com/api/basic/index.php/datasets/123/query?page=1&limit=50&bbox=-180,-90,180,90" \
  -H "Cookie: PHPSESSID=..."
```

## Get Dataset Properties

**Endpoint**: `GET /api/datasets/get_properties.php`

Get all unique property keys from a dataset.

### Parameters

- `id` (required): Dataset ID

### Response

```json
{
  "success": true,
  "data": ["property1", "property2", "property3"]
}
```

## Get Property Values

**Endpoint**: `GET /api/datasets/get_property_values.php`

Get unique values for a specific property.

### Parameters

- `id` (required): Dataset ID
- `property` (required): Property name

### Response

```json
{
  "success": true,
  "data": ["value1", "value2", "value3"]
}
```

## Dataset Filters

**Endpoint**: `GET /api/datasets/filters.php`

Get saved filters for a dataset.

### Parameters

- `id` (required): Dataset ID

### Response

```json
{
  "success": true,
  "data": {
    "filters": [
      {
        "id": 1,
        "name": "Filter Name",
        "conditions": { ... }
      }
    ]
  }
}
```

## Save Dataset Filters

**Endpoint**: `POST /api/datasets/save_filters.php`

Save filter configuration for a dataset.

### Request Body

```json
{
  "id": 123,
  "filters": [
    {
      "name": "Filter Name",
      "conditions": {
        "property": "value",
        "operator": "equals"
      }
    }
  ]
}
```

### Response

```json
{
  "success": true,
  "message": "Filters saved successfully"
}
```

## Dataset Legend

**Endpoint**: `GET /api/datasets/legend.php`

Get legend configuration for a dataset.

### Parameters

- `id` (required): Dataset ID

### Response

```json
{
  "success": true,
  "data": {
    "type": "graduated",
    "property": "value",
    "stops": [
      { "value": 0, "color": "#0000ff" },
      { "value": 100, "color": "#ff0000" }
    ]
  }
}
```

## Save Dataset Legend

**Endpoint**: `POST /api/datasets/save_legend.php`

Save legend configuration for a dataset.

### Request Body

```json
{
  "id": 123,
  "legend": {
    "type": "graduated",
    "property": "value",
    "stops": [ ... ]
  }
}
```

### Response

```json
{
  "success": true,
  "message": "Legend saved successfully"
}
```

## Update Dataset Name

**Endpoint**: `POST /api/update_dataset_name.php`

Update the display name of a dataset.

### Request Body

```json
{
  "id": 123,
  "name": "New Dataset Name"
}
```

### Response

```json
{
  "success": true,
  "message": "Dataset name updated"
}
```

## Background Jobs

Dataset operations that may take time (imports, analysis) are processed as background jobs. See [Jobs API](jobs.md) for job management.

## Related Documentation

- [Analysis Tools](../analysis-tools/index.md)
- [Architecture Overview](../architecture.md)