Metadata-Version: 2.4
Name: univfyi
Version: 0.1.1
Summary: University rankings and programs API client — univfyi.com
Project-URL: Homepage, https://univfyi.com
Project-URL: Documentation, https://univfyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/univfyi
Project-URL: Issues, https://github.com/fyipedia/univfyi/issues
Project-URL: Changelog, https://github.com/fyipedia/univfyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: academic,admission,college,education,higher-education,program,ranking,university
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# univfyi

[![PyPI version](https://agentgif.com/badge/pypi/univfyi/version.svg)](https://pypi.org/project/univfyi/)
[![Python](https://img.shields.io/pypi/pyversions/univfyi)](https://pypi.org/project/univfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/univfyi/)

Python API client for [univfyi.com](https://univfyi.com/) -- the comprehensive university database covering rankings, programs, admissions data, and campus information across continents, countries, and regions. Access university profiles, ranking tiers, glossary terms, and educational guides through a free REST API, CLI, or MCP server for AI assistants.

[UnivFYI](https://univfyi.com/) catalogs universities worldwide with ranking data, program listings, admission requirements, and institutional profiles -- built for developers, students, counselors, and researchers who need structured higher education data.

> **Explore universities at [univfyi.com](https://univfyi.com/)** -- browse rankings, compare programs, and explore admission data by country.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/univfyi/main/demo.gif" alt="univfyi demo -- university rankings and programs API client for Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [University Rankings and Tiers](#university-rankings-and-tiers)
  - [Browse Universities by Region](#browse-universities-by-region)
  - [Admissions and Academic Resources](#admissions-and-academic-resources)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Universities](#learn-more-about-universities)
- [Guide FYI Family](#guide-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
pip install univfyi              # Core (zero deps)
pip install "univfyi[cli]"       # + Command-line interface
pip install "univfyi[mcp]"       # + MCP server for AI assistants
pip install "univfyi[api]"       # + HTTP client for univfyi.com API
pip install "univfyi[all]"       # Everything
```

## Quick Start

```python
from univfyi.api import UnivFYI

with UnivFYI() as api:
    # List universities in the database
    universities = api.list_universities()

    # Get detailed info for a specific university
    mit = api.get_university("massachusetts-institute-of-technology")

    # Browse ranking tiers
    tiers = api.list_tiers()

    # Search across all university content
    results = api.search("computer science")
```

## What You Can Do

### University Rankings and Tiers

Global university rankings evaluate institutions on research output, academic reputation, employer reputation, faculty-student ratio, international diversity, and citation impact. The three most recognized ranking systems -- QS World University Rankings, Times Higher Education (THE), and Academic Ranking of World Universities (ARWU/Shanghai) -- use different methodologies and weights.

| Ranking System | Publisher | Key Metrics | Coverage |
|---------------|-----------|-------------|----------|
| QS World University Rankings | Quacquarelli Symonds | Academic reputation (30%), employer reputation (15%), citations (20%) | 1,500+ universities |
| THE World University Rankings | Times Higher Education | Teaching (29.5%), research (29%), citations (30%) | 1,900+ universities |
| ARWU (Shanghai Ranking) | ShanghaiRanking | Nobel/Fields winners, highly cited researchers, Nature/Science papers | 1,000+ universities |
| US News Global | US News | Research reputation, publications, citations | 2,000+ universities |

```python
from univfyi.api import UnivFYI

# Explore university rankings and tiers
with UnivFYI() as api:
    tiers = api.list_tiers()
    top_tier = api.get_tier("world-top-50")

    # Browse universities within a tier
    universities = api.list_universities()
```

Learn more: [Browse Universities](https://univfyi.com/) · [Glossary](https://univfyi.com/glossary/) · [Guides](https://univfyi.com/guides/)

### Browse Universities by Region

Higher education systems differ significantly across regions. The US and UK use credit-hour and modular systems respectively, while the Bologna Process standardized European degrees into a three-cycle structure (bachelor's, master's, doctorate). Asian universities have seen the fastest ranking rises in the past decade.

| Region | System | Degree Structure | Notable Institutions |
|--------|--------|-----------------|---------------------|
| North America | Credit-hour, liberal arts GE | 4-year bachelor's + 2-year master's | MIT, Stanford, Harvard |
| United Kingdom | Modular, specialized from year 1 | 3-year bachelor's + 1-year master's | Oxford, Cambridge, Imperial |
| Europe (Bologna) | ECTS credits, standardized | 3-year bachelor's + 2-year master's | ETH Zurich, Sorbonne, TU Munich |
| East Asia | Credit-based, exam-oriented | 4-year bachelor's + 2-year master's | University of Tokyo, Tsinghua, NUS |
| Australia/NZ | Unit-based, flexible entry | 3-year bachelor's + 1.5-year master's | University of Melbourne, ANU |

```python
from univfyi.api import UnivFYI

# Browse universities by geographic region
with UnivFYI() as api:
    continents = api.list_continents()
    europe = api.get_continent("europe")

    countries = api.list_countries()
    uk = api.get_country("united-kingdom")

    regions = api.list_regions()
```

Learn more: [Browse Countries](https://univfyi.com/) · [Continents](https://univfyi.com/) · [API Docs](https://univfyi.com/developers/)

### Admissions and Academic Resources

University admissions processes vary by country and institution. US admissions consider standardized tests (SAT/ACT), GPA, essays, and extracurriculars holistically. UK admissions rely primarily on predicted A-level grades and personal statements through UCAS. Many European universities admit based on secondary school leaving exams.

| Test | Score Range | Used In | Purpose |
|------|-----------|---------|---------|
| SAT | 400 -- 1600 | US, some international | Undergraduate admission |
| ACT | 1 -- 36 | US | Undergraduate admission |
| GRE | 130 -- 170 per section | Worldwide | Graduate admission |
| GMAT | 200 -- 800 | Worldwide | MBA/business graduate |
| IELTS | 0.0 -- 9.0 | Worldwide | English proficiency |
| TOEFL | 0 -- 120 | Worldwide | English proficiency |

```python
from univfyi.api import UnivFYI

# Access glossary of higher education terms
with UnivFYI() as api:
    glossary = api.list_glossary()
    term = api.get_term("accreditation")

    # Browse glossary categories
    categories = api.list_glossary_categories()

    # Read guides on admissions and academic topics
    guides = api.list_guides()
    series = api.list_guide_series()
```

Learn more: [Glossary](https://univfyi.com/glossary/) · [Guides](https://univfyi.com/guides/) · [FAQs](https://univfyi.com/)

## Command-Line Interface

```bash
pip install "univfyi[cli]"

# Search for universities
univfyi search "Stanford engineering"

# Output is JSON for easy piping
univfyi search "computer science" | jq '.results[0]'
```

## MCP Server (Claude, Cursor, Windsurf)

Add university data tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).

```bash
pip install "univfyi[mcp]"
```

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "univfyi": {
            "command": "python",
            "args": ["-m", "univfyi.mcp_server"]
        }
    }
}
```

**Available tools**: `search_univfyi`

## REST API Client

```python
from univfyi.api import UnivFYI

with UnivFYI() as api:
    # List endpoints
    universities = api.list_universities()
    tiers = api.list_tiers()
    continents = api.list_continents()
    countries = api.list_countries()
    regions = api.list_regions()
    glossary = api.list_glossary()
    guides = api.list_guides()

    # Detail endpoints
    uni = api.get_university("oxford")
    tier = api.get_tier("world-top-100")

    # Search
    results = api.search("medicine")
```

## API Reference

| Method | Description |
|--------|-------------|
| `list_universities(**params)` | List all universities |
| `get_university(slug)` | Get university detail |
| `list_tiers(**params)` | List all ranking tiers |
| `get_tier(slug)` | Get tier detail |
| `list_continents(**params)` | List all continents |
| `get_continent(slug)` | Get continent detail |
| `list_countries(**params)` | List all countries |
| `get_country(slug)` | Get country detail |
| `list_regions(**params)` | List all regions |
| `get_region(slug)` | Get region detail |
| `list_glossary(**params)` | List glossary terms |
| `get_term(slug)` | Get glossary term detail |
| `list_glossary_categories(**params)` | List glossary categories |
| `get_glossary_category(slug)` | Get glossary category detail |
| `list_guides(**params)` | List all guides |
| `get_guide(slug)` | Get guide detail |
| `list_guide_series(**params)` | List guide series |
| `get_guide_sery(slug)` | Get guide series detail |
| `list_faqs(**params)` | List all FAQs |
| `get_faq(slug)` | Get FAQ detail |
| `search(query)` | Search across all content |

Full API documentation at [univfyi.com/developers/](https://univfyi.com/developers/).

## Learn More About Universities

- **Browse**: [Universities](https://univfyi.com/) · [Countries](https://univfyi.com/) · [Ranking Tiers](https://univfyi.com/)
- **Guides**: [Glossary](https://univfyi.com/glossary/) · [Guides](https://univfyi.com/guides/)
- **API**: [REST API Docs](https://univfyi.com/developers/) · [OpenAPI Spec](https://univfyi.com/api/openapi.json)

## Guide FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem -- life reference guides, calculators, education, and games.

| Package | PyPI | Description |
|---------|------|-------------|
| calcfyi | [PyPI](https://pypi.org/project/calcfyi/) | 200+ calculators, financial, health, math -- [calcfyi.com](https://calcfyi.com/) |
| salaryfyi | [PyPI](https://pypi.org/project/salaryfyi/) | Salary comparison, tax calculators, 36 countries -- [salaryfyi.com](https://salaryfyi.com/) |
| **univfyi** | [PyPI](https://pypi.org/project/univfyi/) | **University rankings, programs, admissions -- [univfyi.com](https://univfyi.com/)** |
| boardgamefyi | [PyPI](https://pypi.org/project/boardgamefyi/) | Board games, rules, reviews, recommendations -- [boardgamefyi.com](https://boardgamefyi.com/) |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies -- [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata -- [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats -- [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings -- [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS -- [fontfyi.com](https://fontfyi.com/) |
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | [npm](https://www.npmjs.com/package/distancefyi) | Haversine distance & travel times -- [distancefyi.com](https://distancefyi.com/) |
| timefyi | [PyPI](https://pypi.org/project/timefyi/) | [npm](https://www.npmjs.com/package/timefyi) | Timezone ops & business hours -- [timefyi.com](https://timefyi.com/) |
| namefyi | [PyPI](https://pypi.org/project/namefyi/) | [npm](https://www.npmjs.com/package/namefyi) | Korean romanization & Five Elements -- [namefyi.com](https://namefyi.com/) |
| unitfyi | [PyPI](https://pypi.org/project/unitfyi/) | [npm](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units -- [unitfyi.com](https://unitfyi.com/) |
| holidayfyi | [PyPI](https://pypi.org/project/holidayfyi/) | [npm](https://www.npmjs.com/package/holidayfyi) | Holiday dates & Easter calculation -- [holidayfyi.com](https://holidayfyi.com/) |
| **univfyi** | [PyPI](https://pypi.org/project/univfyi/) | -- | **University rankings, programs, admissions -- [univfyi.com](https://univfyi.com/)** |
| cocktailfyi | [PyPI](https://pypi.org/project/cocktailfyi/) | -- | Cocktail ABV, calories, flavor -- [cocktailfyi.com](https://cocktailfyi.com/) |
| fyipedia | [PyPI](https://pypi.org/project/fyipedia/) | -- | Unified CLI for all FYI tools -- [fyipedia.com](https://fyipedia.com/) |

## License

MIT
