Skip to content

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 ?search param
  • Added GET /institutions/universities — replaces /university-names (kept as backward-compat alias); filterable by academic_stream and search
  • Added GET /institutions/colleges — replaces /college-names (kept as backward-compat alias); now filterable by university_name, academic_stream, district, college_type, management_type, medium, and search
  • Added GET /institutions/near — proximity search using PostGIS ST_DWithin on geography type (true-metre radius), results ordered nearest-first; optional academic_stream filter
  • Added PATCH /institutions/{id}/location — admin-only; sets/updates the PostGIS POINT geometry for an institution
  • GET /institutions list endpoint now accepts academic_stream as a filter param
  • InstitutionRowRead / InstitutionRead response schemas expose location as a {latitude, longitude} object (deserialized from PostGIS WKBElement)
  • Added InstitutionLocationUpdate schema for the PATCH body
  • Migration e2f3a4b5c6d7: adds nullable location geometry(POINT, 4326) column and GiST spatial index to the institution table

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}/location200 OK, response includes "location": {"latitude": 17.4239, "longitude": 78.5498}
  • GET /institutions/{id}location field 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-names200 OK (backward-compat alias still works)
  • PATCH /institutions/{id}/location with latitude: 999422 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)

Merge request reports

Loading