# WebGIS Poverty Mapping - API Documentation

**Version:** 1.0  
**Last Updated:** May 2026

## Table of Contents

1. [Overview](#overview)
2. [Base URL & Authentication](#base-url--authentication)
3. [Endpoints](#endpoints)
4. [Error Handling](#error-handling)
5. [Examples](#examples)
6. [Data Types](#data-types)

---

## Overview

The WebGIS Poverty Mapping API provides RESTful endpoints to manage geographical data related to poverty mapping, including:
- Points of Interest (Rumah Ibadah, Rumah Miskin, etc.)
- Linear Features (Jalan)
- Polygonal Features (Parsil)

All responses are in JSON format with GeoJSON support for spatial data.

---

## Base URL & Authentication

**Base URL:** `http://localhost/webgis/`

**Content-Type:** `application/json`

**Response Format:** `application/json`

Authentication is not currently implemented. For production, implement JWT or OAuth2.

---

## Endpoints

### 1. GET /get_improved.php - Retrieve Data

Get all features or filtered by type and status.

**Method:** `GET` or `POST`

**Query Parameters:**
```
- tipe          (optional): point | worship | poor_house | jalan | parsil
- status        (optional): aktif | nonaktif | draf (default: aktif)
- limit         (optional): max records to return (default: 1000, max: 5000)
- offset        (optional): pagination offset (default: 0)
- format        (optional): geojson | json (default: geojson)
```

**Request Example:**
```bash
GET /get_improved.php?tipe=worship&status=aktif&limit=100
```

**Response (GeoJSON Format):**
```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [109.3494, -0.0554]
      },
      "properties": {
        "id": 1,
        "tipe": "worship",
        "nama": "Masjid Al-Hidayah",
        "jenis": "Masjid",
        "alamat": "Jln Imam Bonjol",
        "status": "aktif",
        "radius_meter": 200,
        "kapasitas": 500,
        "kegiatan": "Shalat Jum'at, Pengajian",
        "created_at": "2026-05-20 10:00:00"
      }
    }
  ],
  "pagination": {
    "total": 150,
    "count": 100,
    "limit": 100,
    "offset": 0
  }
}
```

**Status Codes:**
- `200 OK` - Success
- `400 Bad Request` - Invalid parameters
- `500 Internal Server Error` - Server error

---

### 2. POST /save_improved.php - Create New Data

Create a new feature in the database.

**Method:** `POST`

**Request Body:**
```json
{
  "tipe": "worship",
  "nama": "Masjid Baitussalam",
  "jenis": "Masjid",
  "alamat": "Jln Dipanegara No 45",
  "kontak": "Imam Haji Syaiful",
  "no_wa": "+62812345678",
  "kegiatan": "Shalat Jum'at, Pengajian",
  "kapasitas": 500,
  "radius_meter": 200,
  "latitude": -0.0554,
  "longitude": 109.3494,
  "status": "aktif"
}
```

**Response (Success):**
```json
{
  "success": true,
  "message": "Data saved successfully",
  "data": {
    "id": 123
  },
  "timestamp": "2026-05-20 10:15:00"
}
```

**Response (Error):**
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "tipe": "Field 'tipe' is required",
    "radius_meter": "Field 'radius_meter' must be >= 1"
  },
  "timestamp": "2026-05-20 10:15:00"
}
```

**Status Codes:**
- `200 OK` - Success
- `400 Bad Request` - Validation error
- `500 Internal Server Error` - Server error

**Required Fields by Type:**

**Type: worship**
- nama
- tipe
- radius_meter (1-500)

**Type: poor_house**
- nama_kepala_keluarga
- latitude
- longitude

**Type: jalan**
- geom (LineString GeoJSON)
- panjang

**Type: parsil**
- geom (Polygon GeoJSON)
- luas

---

### 3. POST /update_improved.php - Update Data

Update an existing feature.

**Method:** `POST`

**Request Body:**
```json
{
  "id": 123,
  "nama": "Masjid Baitussalam (Updated)",
  "kapasitas": 600,
  "status": "aktif"
}
```

**Response (Success):**
```json
{
  "success": true,
  "message": "Data updated successfully",
  "data": {
    "id": 123
  },
  "timestamp": "2026-05-20 10:20:00"
}
```

**Status Codes:**
- `200 OK` - Success
- `400 Bad Request` - Validation error
- `404 Not Found` - Record not found
- `500 Internal Server Error` - Server error

---

### 4. POST /delete_improved.php - Delete Data

Delete or soft-delete a feature.

**Method:** `POST`

**Request Body:**
```json
{
  "id": 123,
  "method": "soft"
}
```

**Parameters:**
- `id` (required): Record ID to delete
- `method` (optional): "soft" (mark as nonaktif) or "hard" (actually remove)

**Response (Success):**
```json
{
  "success": true,
  "message": "Data deleted successfully",
  "data": {
    "id": 123
  },
  "timestamp": "2026-05-20 10:25:00"
}
```

**Status Codes:**
- `200 OK` - Success
- `404 Not Found` - Record not found
- `405 Method Not Allowed` - Wrong HTTP method
- `500 Internal Server Error` - Server error

---

## Error Handling

All errors follow this structure:

```json
{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": "Specific error message"
  },
  "timestamp": "2026-05-20 10:30:00"
}
```

### Common Error Codes

| Code | Message | Solution |
|------|---------|----------|
| 400 | Bad Request | Check request format and parameters |
| 400 | Invalid JSON input | Ensure JSON is properly formatted |
| 400 | Validation failed | Check required fields and data types |
| 404 | Record not found | Verify the ID exists |
| 405 | Method not allowed | Use correct HTTP method (GET/POST) |
| 500 | Server error | Check server logs |

---

## Examples

### Example 1: Add Rumah Ibadah

```bash
curl -X POST http://localhost/webgis/save_improved.php \
  -H "Content-Type: application/json" \
  -d '{
    "tipe": "worship",
    "nama": "Gereja Pentekosta",
    "jenis": "Gereja",
    "alamat": "Jln Achmad Yani",
    "kontak": "Pdt. Markus",
    "kegiatan": "Ibadah Minggu, Doa Malam",
    "kapasitas": 300,
    "radius_meter": 150,
    "latitude": -0.0500,
    "longitude": 109.3500,
    "status": "aktif"
  }'
```

### Example 2: Add Poor Household

```bash
curl -X POST http://localhost/webgis/save_improved.php \
  -H "Content-Type: application/json" \
  -d '{
    "tipe": "poor_house",
    "nama_kepala_keluarga": "Budi Santoso",
    "alamat": "Jln Cendana RT 05 RW 02",
    "jumlah_anggota": 5,
    "kondisi_rumah": "BURUK",
    "sumber_penghasilan": "Buruh",
    "kebutuhan_prioritas": "Perbaikan Atap",
    "status_bantuan": "BELUM",
    "latitude": -0.0600,
    "longitude": 109.3400,
    "status": "aktif"
  }'
```

### Example 3: Retrieve All Worship Places

```bash
curl "http://localhost/webgis/get_improved.php?tipe=worship&limit=50"
```

### Example 4: Update Feature

```bash
curl -X POST http://localhost/webgis/update_improved.php \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "nama": "Masjid Al-Hidayah (Updated)",
    "status": "aktif"
  }'
