{"id":31556241,"url":"https://github.com/wal33d/us-school-districts-api","last_synced_at":"2026-04-13T12:01:44.972Z","repository":{"id":307261580,"uuid":"966478082","full_name":"Wal33D/us-school-districts-api","owner":"Wal33D","description":"High-performance, memory-optimized API for US school district lookups using official NCES boundary data","archived":false,"fork":false,"pushed_at":"2025-09-12T04:59:07.000Z","size":272,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-04T22:52:41.605Z","etag":null,"topics":["api","education","express","geospatial","gis","nces","nodejs","open-data","pm2","rest-api","school-districts","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/Wal33D/us-school-districts-api#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wal33D.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-15T01:40:22.000Z","updated_at":"2025-09-12T04:59:11.000Z","dependencies_parsed_at":"2025-07-30T10:41:24.995Z","dependency_job_id":"148cfaca-dfe3-4de1-8a81-b8e7054c2dc6","html_url":"https://github.com/Wal33D/us-school-districts-api","commit_stats":null,"previous_names":["wal33d/candycomp-us-school-districts-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Wal33D/us-school-districts-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fus-school-districts-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fus-school-districts-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fus-school-districts-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fus-school-districts-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wal33D","download_url":"https://codeload.github.com/Wal33D/us-school-districts-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fus-school-districts-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31751705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","education","express","geospatial","gis","nces","nodejs","open-data","pm2","rest-api","school-districts","typescript"],"created_at":"2025-10-04T22:50:47.570Z","updated_at":"2026-04-13T12:01:44.885Z","avatar_url":"https://github.com/Wal33D.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# US School Districts Service\n\nHigh-performance API for US school district boundary lookups using NCES official data with SQLite.\n\n## Overview\n\nProvides school district information based on geographic coordinates for various platform. Uses official NCES (National Center for Education Statistics) shapefile data stored in SQLite with spatial indexing for ultra-fast lookups. Built with TypeScript and Express, featuring minimal memory usage (~100MB) and exceptional reliability.\n\n## Performance Improvements (v2.0)\n\n| Metric | Old (R-tree) | New (SQLite) | Improvement |\n|--------|--------------|--------------|-------------|\n| Memory Usage | 1,700 MB | 100 MB | **95% reduction** |\n| Success Rate | 70% | 100% | **Perfect reliability** |\n| Response Time | Degraded under load | \u003c50ms consistent | **Stable performance** |\n| Startup Time | 30+ seconds | \u003c1 second | **30x faster** |\n\n## Features\n\n- **SQLite Database** - Pre-built spatial database for instant lookups\n- **Spatial Indexing** - Bounding box indexes for O(log n) performance\n- **Memory Efficient** - Only ~100MB RAM usage (vs 1.7GB before)\n- **100% Reliability** - No timeouts or failures under heavy load\n- **NCES Data** - Official government school district boundaries\n- **TypeScript** - Full type safety with zero errors/warnings\n- **Production Ready** - PM2 support with graceful shutdown\n\n## Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Setup database (one-time - requires NCES shapefile)\nnpm run setup-db\n\n# Run development server\nnpm run dev\n\n# Run production\nnpm start\n```\n\n## Database Setup\n\nThe service requires a one-time database creation from NCES shapefiles:\n\n1. **Download NCES Data**:\n   - Visit [NCES School District Boundaries](https://nces.ed.gov/programs/edge/Geographic/DistrictBoundaries)\n   - Download the latest shapefile (e.g., `EDGE_SCHOOLDISTRICT_TL24_SY2324.zip`)\n   - Extract to `school_district_data/` directory\n\n2. **Build Database**:\n   ```bash\n   npm run build\n   npm run setup-db\n   ```\n\nThis creates a ~200MB SQLite database with 13,382 US school districts.\n\n## Environment Variables\n\n### Core Settings\n| Variable | Description | Default |\n|----------|-------------|---------|\n| PORT | Service port | 3712 |\n| NODE_ENV | Environment mode | development |\n| LOG_LEVEL | Logging level | info |\n\n## API Endpoints\n\n### Health Check\n```bash\nGET /health\n```\nReturns service health status and memory usage.\n\n### Single Lookup\n```bash\nGET /school-district?lat=42.3601\u0026lng=-71.0589\n```\n\n**Response:**\n```json\n{\n  \"status\": true,\n  \"districtId\": \"2502790\",\n  \"districtName\": \"Boston School District\",\n  \"gradeRange\": {\n    \"lowest\": \"Pre-K\",\n    \"highest\": \"12\"\n  },\n  \"area\": {\n    \"landSqMiles\": 48.34,\n    \"waterSqMiles\": 41.27\n  },\n  \"schoolYear\": \"2023-2024\",\n  \"stateCode\": \"25\",\n  \"coordinates\": {\n    \"lat\": 42.3601,\n    \"lng\": -71.0589\n  }\n}\n```\n\n### POST Lookup\n```bash\nPOST /lookup\nContent-Type: application/json\n\n{\n  \"lat\": 42.3601,\n  \"lng\": -71.0589\n}\n```\n\n### Batch Lookup\n```bash\nPOST /school-districts/batch\nContent-Type: application/json\n\n{\n  \"coordinates\": [\n    {\"lat\": 42.3601, \"lng\": -71.0589},\n    {\"lat\": 40.7128, \"lng\": -74.0060}\n  ]\n}\n```\n\nReturns array of results for each coordinate (max 100 per batch).\n\n## Production Deployment\n\n### PM2 Configuration\n\n```bash\n# Start with PM2\npm2 start ecosystem.config.js\n\n# Monitor\npm2 monit\n\n# Reload (zero-downtime)\npm2 reload ecosystem.config.js\n\n# View logs\npm2 logs us-school-districts-api\n```\n\nThe service is configured with:\n- Auto-restart on failure\n- Memory limit: 150MB (auto-restart if exceeded)\n- Daily restart at 3 AM for maintenance\n- Graceful shutdown handling\n\n## Architecture\n\n### SQLite-Based Design\n\n```\n┌─────────────────────────────────────────┐\n│         School Districts API             │\n├─────────────────────────────────────────┤\n│                                         │\n│   Request → Bounding Box Query         │\n│      ↓                                  │\n│   SQLite Spatial Index                 │\n│      ↓                                  │\n│   Candidates (1-5 districts)           │\n│      ↓                                  │\n│   Point-in-Polygon Check               │\n│      ↓                                  │\n│   Return Match or Nearest              │\n│                                         │\n├─────────────────────────────────────────┤\n│   Memory: ~100MB   Response: \u003c50ms     │\n└─────────────────────────────────────────┘\n```\n\n### Why SQLite?\n\n1. **Memory Efficiency**: Database on disk, not in RAM\n2. **Fast Queries**: Prepared statements + spatial indexes\n3. **Reliability**: No garbage collection issues\n4. **Portability**: Single file database\n5. **Read-Only Safety**: Database opened in read-only mode\n\n## CLI Tool\n\nTest the API using the built-in CLI:\n\n```bash\n# Single coordinate lookup\nnpm run cli lookup --latitude 42.3601 --longitude -71.0589\n\n# Batch processing from file\nnpm run cli batch --file coordinates.json\n\n# Health check\nnpm run cli health\n\n# Performance test\nnpm run cli test --requests 1000\n```\n\n## Development\n\n```bash\n# Development with auto-reload\nnpm run dev\n\n# Run tests\nnpm test\n\n# Lint and format\nnpm run lint\nnpm run format\n\n# Type checking\nnpm run type-check\n\n# Clean build\nnpm run clean \u0026\u0026 npm run build\n```\n\n## Performance\n\nStress test results (1000 requests, 10 concurrent):\n\n```\nTotal Requests: 1000\nSuccessful: 1000 (100.0%)\nFailed: 0 (0.0%)\nAverage Response: 109ms\nRequests/Second: 90.58\nMemory Usage: ~100MB (stable)\n```\n\n## Troubleshooting\n\n### Database Not Found\n```\nError: Database not found at .../districts.db\n```\n**Solution**: Run `npm run setup-db` after placing shapefile in `school_district_data/`\n\n### High Memory Usage\nIf memory exceeds 150MB, PM2 will auto-restart. Check for:\n- Memory leaks in custom code\n- Excessive concurrent requests\n- Large batch sizes\n\n### Slow Lookups\nNormal response time is \u003c50ms. If slower:\n- Check disk I/O performance\n- Verify spatial indexes exist\n- Monitor concurrent request load\n\n## License\n\nMIT\n\n## Author\n\n**Waleed Judah** (Wal33D)\n- Email: aquataze@yahoo.com\n- GitHub: [@Wal33D](https://github.com/Wal33D)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwal33d%2Fus-school-districts-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwal33d%2Fus-school-districts-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwal33d%2Fus-school-districts-api/lists"}