Geo - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: The two public reference-data endpoints for Nepal's provinces and districts.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

5. Auth, Identity, and Permissions

6. DTO and Model Reference

6.1 Query DTOs

6.2 Response DTOs

7. Enum Reference

None — province/district codes are data, not enums.

8. Endpoint Reference

8.1 GET /api/mobile/geo/provinces

Purpose

The province picker. Seven entries in official order; key on code, display name.

Auth and Permissions

@Public(); PUBLIC_READ 60/min; no permission.

Response

200 — data array of { id, code, name, displayOrder }.

{
  "message": "Provinces fetched successfully",
  "errorCode": null,
  "data": [
    { "id": "0198…", "code": "koshi", "name": "Koshi", "displayOrder": 1 },
    { "id": "0198…", "code": "bagmati", "name": "Bagmati", "displayOrder": 3 }
  ]
}

Error Cases

None — a list of a fixed table cannot 404.

8.2 GET /api/mobile/geo/districts

Purpose

The district picker — all 77, or one province's, ordered by name.

Request

Response

200 — data array of { id, code, name, province }.

{
  "message": "Districts fetched successfully",
  "errorCode": null,
  "data": [
    {
      "id": "0198…",
      "code": "kathmandu",
      "name": "Kathmandu",
      "province": { "id": "0198…", "code": "bagmati", "name": "Bagmati" }
    }
  ]
}

Error Cases

Edge Cases

The four merge-trap codes (rukum-east/rukum-west, nawalpur/parasi) are distinct rows in different provinces — never merge them.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence

10. Pagination, Sorting, Filtering, and Search

Unpaginated by default — the whole list is the contract for a picker.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered in §8: full responses (§8.1/8.2), empty-list behavior (empty data before seeding), domain error (404 GEO_PROVINCE_NOT_FOUND), rate-limit behavior (429).

13.3 API Diagram Pack

Route ownership (§9.1), request sequence (§9.2).

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8, §13.1).
• Every parent route prefix and runtime URL is documented (§2, §4).
• Every DTO field, enum, default, transform and validator is documented (§6).
• Every response field and nullable field is documented (§8).
• Every auth, guard, permission and guest identity branch is documented (§5).
• Every success and error branch is documented (§8).
• Every DB read, cache and external call is documented (§11).
• Every route has examples for success responses and representative failures (§8).
• Every endpoint family has route and sequence diagrams (§9).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (§1, See Also).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every response envelope is documented.
• Every error code is documented.
• Every auth guard and permission is documented.
• Every cache key, queue job and external call is documented.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/geo/backend
• Features and flows doc: /docs/developer/geo/feature
• TDD: not yet published