# Connectors `seer` (SEER API, credential-gated) and `seer-explorer` (SEER*Explorer exports)

Documentation verified **2026-09-08**.

## 1. What the SEER API actually offers

<https://api.seer.cancer.gov/> — "The SEER API is a RESTful Web service that supports various SEER Program data sets and mapping. This service is available to developers who wish to incorporate SEER resources into their own systems. These resources include databases and tools developed to enhance registry operations and quality improvement. The SEER API is designed for integration into registry computer systems and is not designed to be accessed by end-users." Recent changes: "July 11, 2025 Transitioned to Login.gov for authentication".

OpenAPI definition <https://api.seer.cancer.gov/v3/api-docs> (93 paths): tags `rx` (Antineoplastic drugs database), `glossary`, `ndc`, `mph` (Multiple Primary and Histology Coding Rules), `recode` (Recode algorithms: `/rest/recode/sitegroup/algorithms`, `/rest/recode/sitegroup/{algorithm}?site&hist&behavior`), `surgery`, `disease` (Hematopoietic, lymphoid neoplasms and solid tumor diseases), `staging`, `hcpcs`, `naaccr`. Security scheme: `{"apiKeyScheme":{"type":"apiKey","name":"X-SEERAPI-Key","in":"header"}}`.

**There is no endpoint exposing population statistics** (incidence, mortality, survival, SEER\*Explorer views). The API is registry tooling only.

Usage page <https://api.seer.cancer.gov/usage>: header `X-SEERAPI-Key: YOURAPIKEY` (preferred); query `api_key=` "is a less secure way of passing the API key … should only be used for testing purposes"; "The current rate limit is 5000 API calls per hour per account." with `X-RateLimit-Limit/Remaining/Reset` headers, HTTP 429 when exceeded.

Terms <https://api.seer.cancer.gov/terms>: "You agree that any Applications utilizing the SEER APIs will include appropriate acknowledgement of SEER's contribution to the Application"; "You shall not assert any proprietary rights to any portion of the datasets in the SEER APIs, or represent the dataset or any part thereof to anyone as other than a United States Government dataset."; "5000 API calls per 60 minute time period".

Unauthenticated probe (2026-09-08): `GET /rest/recode/sitegroup/algorithms` → HTTP 401 `{"message":"You must supply an API key"}`.

### Connector `seer`

- `credentialsMissing()` returns "SEER_API_KEY is not set — request a free key at https://api.seer.cancer.gov/ (Login.gov) and add it to .env" → the SDK marks the run `aborted`, cursor health `awaiting_credentials`, source status `awaiting_credentials` (verified on the private DB).
- With a key: `healthCheck` and `sync` call `GET /rest/recode/sitegroup/algorithms` with `X-SEERAPI-Key`, store the algorithm list as a source record (`recode_algorithms`) and set `dataset_version` to the algorithm versions. **No epidemiology rows are written** — the manifest lists no entities/metrics, so nothing tooling-related can ever be shown as statistics.
- Manifest: `access.type = rest`, `auth = api_key`, `licenseStatus = approved` (US Government dataset, acknowledgement required), `status = awaiting_credentials`.

## 2. SEER*Explorer — the statistics path

<https://seer.cancer.gov/statistics-network/explorer/> (application <https://seer.cancer.gov/statistics-network/explorer/application.html>). Statistics offered: SEER incidence (SEER 8/12/17/21/22 registries), U.S. mortality (NCHS), relative survival, prevalence, lifetime risk, by site, sex, race/ethnicity, age, year, stage. Each view has a **"Download data"** button (`button#dload-data`) that assembles `explorer_download.csv` in the browser from the visible tables (function `EXPLORER.DOWNLOAD.DATA.DOWNLOAD_MANAGER` in `j/seer-explorer.min.js`; suppressed cells exported as `^`). Release label embedded in the application: `oReleaseDate: new Date("April 22, 2026")`, `oUpdatedDate: new Date("June 22, 2026")`. Citation template: "SEER*Explorer: An interactive website for SEER cancer statistics [Internet]. Surveillance Research Program, National Cancer Institute; <release date>. [updated: …; cited …]. Available from: https://seer.cancer.gov/statistics-network/explorer/."

The application loads its numbers from internal PHP endpoints (`source/content_writers/*.php`) that are **not documented**; per CLAUDE.md §9 they are not used. Exports are made by a human operator in the UI and dropped into `data/import/seer-explorer/*.csv` (`SEER_EXPLORER_IMPORT_DIR` overrides).

