SPB Git forge
spboucher.ai ↗

spb/cancerindex

Public
37commits 1branches 0releases
2.9 MBsize
maindefault branch
10 days agolast push
TypeScript 97.2% SQL 1.5% CSS 0.6% JavaScript 0.5%
8.6 KB
View source Raw Blame History

# 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; . [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 = "SEERExplorer relative survival (monthly intervals; Ederer II expected survival) — ", geography = united-states, provenance population = "SEER 21 registries (excluding Illinois) (SEER registry areas, not the whole US population)", dataset_version = "SEERExplorer — 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/*}.