{"id":18986870,"url":"https://github.com/karllhughes/colleges","last_synced_at":"2025-08-12T21:04:29.502Z","repository":{"id":25930691,"uuid":"29371989","full_name":"karllhughes/colleges","owner":"karllhughes","description":"An open API of US colleges and universities","archived":false,"fork":false,"pushed_at":"2017-05-11T00:44:27.000Z","size":963,"stargazers_count":19,"open_issues_count":0,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-14T21:34:26.558Z","etag":null,"topics":["api","college","education","php","university"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karllhughes.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-16T23:08:11.000Z","updated_at":"2024-08-27T01:38:04.000Z","dependencies_parsed_at":"2022-08-24T14:17:49.745Z","dependency_job_id":null,"html_url":"https://github.com/karllhughes/colleges","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/karllhughes/colleges","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karllhughes%2Fcolleges","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karllhughes%2Fcolleges/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karllhughes%2Fcolleges/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karllhughes%2Fcolleges/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karllhughes","download_url":"https://codeload.github.com/karllhughes/colleges/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karllhughes%2Fcolleges/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270134997,"owners_count":24533193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","college","education","php","university"],"created_at":"2024-11-08T16:37:14.642Z","updated_at":"2025-08-12T21:04:29.475Z","avatar_url":"https://github.com/karllhughes.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# US Colleges API\n\nThis is an open API for accessing the names and locations of accredited colleges and universities in the United States.\n\n## Local Installation\n\n### Prerequisites\n\n- Docker and Docker Compose\n- NPM/NodeJS 6+\n\n### Local Setup\n\n- Clone this repository.\n- Install the composer packages: `npm run -s composer:install`.\n- Copy `.env.example` to `.env` and add your credentials.\n- Build the dockerfile: `npm run -s app:local:build`.\n- Bring up the containers: `npm run -s app:local:up`. It may take a few seconds for the database to start up the first time.\n- Run the migrations: `npm run -s db:migrate`.\n- Run the seeder: `npm run -s db:seed`.\n\nThe application's documentation will be reachable at `localhost:8100/`.\n\n## Usage\n\n### API Documentation\n\n- Once your web application is running, visit `localhost:8100/` to view the documentation.\n- By default, all requests are made on the first page of 100, ordered by ID. You can change that though.\n- Examples:\n\n#### Get the second 100 colleges sorted by name and transformed:\n\n``` \nhttp://localhost:8100/colleges?order=name\u0026page=2,100\u0026transform=1\n```\n\n#### Get the second page of records for colleges in Memphis, TN:\n\n``` \nhttp://localhost:8100/colleges?order=id\u0026page=2,20\u0026filter=location,eq,Memphis, TN\n```\n\n#### Get a single college by uuid\n```\nhttp://localhost:8100/colleges/a3379d4e-bc71-4a7d-b7d9-c954c8b1d300\n```\n\nCurrently only GET requests are supported. POST, PUT, DELETE and others will be available with API key authorization in a later release.\n\n## Server Deployment\nThis project is intended to be hosted on [Hyper.sh](https://hyper.sh/), but you can set it up anywhere you host docker containers.\n\n### First time deployment\n- Upload local data to volume: `hyper run -v $(pwd)/.data:/.data ubuntu`\n- Remove the original container: `hyper rm \u003cCID\u003e`\n- Create snapshot: `hyper snapshot create --volume \u003cVID\u003e --name colleges`\n- Create named volume from snapshot: `hyper volume create --snapshot=colleges --name=colleges`\n- Pull the latest: `hyper pull karllhughes/colleges:latest`\n- Bring up the containers: `hyper compose up -f docker/compose.hyper.yml -p colleges$RANDOM -d`\n- Attach your floating IP: `hyper fip attach \u003cFIP\u003e \u003cCID\u003e`\n\n### Updating code\n\nUpdating production code:\n\n- Pull the latest: `hyper pull karllhughes/colleges:latest`\n- Recreate the containers: `hyper compose up -f docker/compose.hyper.yml -d --force-recreate -p \u003cPID\u003e`\n- Attach your floating IP: `hyper fip attach \u003cFIP\u003e \u003cPID\u003e`\n\nOr the single command/container:\n\n- Add a `docker/deployer/.env` file with your Hyper.sh credentials.\n- Run `npm run -s app:prod:deploy`.\n\n## Technical Details\n\n- The list of colleges is retrieved from [ope.ed.gov](https://ope.ed.gov/accreditation/GetDownloadFile.aspx), and the last update was in March 2016.\n- I standardized fields based on [Schema.org's CollegeOrUniversity object](https://schema.org/CollegeOrUniversity). Not all fields are currently supported and I had to add a couple special ones, so check the migrations files for a list of supported fields.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarllhughes%2Fcolleges","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarllhughes%2Fcolleges","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarllhughes%2Fcolleges/lists"}