Reuse: NCI policy <https://www.cancer.gov/policies/copyright-reuse> — "Unless otherwise indicated, all text within National Cancer Institute (NCI) products is free of copyright and may be reused without our permission." "Credit the National Cancer Institute as the source." (The page <https://seer.cancer.gov/about/terms.html> given in the task returns 404; SEER *research data* — case-level — are governed by <https://seer.cancer.gov/registries/terms.html> and a data use agreement, which do not apply to the aggregate statistics in SEER\*Explorer.) → `licenseStatus = approved`, `redistribution = attribution`, `accessLevel = open`.

### Export layout (verified on three real exports, 2026-09-08)

Obtained headlessly with Playwright from the public application (no login). Fixtures under `packages/connectors/src/connectors/seer/fixtures/`:

1. `explorer-lung-relative-survival-by-time.csv` — "Lung and Bronchus" / "SEER Relative Survival Rates by Time Since Diagnosis, 2000-2022" / "By Sex, All Races / Ethnicities, All Ages, All Stages"; header rows `"","Both Sexes","Both Sexes","Both Sexes","Female",…` and `"Time Since Diagnosis","Relative Survival (%)","Lower 95% C.I.","Upper 95% C.I.",…`; rows "Diagnosis", "1 year" … "10 years"; footnotes "Data Source:" → "-SEER Incidence Data, November 2025 Submission (1975-2023), SEER 21 registries [https://seer.cancer.gov/registries/terms.html] (excluding Illinois)."; "Methodology:" → "-The relative survival rates are calculated using monthly intervals."; last line "Created by https://seer.cancer.gov/statistics-network/explorer/ on Tue Sep 08 2026."
2. `explorer-lung-mortality-trends-apc.csv` — "Long-Term Trends in U.S. Age-Adjusted Mortality Rates, 1975-2024": tables "Regression Line Segment Trends (shown on graph)" and "Recent 5 and 10 Year Trends" (APC/AAPC, not observations); data source "-U.S. Mortality Data (1969-2024), National Center for Health Statistics, CDC."; methodology "-Rates are per 100,000 and are age-adjusted to the 2000 US Std Population (20 age groups - Census P25-1130)."
3. `explorer-lung-incidence-by-age.csv` — "SEER Incidence Rates by Age at Diagnosis, 2019-2023" (`^` suppressed cells).

### Connector `seer-explorer` mapping

- "Relative Survival Rates by Time Since Diagnosis" → `survival_observations`: `survival_type = relative`, `duration_months = 12·n` (row "5 years" → 60), `probability = % / 100` with CI, `diagnosis_period` from the title ("2000-2022"), `sex` from the group header, `stage = null`, `age_group = all`, `method` = "SEER*Explorer relative survival (monthly intervals; Ederer II expected survival) — <site definition>", `geography = united-states`, provenance `population` = "SEER 21 registries (excluding Illinois) (SEER registry areas, not the whole US population)", `dataset_version` = "SEER*Explorer — SEER Incidence Data, November 2025 Submission (1975-2023), SEER 21 registries (excluding Illinois).", `published_at` = "November 2025". `cohort_size` is not present in exports → null. Rows are replaced per (cancer, source, sex, duration, period) — the table has no unique index.
- By-year rate tables (first column "Year of Diagnosis"/"Year of Death", measures "Rate per 100,000", "Lower/Upper 95% C.I.", "Number of …") → `as_incidence_rate`/`as_mortality_rate` (+ counts). **Layout inferred from the application's label dictionary (`EXPLORER.DEFINES.VALUE_LABELS`), not yet confirmed on a real by-year export** — the views we could export headlessly produced APC tables. Marked clearly in code; a unit test covers the inferred shape.
- Trend, by-age and stage tables are recognized and skipped with a log line.
- Site labels → `explorer-sites.ts` aliases onto the USCS/SEER recode definitions (`cdc-uscs/sites.ts`); resolution through `cancer_codes` (`icd10`) with the declared relation; unknown labels → `unresolved_labels`.

Real run 2026-09-08 (two files): 30 relative-survival points for Lung and Bronchus (all/female/male × 1–10 years; 5-year all sexes 0.215 [0.214–0.216]), trend file skipped. Never present these as global; they describe SEER registry areas.

## Files

`packages/connectors/src/connectors/seer/{manifest.ts,index.ts,explorer-manifest.ts,explorer.ts,explorer-parse.ts,explorer-sites.ts,seer.test.ts,fixtures/*}`.