```

### Example 5: Delete Feature (Soft Delete)

```bash
curl -X POST http://localhost/webgis/delete_improved.php \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "method": "soft"
  }'
```

---

## Data Types

### Feature Types

| Type | Description | Key Fields |
|------|-------------|-----------|
| worship | Rumah Ibadah (Masjid, Gereja, dll) | nama, jenis, radius_meter, kapasitas |
| poor_house | Rumah Penduduk Miskin | nama_kepala_keluarga, jumlah_anggota, kondisi_rumah |
| point | Data Umum | nama, alamat |
| jalan | Ruas Jalan | geom (LineString), panjang |
| parsil | Bidang/Parsil | geom (Polygon), luas |

### House Conditions

| Code | Description |
|------|-------------|
| SANGAT_BURUK | Rumah dalam kondisi sangat buruk/rawan roboh |
| BURUK | Rumah banyak kerusakan |
| SEDANG | Rumah dengan kerusakan ringan |
| BAIK | Rumah dalam kondisi baik |

### Assistance Status

| Code | Description |
|------|-------------|
| BELUM | Belum menerima bantuan apapun |
| PENERIMA_PKH | Penerima Program Keluarga Harapan |
| PENERIMA_BLT | Penerima Bantuan Langsung Tunai |
| PENERIMA_BANTSOS | Penerima bantuan sosial lainnya |

### Income Sources

| Code | Description |
|------|-------------|
| PETANI | Petani |
| BURUH | Buruh |
| PEDAGANG | Pedagang |
| PNS | PNS |
| SWASTA | Pegawai Swasta |
| USAHA_KECIL | Usaha Kecil |
| PENSIUN | Pensiun |
| TIDAK_BEKERJA | Tidak Bekerja |

---

## GeoJSON Reference

### Point Geometry

```json
{
  "type": "Point",
  "coordinates": [109.3494, -0.0554]
}
```

### LineString Geometry (Jalan)

```json
{
  "type": "LineString",
  "coordinates": [
    [109.3494, -0.0554],
    [109.3500, -0.0560],
    [109.3510, -0.0570]
  ]
}
```

### Polygon Geometry (Parsil)

```json
{
  "type": "Polygon",
  "coordinates": [
    [
      [109.3494, -0.0554],
      [109.3500, -0.0554],
      [109.3500, -0.0560],
      [109.3494, -0.0560],
      [109.3494, -0.0554]
    ]
  ]
}
```

---

## Rate Limiting & Performance Tips

- Maximum 1000 records per request (configurable via `limit` parameter, max 5000)
- Use pagination with `offset` for large datasets
- Index on commonly filtered fields: `tipe`, `status`, `latitude`, `longitude`
- Cache results when possible
- Use GeoJSON format for map applications

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | May 2026 | Initial API documentation |

---

**For support, contact the development team.**