PTT StudyAbroad API

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

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

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

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

• majors.csv is parsed from http://www.aca.ntu.edu.tw/curri/curs_deptabb.asp
• tw_universities.csv and us_universities_uids.csv are parsed from Wiki
• world_universities_and_domains.json is downloaded from Hipo/university-domains-ist
• All articles belong to PTT/StudyAbroad