Reference API

Overview

Reference API menyediakan data lokasi hierarchical (provinsi → kota → kecamatan → kelurahan) dan validasi foto profil. Service ini read-only untuk data lokasi.

• REST: Port 4000 (dev/prod)
• gRPC: Port 50050 (internal only)

REST Endpoints

List Provinces

GET /provinces

Response 200 OK:

[
  { "id": 11, "name": "ACEH" },
  { "id": 12, "name": "SUMATERA UTARA" },
  { "id": 31, "name": "DKI JAKARTA" }
]

List Cities/Regencies

GET /city_regencies
GET /city_regencies?province_id=31

Response 200 OK:

[
  { "id": 3101, "province_id": 31, "name": "KAB. ADM. KEP. SERIBU" },
  { "id": 3171, "province_id": 31, "name": "KOTA ADM. JAKARTA PUSAT" },
  { "id": 3174, "province_id": 31, "name": "KOTA ADM. JAKARTA SELATAN" }
]

List Districts

GET /districts
GET /districts?city_id=3174

List Villages

GET /villages
GET /villages?district_id=317401

Upload Profile Photo

POST /upload-profile-photo
Content-Type: multipart/form-data

file: <binary image data>

Validasi:

• Max size: 1MB
• Formats: JPEG, PNG, WebP
• Returns presigned S3 URL

gRPC Service: ReferenceService

Dipanggil oleh auth-api untuk validasi data lokasi saat registrasi dan validasi foto.

service ReferenceService {
  rpc ValidateLocation (ValidateLocationRequest)
      returns (ValidateLocationResponse);

  rpc ValidateProfilePhoto (ValidateProfilePhotoRequest)
      returns (ValidateProfilePhotoResponse);
}

ValidateLocation

Memvalidasi bahwa kombinasi province/city/district/village valid dan terdaftar dalam database.

message ValidateLocationRequest {
  string province = 1;
  string city = 2;
  string district = 3;
  string village = 4;
}

message ValidateLocationResponse {
  bool valid = 1;
  string message = 2;
}

Data Source

Database waqfuel_reference berisi tabel locations dengan seluruh data administratif Indonesia:

Level	Jumlah
Provinsi	38
Kota/Kabupaten	~514
Kecamatan	~7.277
Kelurahan/Desa	~83.931

Data di-import via SQL migration file (~2.8MB). Lihat Troubleshooting jika migration lama.

Configuration

Env Var	Deskripsi	Contoh
API_PORT	Port REST server	4000
GRPC_PORT	Port gRPC server	50050
DATABASE_URL	PostgreSQL connection string	postgresql://localhost/waqfuel_reference
AWS_ENDPOINT	S3 endpoint	https://s3.ap-southeast-1.amazonaws.com
AWS_BUCKET_ASSETS	S3 bucket	waqfuel-assets-dev
AWS_REGION	AWS region	ap-southeast-1