SchoolSpring Jobs API.

from urllib.parse import urlparse, parse_qs

RESERVED = {"www", "api", "employer"}

def parse_schoolspring(url: str) -> dict:
    parsed = urlparse(url)
    labels = parsed.netloc.lower().split(".")
    job_id = (parse_qs(parsed.query).get("jobId")
              or parse_qs(parsed.query).get("jobid") or [None])[0]

    if len(labels) != 3 or labels[1:] != ["schoolspring", "com"]:
        raise ValueError("not a SchoolSpring URL")

    tenant = labels[0]
    if tenant in RESERVED:
        # National /jobdetail links have no district in the URL — see step 5.
        return {"tenant": None, "job_id": job_id}
    return {"tenant": tenant, "job_id": job_id}

print(parse_schoolspring("https://huusd.schoolspring.com?jobid=5791873"))
# {'tenant': 'huusd', 'job_id': '5791873'}

import requests

API_BASE = "https://api.schoolspring.com/api"
PAGE_SIZE = 25

def listings_url(tenant: str, page: int) -> str:
    domain = f"{tenant}.schoolspring.com"
    return (
        f"{API_BASE}/Jobs/GetPagedJobsWithSearch?domainName={domain}"
        "&keyword=&location=&category=&gradelevel=&jobtype=&organization="
        "&swLat=&swLon=&neLat=&neLon="
        f"&page={page}&size={PAGE_SIZE}&sortDateAscending=false"
    )

def fetch_all(tenant: str, session: requests.Session) -> list[dict]:
    jobs, page = [], 1
    while True:
        resp = session.get(listings_url(tenant, page), timeout=30)
        resp.raise_for_status()
        payload = resp.json()

        if not payload.get("success"):
            raise RuntimeError(payload.get("message") or "listings API returned success=false")

        batch = (payload.get("value") or {}).get("jobsList") or []
        jobs.extend(batch)
        if len(batch) < PAGE_SIZE:
            return jobs
        page += 1

session = requests.Session()
listings = fetch_all("bsdvt", session)
print(f"{len(listings)} open jobs")

import time

def detail_url(job_id: str, domain: str) -> str:
    return f"{API_BASE}/Jobs/{job_id}?domainName={domain}"

def get_detail(tenant: str, job_id: str, session: requests.Session) -> dict | None:
    resp = session.get(detail_url(job_id, f"{tenant}.schoolspring.com"), timeout=30)
    if resp.status_code in (404, 410):
        return None  # canonical removal
    resp.raise_for_status()
    payload = resp.json()

    if not payload.get("success"):
        message = payload.get("message") or ""
        if "JobDetail not found" in message:
            return None  # structured removal signal, not a parse failure
        raise RuntimeError(message)

    info = (payload.get("value") or {}).get("jobInfo") or {}
    if str(info.get("jobId")) != str(job_id):
        raise RuntimeError("detail API returned a mismatched job")

    return {
        "id": info.get("jobId"),
        "title": info.get("jobTitle"),
        "employer": info.get("employerName"),
        "employer_id": info.get("employerID"),
        "description_html": info.get("jobDescription"),
        "job_type": info.get("jobTypeName"),
        "external_code": info.get("externalJobCode"),
        "posted_at": info.get("postDate"),
        "closes_at": info.get("closeDate"),
        "pay_min": info.get("payMin"),
        "pay_max": info.get("payMax"),
    }

for row in listings[:3]:
    print(get_detail("bsdvt", row["jobId"], session))
    time.sleep(0.1)

def resolve_board(job_id: str, session: requests.Session) -> str | None:
    resp = session.get(detail_url(job_id, "www.schoolspring.com"), timeout=30)
    resp.raise_for_status()
    payload = resp.json()
    if not payload.get("success"):
        return None

    value = payload.get("value") or {}
    if str((value.get("jobInfo") or {}).get("jobId")) != str(job_id):
        return None

    tenants = set()
    for board in value.get("jobBoards") or []:
        url = board.get("jobBoardUrl")
        if not url:
            continue
        try:
            parsed = parse_schoolspring(url)
        except ValueError:
            continue
        if parsed["tenant"]:
            tenants.add(parsed["tenant"])

    # Exactly one district, or the job is unattributable.
    return tenants.pop() if len(tenants) == 1 else None

print(resolve_board("5824140", session))

OTHER_K12_HOSTS = (
    "tedk12.com", "tedk12.ca",          # PowerSchool TalentEd Hire
    "applitrack.com",                    # Frontline / AppliTrack
    "atenterprise.powerschool.com",      # PowerSchool ATS Enterprise
)

def is_real_schoolspring(url: str) -> bool:
    host = urlparse(url).netloc.lower()
    if any(host.endswith(other) for other in OTHER_K12_HOSTS):
        return False
    return host == "www.schoolspring.com" or host.endswith(".schoolspring.com")

print(is_real_schoolspring("https://bsdvt.schoolspring.com"))              # True
print(is_real_schoolspring("https://alleganymd.tedk12.com/hire/index.aspx"))  # False