/postsec_api

Post Secondary Institutions autocomplete API

Primary LanguageCrystal

Ported this to Rails for convenience

PostsecAPI

This is a proof of concept for an API to search accredited post secondary institutions in the US. I once needed this for a project and thought it would work well as a standalone API.

There is a sample autocomplete (view source) using the API, and you can hit the api.

The data was obtained from the IPEDS database

On the other hand, I wanted to try out the crystal programming language and the Lucky web framework, and this looked like a nice fit.

Usage

It's a single endpoint API, at /institutions.

Options

Only three options (passed in as query params) are supported for the time being:

  1. page: optional, defaults to 1.
  2. per_page: optional, defaults to 20.
  3. query: optional, searches the names of the institutions.

Example

  fetch("postsecapi.herokuapp.com/institutions?page=1&per_page=1")
  .then(response => response.json())
  .then(responseJson => console.log(responseJson))

  // = { "ipeds_id": "166027", "name": "Harvard University" }

For a more complete example, check out the sample app.

Running the project locally

  1. Install required dependencies
  2. Run bin/setup
  3. Run lucky dev to start the app
  4. Set up the database running lucky db.create and then lucky db.migrate
  5. Load the database seeds running lucky db.create_required_seeds

Improvements

This is just a proof of concept and I don't intend to invest much time in it unless I find a need for it again. But here are a few ideas of what can be improved, and of course PRs would be more than welcome.

  • Use the IPEDS database better
    • Expose more information, for instance it would be nice to include location data.
    • Use more fields in search, for instance, the name alias field in the IPEDS database could help easily improve the search
  • Use Postgres better (Currently a simple ilike query is being used, but the full text search and trigram module could greatly improve the results)
  • Make production ready (I think this could be a useful service and mantained very cheaply if the previous points are addressed, and API keys are added, but I think it would make more sense to port to a more mature framework)

Learn Lucky

This app uses Lucky, which in turn uses the Crystal programming language. You can learn about Lucky from the Lucky Guides.