Open Syllabus API

# The primary interface is the web explorer:
# https://explorer.opensyllabus.org/

# Search by title, author, or field
# Filter by country, institution, discipline, year range

# API requires institutional subscription
# Base URL: https://api.opensyllabus.org/v1/

# Search titles
curl -H "Authorization: Bearer $OS_TOKEN" \
  "https://api.opensyllabus.org/v1/titles?query=republic+plato&limit=20"

# Get title details
curl -H "Authorization: Bearer $OS_TOKEN" \
  "https://api.opensyllabus.org/v1/titles/12345"

# Co-assignment analysis
curl -H "Authorization: Bearer $OS_TOKEN" \
  "https://api.opensyllabus.org/v1/titles/12345/co-assigned?limit=20"

# Rankings by field
curl -H "Authorization: Bearer $OS_TOKEN" \
  "https://api.opensyllabus.org/v1/rankings?field=Economics&limit=50"

import requests

BASE_URL = "https://api.opensyllabus.org/v1"


def search_titles(query: str, field: str = None,
                  country: str = None,
                  limit: int = 20, token: str = "") -> list:
    """Search Open Syllabus for assigned titles."""
    headers = {"Authorization": f"Bearer {token}"} if token else {}
    params = {"query": query, "limit": limit}
    if field:
        params["field"] = field
    if country:
        params["country"] = country

    resp = requests.get(
        f"{BASE_URL}/titles",
        headers=headers,
        params=params,
    )
    resp.raise_for_status()
    data = resp.json()

    results = []
    for item in data.get("results", []):
        results.append({
            "title": item.get("title"),
            "authors": item.get("authors"),
            "teaching_score": item.get("teaching_score"),
            "count": item.get("appearance_count"),
            "rank": item.get("rank"),
            "top_fields": item.get("top_fields", []),
        })
    return results


def get_co_assigned(title_id: int, limit: int = 20,
                    token: str = "") -> list:
    """Get titles frequently co-assigned with a given title."""
    headers = {"Authorization": f"Bearer {token}"} if token else {}
    resp = requests.get(
        f"{BASE_URL}/titles/{title_id}/co-assigned",
        headers=headers,
        params={"limit": limit},
    )
    resp.raise_for_status()
    return resp.json().get("results", [])


def get_field_rankings(field: str, limit: int = 50,
                       token: str = "") -> list:
    """Get most-taught titles in a field."""
    headers = {"Authorization": f"Bearer {token}"} if token else {}
    resp = requests.get(
        f"{BASE_URL}/rankings",
        headers=headers,
        params={"field": field, "limit": limit},
    )
    resp.raise_for_status()
    return resp.json().get("results", [])


# Example: find most-taught economics texts
# results = search_titles("microeconomics", field="Economics")
# for r in results:
#     print(f"#{r['rank']} {r['title']} — {r['authors']}")
#     print(f"  Teaching Score: {r['teaching_score']} "
#           f"({r['count']} syllabi)")