refactor(institutions): academic-streams/universities/colleges routes + PostGIS geo location
Summary
- Added
GET /institutions/academic-streams— returns distinct academic stream values stored in the institutions table, with optional?searchparam - Added
GET /institutions/universities— replaces/university-names(kept as backward-compat alias); filterable byacademic_streamandsearch - Added
GET /institutions/colleges— replaces/college-names(kept as backward-compat alias); now filterable byuniversity_name,academic_stream,district,college_type,management_type,medium, andsearch - Added
GET /institutions/near— proximity search using PostGISST_DWithinon geography type (true-metre radius), results ordered nearest-first; optionalacademic_streamfilter - Added
PATCH /institutions/{id}/location— admin-only; sets/updates the PostGISPOINTgeometry for an institution -
GET /institutionslist endpoint now acceptsacademic_streamas a filter param -
InstitutionRowRead/InstitutionReadresponse schemas exposelocationas a{latitude, longitude}object (deserialized from PostGIS WKBElement) - Added
InstitutionLocationUpdateschema for the PATCH body - Migration
e2f3a4b5c6d7: adds nullablelocation geometry(POINT, 4326)column and GiST spatial index to theinstitutiontable
Test plan
-
GET /institutions/academic-streams→["engineering"] -
GET /institutions/academic-streams?search=eng→["engineering"] -
GET /institutions/universities?academic_stream=engineering→["OSMANIA UNIVERSITY"] -
GET /institutions/universities?search=osmania→["OSMANIA UNIVERSITY"] -
GET /institutions/colleges?university_name=OSMANIA UNIVERSITY→["university college of engineering"] -
GET /institutions/colleges?academic_stream=engineering&district=hyderabad→["university college of engineering"] -
PATCH /institutions/{id}/location→200 OK, response includes"location": {"latitude": 17.4239, "longitude": 78.5498} -
GET /institutions/{id}→locationfield populated correctly -
GET /institutions/near?latitude=17.4239&longitude=78.5498&radius_meters=5000→ returns institution, ordered nearest-first -
GET /institutions/near?latitude=0.0&longitude=0.0&radius_meters=100→[] -
GET /institutions?academic_stream=engineering→ filtered results -
GET /institutions/university-names→200 OK(backward-compat alias still works) -
PATCH /institutions/{id}/locationwithlatitude: 999→422 Unprocessable Entity
Checklist
-
Code follows project API guidelines -
Documentation is updated (OpenAPI docs reflect all new endpoints and params) -
Code adheres to project coding standards
Closes #127 (closed)