USAJOBS Jobs API.

HOST = "www.usajobs.gov"

def board_url(agency_code: str) -> str:
    return f"https://{HOST}/Search/Results?a={agency_code.upper()}"

def job_url(control_number: str) -> str:
    return f"https://{HOST}/job/{control_number}"

# Four-character agency codes, not department names or display titles.
AGENCIES = {
    "AF34": "Air National Guard",
    "AF1L": "Air Mobility Command",
    "VATA": "Veterans Health Administration",
}

for code, name in AGENCIES.items():
    print(code, name, board_url(code))

import requests

SEARCH = f"https://{HOST}/Search/ExecuteSearch"
PAGE_SIZE = 100

session = requests.Session()
session.headers.update({
    "Accept": "application/json",
    "Content-Type": "application/json",
})

def search_page(agency_code: str, page: int) -> dict:
    resp = session.post(
        SEARCH,
        json={"Agency": [agency_code], "ResultsPerPage": PAGE_SIZE, "Page": page},
        headers={"Referer": board_url(agency_code)},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

payload = search_page("AF34", 1)
pager = payload["Pager"]
print(payload["Total"], "results across", pager["NumberOfPages"], "pages")

def fetch_agency(agency_code: str) -> list[dict]:
    jobs, page = [], 1
    while True:
        payload = search_page(agency_code, page)
        pager = payload.get("Pager") or {}
        batch = payload.get("Jobs") or []

        if pager.get("ItemsPerPage") != PAGE_SIZE:
            raise RuntimeError("search returned an unexpected page size")
        if pager.get("HasNextPage") != (page < pager.get("NumberOfPages", 0)):
            raise RuntimeError("Pager contradicted its own page count")

        if not batch:
            # An empty first page is authoritative only when everything agrees on zero.
            if page == 1 and str(payload.get("Total")) in ("0", "") and pager.get("NumberOfItems") == 0:
                return []
            raise RuntimeError("empty page while the pager still reports results")

        jobs.extend(batch)
        if not pager.get("HasNextPage"):
            return jobs
        page = pager["NextPageIndex"]

listings = fetch_agency("AF34")
print(f"{len(listings)} announcements")

def to_listing(row: dict, agency_code: str) -> dict:
    control_number = row.get("DocumentID")
    return {
        "id": control_number,
        "agency_code": agency_code,
        "agency": (row.get("Agency") or "").strip(),
        "department": row.get("Department"),
        "title": row.get("Title"),
        "position_id": row.get("PositionID"),
        "location": row.get("LocationDisplay") or row.get("LocationName"),
        "salary": row.get("SalaryDisplay"),
        "grade": row.get("JobGrade"),
        "grade_low": row.get("LowGrade"),
        "grade_high": row.get("HighGrade"),
        "schedule": row.get("WorkSchedule"),
        "work_type": row.get("WorkType"),
        "opens_at": row.get("PositionStartDate"),
        "closes_at": row.get("PositionEndDate"),
        "categories": [c.get("Name") for c in (row.get("JobCategoryCode") or [])],
        "listing_url": job_url(control_number),
    }

for row in listings[:3]:
    listing = to_listing(row, "AF34")
    print(listing["title"], "|", listing["grade"], "|", listing["location"])

import json
import time
from bs4 import BeautifulSoup

def agency_from_page(html: str) -> str | None:
    """The page's filter-query element carries the provider-owned agency code."""
    node = BeautifulSoup(html, "html.parser").select_one("#joaFilterQuery")
    if node is None or not node.get("value"):
        return None
    identity = json.loads(node["value"])
    agencies = identity.get("Agency") or []
    return agencies[0].strip() if len(agencies) == 1 else None

def hydrate(control_number: str, agency_code: str) -> dict | None:
    resp = session.get(job_url(control_number),
                       headers={"Accept": "text/html,application/xhtml+xml"}, timeout=30)
    if resp.status_code in (404, 410):
        return None                                  # canonical removal
    resp.raise_for_status()

    if agency_from_page(resp.text) != agency_code.upper():
        raise RuntimeError("announcement did not prove the requested agency")

    if '"ClockDisplay": "JobClosed"' in resp.text:
        return None                                  # structured unavailability

    soup = BeautifulSoup(resp.text, "html.parser")
    posting = None
    for tag in soup.find_all("script", type="application/ld+json"):
        try:
            data = json.loads(tag.string or "")
        except (json.JSONDecodeError, TypeError):
            continue
        for node in (data if isinstance(data, list) else [data]):
            if isinstance(node, dict) and node.get("@type") == "JobPosting":
                posting = node

    if posting is None:
        raise RuntimeError("announcement carried no JobPosting JSON-LD")

    return {
        "id": control_number,
        "title": posting.get("title"),
        "description_html": posting.get("description"),
        "posted_at": posting.get("datePosted"),
        "closes_at": posting.get("validThrough"),
        "listing_url": job_url(control_number),
    }

for row in listings[:3]:
    print(bool(hydrate(row["DocumentID"], "AF34")))
    time.sleep(0.1)