https://github.com/jongan69/college-financial-estimate-api
A python api for estimating college degree prices
https://github.com/jongan69/college-financial-estimate-api
Last synced: 4 months ago
JSON representation
A python api for estimating college degree prices
- Host: GitHub
- URL: https://github.com/jongan69/college-financial-estimate-api
- Owner: jongan69
- Created: 2025-11-08T22:48:50.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-11-09T21:29:29.000Z (9 months ago)
- Last Synced: 2025-12-19T23:45:22.532Z (7 months ago)
- Language: Python
- Size: 15.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# College Financial API
A FastAPI application that estimates the total cost of college degrees for U.S. universities using the College Scorecard API.
## Features
✅ **Caching** - In-memory caching to avoid duplicate external API requests
✅ **Compare Endpoint** - Compare costs across multiple universities
✅ **Program Cost Endpoint** - Get cost information for specific programs/fields of study
✅ **Inflation Adjustment** - Optional inflation adjustment for cost estimates
## Installation
```bash
pip install -r requirements.txt
```
Or install individually:
```bash
pip install fastapi uvicorn requests python-dotenv
```
## Configuration
Create a `.env` file in the root directory:
```env
API_KEY=your_key_here
DATA_API_KEY=your_key_here
```
Get your free API key from: https://api.data.gov/signup/
## Running Locally
```bash
export API_KEY="your_key_here"
uvicorn main:app --reload
```
Then visit:
- API: http://127.0.0.1:8000
- Interactive Docs: http://127.0.0.1:8000/docs
## API Documentation
### Interactive Documentation
Visit the interactive documentation page:
- **Deployed**: https://college-financial-api.gradtrack.workers.dev/docs
- **Local**: http://127.0.0.1:8000/docs (when running locally)
The docs page includes:
- Complete API reference
- Parameter descriptions
- Example requests and responses
- Try-it links for each endpoint
## API Endpoints
### GET `/degree-cost`
Get the total cost of a degree for a single university.
**Parameters:**
- `university` (required): Full name of the university
- `degree` (optional): Degree level (default: "Bachelor")
- `years` (optional): Number of years (default: 4)
- `adjust_inflation` (optional): Adjust costs for inflation (default: false)
**Example:**
```
http://127.0.0.1:8000/degree-cost?university=University%20of%20Florida&years=4&adjust_inflation=true
```
### GET `/compare`
Compare costs across multiple universities (up to 10).
**Parameters:**
- `universities` (required): Comma-separated list of university names
- `degree` (optional): Degree level (default: "Bachelor")
- `years` (optional): Number of years (default: 4)
- `adjust_inflation` (optional): Adjust costs for inflation (default: false)
**Example:**
```
http://127.0.0.1:8000/compare?universities=University%20of%20Florida,University%20of%20California&years=4
```
### GET `/program-cost`
Get cost for a specific program/field of study at a university.
**Parameters:**
- `university` (required): Full name of the university
- `program` (optional): Field of study (e.g., "Computer Science", "Business")
- `degree` (optional): Degree level (default: "Bachelor")
- `years` (optional): Number of years (default: 4)
- `adjust_inflation` (optional): Adjust costs for inflation (default: false)
**Example:**
```
http://127.0.0.1:8000/program-cost?university=University%20of%20Florida&program=Computer%20Science&years=4
```
## Caching
The API uses in-memory caching to avoid duplicate external API requests. Cache is stored in memory for the duration of the application runtime.
## Response Format
All endpoints return JSON with the following structure:
```json
{
"university": "University of Florida",
"degree": "Bachelor",
"years": 4,
"in_state_total": 45600,
"out_of_state_total": 180000,
"breakdown": {
"tuition_in_state": 6380,
"tuition_out_state": 28659,
"room_board": 10190,
"other_expenses": 3330
},
"inflation_adjusted": false
}
```
## Deployment to Cloudflare Workers
The API is deployed serverlessly on Cloudflare Workers (no local server needed).
**Live API**: `https://college-financial-api.gradtrack.workers.dev`
### Deploy
```bash
# Install Wrangler CLI
npm install -g wrangler
# or
bun install -g wrangler
# Login to Cloudflare
wrangler login
# Set API key secret
wrangler secret put API_KEY
# Deploy
./deploy_workers.sh
# or
wrangler deploy
```
### Test Deployed API
```bash
# Test root endpoint
curl https://college-financial-api.gradtrack.workers.dev/
# Test degree cost
curl "https://college-financial-api.gradtrack.workers.dev/degree-cost?university=MIT"
# Run test suite
python3 test_deployed_api.py
```
## Testing
### Local Testing
```bash
# Run test suite
python3 test_api.py
```
### Deployed API Testing
```bash
python3 test_deployed_api.py
```
## Notes
- The College Scorecard API has limited program-specific cost data. The `/program-cost` endpoint provides base university costs with program availability information.
- Inflation adjustment uses a 3% annual inflation rate by default.
- The API uses in-memory caching to reduce external API calls.