/ptt-studyabroad-api

🔎 Search articles with personalized results on ptt/studyabroad

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

PTT StudyAbroad API

Website: https://alvinhou.com/studyabroad/

Documentation: https://ptt-studyabroad-api.herokuapp.com/docs

ptt-studyabroad-api

Find articles that matches your background, your research interest and your target school

Having a hard time searching for information about studying abroad?

Got flamed for not doing enough research before posting on PTT?

PTT StudyAbroad API provides a way to search for articles with personalized results that matches your background

ptt-studyabroad-api

Getting Started

Given specific education information (e.g. GPA, major, etc.), target programs (e.g. LTI, MHCI, MSCS, etc.) and target schools, the API returns articles that matches your background best.

The API supports a wide range of programs (especially the CMU ones) and you could specify which domains you are interested in (e.g. HCI, EE, MEng).

Example Request:

POST /admission
Content-Type: application/json
{
  "university": "NTU",
  "major": "IM",
  "gpa": 3.7,
  "target_schools": [
    "Stanford",
    "University of California, Berkeley",
    "CMU"
  ],
  "target_programs": [
    "MHCI", "MSIN"
  ],
  "program_types": [
    "HCI", "CS"
  ],
  "program_level": "MS"
}

Successful Response:

[
  {
    "article_id": "M.1554447713.A.2A5",
    "article_title": "[錄取] UVA/NCSU CS PhD w/o publications",
    "author": "catalish (Hannah)",
    "date": "2019-04-05T15:01:44",
    "url": "https://www.ptt.cc/bbs/studyabroad/M.1554447713.A.2A5.html",
    "university": "CGU",
    "university_cname": "長庚大學",
    "university_cabbr": "長庚",
    "major": "IM",
    "major_cname": "資訊管理學系",
    "major_cabbr": "資管",
    "major_type": "IM",
    "gpa": 3.76,
    "gpa_scale": 4,
    "admission_programs": [
      {
        "university": "University of Virginia",
        "program": "CS",
        "program_level": "PhD",
        "program_type": "CS"
      },
      {
        "university": "North Carolina State University",
        "program": "CS",
        "program_level": "PhD",
        "program_type": "CS"
      },
      {
        "university": "Carnegie Mellon University",
        "program": "MSIN",
        "program_level": "MS",
        "program_type": "CS"
      },
      {
        "university": "Ohio State University",
        "program": "MSCS",
        "program_level": "MS",
        "program_type": "CS"
      }
    ],
    "score": 42
  },...
]

API schema

Entrypoint: https://ptt-studyabroad-api.herokuapp.com/

Playground

Visit the docs and click the [Try it out] button to play with the API

API Playground Example Response

Parameters

Request

parameter type description
university string University that you graduated from. Name in English or Chinese are both acceptable. Examples: NCTU, 交大, 國立交通大學
major string Major that you study. Name in English or Chinese are both acceptable. Examples: CS, IM, CSIE, GINM, Finance, 資工, 網媒, 電信工程學研究所
gpa float Overall GPA. Any number between 0 and 4.3
target_schools List[string] A list of target schools, fullname or abbreviation are both acceptable. Example: [ Stanford, University of California, Berkeley, CMU, UofT]
target_programs List[string] A list of target programs. Example: [CS, MCS, MHCI, MITS, MSSE, PMP, Robotics]
program_types List[string] A list of target program types. We accept the following 6 program types: [CS, EE, SE, IS, HCI, MEng]
program_level string Target program level: MS or PhD

Response

The response JSON should be pretty self-explanatory. The score indicates how well the article matches your query, the higher the better. The detailed API schemas is also documented here.

Example curl request

curl -X POST "https://ptt-studyabroad-api.herokuapp.com/admission" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{\"university\":\"NTU\", \"target_schools\": [\"MIT\",\"CMU\"], \
  \"target_programs\":[\"CS\"], \
  \"program_level\":\"PhD\"}"

Deployment

Deploy Locally

All the deployment is done in one line. Visit localhost:5000 to see the results.

docker-compose up -d

If you would like to build and parse all the articles from scratch, set BUILD_FROM_SCRATCH to True in the settings.py file. Building from scratch takes around a minute.

Deploy on Heroku

We use the heroku-postgresql addon as our database

heroku apps:create ptt-studyabroad-api
heroku addons:create heroku-postgresql:hobby-dev
heroku stack:set container
git push heroku master:master

Built With

  • FastAPI - Modern, fast framework for building APIs
  • PostgreSQL - Relational database that comes in handy
  • docker-compose - For multi-container Docker applications
  • heroku.yml - New feature from Heroku to build Docker Images with self defined manifest

TODO

*Note: The API is still under development, so some information parsing may be incorrect. If the quarantine ends I maybe won't have that much time to work on these TODOs...

  • Refactor code (Too much special cases to deal with, the code is kinda ugly...)
  • Add background workers that parse new articles from PTT
  • Exclude some large files from GitHub
  • Improve keyword extraction
  • Add other APIs (such as college decision articles)

License

This project is licensed under the GPLv3 License - see the LICENSE.md file for details.

Acknowledgments