TemanNelayan API

Dokumentasi ini disusun berdasarkan implementasi di folder src/ proyek. Struktur respons dan parameter mengikuti yang ada di kode (routes.js, controllers/*, services/*).

Base URL

http://localhost:3000/api

Autentikasi

Tidak diperlukan pada versi ini. Beberapa fitur cuaca menggunakan OpenWeather dan memerlukan konfigurasi OW_API_KEY di environment server.

---

1. Health Check

Cek status API.

Endpoint

GET /health

Response

{ "status": "ok" }

---

2. Weather by Coordinates

Mengambil ringkasan cuaca pada koordinat tertentu. Parameter lat dan lon wajib.

Endpoint

GET /weather

Query Parameters

Parameter	Tipe	Wajib	Deskripsi
lat	number	ya	Lintang
lon	number	ya	Bujur

Response Struktur respons disusun dari weatherController.get, locationService, dan weatherService:

{
	"coord": { "lat": "-6.2", "lon": "106.8" },
	"location": {},
	"weather": {
		"description": "broken clouds",
		"humidity": 78,
		"temp_c": 29.5,
		"pressure": 1007,
		"wind": { "speed_mps": 4.2, "category": "Angin sedang" },
		"gust": { "speed_mps": 6.0, "category": "Angin kencang" },
		"direction": { "direction": "Timur", "deg": 90 }
	}
}

Kode Status

• 200 OK
• 400 jika lat/lon tidak diberikan
• 500 jika layanan pihak ketiga gagal

---

3. List Map Grids

Mengambil daftar grid laut dari file src/map/map.json beserta atribut yang dikalkulasikan.

Endpoint

GET /map

Response Array of object. Contoh 2 item pertama (diambil langsung dari map.json dan dipetakan oleh mapController.get):

[
	{
		"id": 0,
		"gridId": "GRID_007",
		"tanggal": "2025-09-01",
		"latitude": -10.9326,
		"longitude": 94.0686,
		"sst": 30.61,
		"chlorophyll": 1.1,
		"zpi": 9,
		"kedalamanClass": 5534.87,
		"kedalamanMeter": "Abisal (zona sangat dalam)",
		"musim": "Musim Barat)"
	},
	{
		"id": 1,
		"gridId": "GRID_012",
		"tanggal": "2025-09-01",
		"latitude": -10.9326,
		"longitude": 94.2059,
		"sst": 29.93,
		"chlorophyll": 0.61,
		"zpi": 55,
		"kedalamanClass": 5066.26,
		"kedalamanMeter": "Abisal (zona sangat dalam)",
		"musim": "Musim Barat)"
	}
]

Keterangan field:

• kedalamanClass: nilai kedalaman dalam meter (apa adanya dari data).
• kedalamanMeter: klasifikasi zona kedalaman (hasil depthClass()).
• musim: hasil fishingSeasonNow().
• jenisIkan: array 3 ikan acak dari src/map/fish.js (tidak ditampilkan pada contoh di atas untuk ringkas).

Kode Status

• 200 OK
• 500 Internal Server Error

---

4. Map Detail

Detail satu grid beserta info lokasi dan cuaca pada koordinat titik grid. Juga memuat prediksi kandidat ikan dari model Gemini (hasil dibersihkan lewat safeJSONParse).

Endpoint

GET /map/detail

Query Parameters

Parameter	Tipe	Wajib	Deskripsi
id	string	ya	Kode grid, misal: GRID_007

Response

{
	"id": null,
	"gridId": "GRID_007",
	"tanggal": "2025-09-01",
	"latitude": -10.9326,
	"longitude": 94.0686,
	"sst": 30.61,
	"chlorophyll": 1.1,
	"zpi": 9,
	"kedalamanClass": 5534.87,
	"kedalamanMeter": "Abisal (zona sangat dalam)",
	"musim": "Musim Barat)",
	"location": {},
	"weather": {
		"description": "broken clouds",
		"humidity": 78,
		"temp_c": 29.5,
		"pressure": 1007,
		"wind": { "speed_mps": 4.2, "category": "Angin sedang" },
		"gust": { "speed_mps": 6.0, "category": "Angin kencang" },
		"direction": { "direction": "Timur", "deg": 90 }
	},
	"jenisIkan": [
		{ "id": 35, "name": "Kuwe Laut Dalam" },
		{ "id": 36, "name": "Kakap Laut Dalam" },
		{ "id": 37, "name": "Selar Laut Dalam" }
	]
}

Catatan:

• jenisIkan berasal dari fishPredictionService (Gemini). Jika model mengembalikan teks dengan awalan json atau ada karakter lain, server membersihkan dan melakukan JSON.parse aman via safeJSONParse.
• Jika grid tidak ditemukan: 404.

Kode Status

• 200 OK
• 404 Grid not found
• 500 Internal Server Error

---

5. Fish/Trip Prediction (AI)

Endpoint untuk meminta ringkasan strategi, estimasi BBM, waktu tempuh, dan risiko dari AI berdasarkan input lingkungan, musim, cuaca, dan spesifikasi mesin kapal.

Catatan penting: Di kode saat ini, route terdaftar sebagai GET (/map/prediction) tetapi controller membaca req.body. Klien umum biasanya tidak mengirim body pada GET. Disarankan mengganti method menjadi POST di sisi server. Dokumentasi di bawah mengikuti implementasi controller.

Endpoint (sesuai routes.js)

GET /map/prediction

Request Body (JSON)

{
	"zpi": 78,
	"chl_a": 0.32,
	"temp_c": 29.1,
	"depth": 200,
	"musim": "Musim Timur",
	"distance": 12.5,
	"weather": {
		"windDirection": { "direction": "Timur", "deg": 90 },
		"windSpeed": { "speed_mps": 4.2, "category": "Angin sedang" },
		"humidity": 78,
		"pressure": 1007
	},
	"engine": {
		"power": 15,
		"weight": 220,
		"speed": 8
	}
}

Response

{
	"data": {
		"incomePotential": "sedang",
		"fuelEstimation": 10.8,
		"travellingTime": { "day": 0, "hour": 2, "minute": 30 },
		"strategyRecommendation": "Fokus di area dengan CHL 0.2–0.4 mg/m3, hindari saat angin kencang...",
		"anotherConsideration": "Perhatikan perubahan tekanan...",
		"riskLevel": "moderate"
	}
}

Catatan:

• Struktur data adalah hasil dari predictionService (Gemini) yang diformat ke JSON dan dibersihkan oleh safeJSONParse.
• Jika parsing gagal, server mengembalikan 500 dengan pesan Internal server error (invalid JSON).

Kode Status

• 200 OK
• 500 Internal Server Error

---

Kesalahan Umum

• 400 lat & lon required pada /weather bila parameter tidak diisi.
• 404 Grid not found pada /map/detail bila id tidak ada di map.json.
• 500 Internal Server Error bila
  • gagal mengambil data pihak ketiga (OpenWeather, lokasi pantai/lautan),
  • atau hasil AI tidak dapat diparse menjadi JSON.

---

Catatan Implementasi

• Semua endpoint berada di bawah prefix /api (lihat app.js).
• File sumber penting:
  • src/routes.js
  • src/controllers/*.js
  • src/services/*.js
  • src/utils/allUtils.js (fungsi safeJSONParse untuk membersihkan respons Gemini).
• Dependensi eksternal:
  • OpenWeather (env.owApiBase, OW_API_KEY)
  • Marine Regions / Nominatim untuk nama lokasi
  • Google Gemini (GEMINI_API_KEY)