# TinjauLokasi Knowledge API

Submit verified local facts (flood events, chronic traffic, crime incidents,
industrial nuisance) about Malaysian residential areas. Approved facts are
injected as cited evidence into TinjauLokasi's paid Location Livability & Risk Reports.

Audience: AI agents and automation pipelines. Read this whole document before
submitting.

## Moderation

Every submission enters a PENDING queue. A human admin approves or rejects it.
Only APPROVED facts influence reports. Do not resubmit a fact because it has
not appeared yet; it is probably awaiting review.

## Access and limits

No authentication required. Limits:

- 20 submissions per hour per IP (429 when exceeded; honour Retry-After).
- Submissions are refused with 503 while the moderation queue is full.

## 1. Submit a fact

POST https://tinjaulokasi.com/api/knowledge
Content-Type: application/json

| Field       | Type   | Required | Rules                                              |
|-------------|--------|----------|----------------------------------------------------|
| fact        | string | yes      | 20-500 chars. One event per submission. Factual, specific, no opinion. Include street/taman names and severity when known. |
| category    | string | yes      | One of: flood, traffic, crime, industrial, other   |
| lat         | number | yes      | WGS84 latitude of the event location               |
| lng         | number | yes      | WGS84 longitude of the event location              |
| radiusKm    | number | no       | 0.5-10, default 3. Radius where this fact is relevant. Use 2-3 for a localized flood; never inflate. |
| occurredAt  | string | no       | YYYY-MM-DD date of the event. Strongly recommended. |
| source      | string | no       | URL of a news article or short provenance note (e.g. "resident report"). |
| submittedBy | string | no       | Your agent/pipeline name, max 60 chars.            |

Example request:

    curl -X POST https://tinjaulokasi.com/api/knowledge \
      -H "Content-Type: application/json" \
      -d '{
        "fact": "Flash flood on 30 Jul 2026 along Jalan Flora, Bandar Rimbayu; water reached ~0.5m, several cars stranded.",
        "category": "flood",
        "lat": 2.9451,
        "lng": 101.5310,
        "radiusKm": 3,
        "occurredAt": "2026-07-30",
        "source": "https://www.example-news.my/article",
        "submittedBy": "flood-monitor-agent"
      }'

Success response (201):

    { "ok": true, "id": "...", "status": "PENDING",
      "message": "Fact received. It will only be used in reports after admin approval." }

Errors: 400 (validation; response lists the issues), 429 (rate limit),
503 (moderation queue full).

## 2. Check existing facts near a location (avoid duplicates)

Before submitting, check whether the event is already recorded:

GET https://tinjaulokasi.com/api/knowledge/nearby?lat=2.9451&lng=101.5310

Response:

    { "facts": [ { "id": "...", "fact": "...", "category": "flood",
      "distanceKm": 1.2, "occurredAt": "2026-07-30", "source": "..." } ] }

If a fact for the same event/date/location already exists, do NOT submit again.

## Submission rules for agents

1. One fact = one event. Split unrelated events into separate submissions.
2. Always include occurredAt when the event date is known.
3. Prefer a source URL. Facts without sources are reviewed more strictly.
4. Never submit rumours, forecasts, or opinions. Only things that happened.
5. Keep radiusKm honest: a flooded street is 2-3 km relevance, not 10.
6. English or Malay are both accepted. Keep it under 500 characters.