API Documentation - Oncology Data to Lancet

Authentication

All API requests require authentication via API key or JWT token. Include the token in the Authorization header.

# API Key Authentication

curl -H "Authorization: Bearer olk_your_api_key" \

  https://api.oncology-lancet.com/v1/data/globocan/lung

Obtaining an API Key

import oncology

# Register and get API key

client = oncology.Client(email="researcher@university.edu")

api_key = client.generate_api_key(name="my-research-key")

print(api_key) # olk_...

Header	Value	Description
`Authorization`	`Bearer {api_key}`	Your API key or JWT token
`Content-Type`	`application/json`	Request body format
`Accept-Language`	`en` / `zh`	Response language (optional)

Base URL

All endpoints are relative to:

https://api.oncology-lancet.com/v1

Rate Limits

Free

100

requests/day

Pro

5,000

requests/day

Enterprise

Unlimited

dedicated infrastructure

Error Handling

The API uses standard HTTP status codes. All error responses follow this format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "cancer_type must be one of: lung, breast, colorectal, ...",
    "status": 400
  }
}

Status Code	Description
`200`	Success
`400`	Invalid request parameters
`401`	Invalid or missing authentication
`403`	Insufficient quota or permissions
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error

GLOBOCAN Data

GET /data/globocan/{cancer_type}

Fetch GLOBOCAN 2022 cancer statistics for a specific cancer type. Returns incidence, mortality, and prevalence by country with age-standardized rates.

Parameter	Type	Description
`cancer_type`	string	Cancer type: "lung", "breast", "colorectal", "prostate", "stomach", "liver", "thyroid", etc.
`year`	integer	GLOBOCAN edition year: 2018, 2020, or 2022 (default: 2022)
`countries`	string	Comma-separated ISO country codes (e.g., "US,CN,JP")
`region`	string	WHO region filter: "AFR", "AMR", "EMR", "EUR", "SEAR", "WPR"
`sex`	string	"male", "female", or "both" (default: "both")

{
  "cancer_type": "lung",
  "year": 2022,
  "total_cases": 2480301,
  "total_deaths": 1817050,
  "asr_incidence": 22.4,
  "asr_mortality": 18.3,
  "countries": [
    {
      "iso3": "CHN",
      "incidence": 812347,
      "mortality": 714522,
      "asr_i": 34.8,
      "asr_m": 30.1
    }
  ]
}

SEER Data

GET /data/seer/{cancer_type}

Fetch NCI SEER program data for US cancer statistics including survival trends and staging data.

Parameter	Type	Description
`cancer_type`	string	Cancer type code
`years`	string	Year range, e.g., "2000-2020"
`stage`	string	"localized", "regional", "distant", "all"
`demographic`	string	"race", "sex", "age_group"

Upload Dataset

POST /data/upload

Upload a custom CSV, Excel, or JSON dataset for analysis. The AI auto-detects cancer types, variables, and appropriate statistical methods.

curl -X POST "https://api.oncology-lancet.com/v1/data/upload" \

  -H "Authorization: Bearer olk_your_key" \

  -F "file=@my_data.csv" \

  -F "data_type=incidence"

Sample Data

GET /api/sample/{cancer_type}

Retrieve built-in sample data for demonstration. Available types: hcc, gastric, prostate, thyroid.

Create Analysis

POST /api/analysis

Submit a new epidemiological analysis pipeline with specified parameters.

{

  "project_id": "proj_abc123",

  "analysis_type": "trend",

  "parameters": {

    "method": "joinpoint",

    "confidence_level": 0.95,

    "standard_population": "world"

  }

}

analysis_type	Description
`paf`	Population Attributable Fraction calculation
`trend`	Trend analysis with joinpoint regression
`kaplan_meier`	Survival analysis with Kaplan-Meier curves
`cox_regression`	Cox proportional hazards regression
`meta_analysis`	Fixed/random effects meta-analysis
`forest_plot`	Forest plot generation
`funnel_plot`	Funnel plot for publication bias

Get Results

GET /api/analysis/{analysis_id}

Retrieve results from a completed analysis. Returns statistical results, figures, and metadata.

Statistical Tests

POST /api/analysis/paf

Calculate Population Attributable Fraction from exposure rate and relative risk.

POST /api/analysis/trend

Run trend analysis on time-series cancer data with joinpoint regression.

POST /api/analysis/meta-analysis

Perform fixed or random effects meta-analysis on multiple study results.

Survival Analysis

POST /api/analysis/kaplan-meier

Generate Kaplan-Meier survival curves with confidence intervals and log-rank tests.

POST /api/analysis/cox-regression

Fit Cox proportional hazards model with covariates. Returns hazard ratios and significance.

Generate Manuscript

POST /api/export/manuscript

Generate a Lancet-format manuscript from analysis results. Returns DOCX or LaTeX file.

Parameter	Type	Description
`project_id`	string	Project containing the analysis results
`format`	string	"docx", "latex", or "markdown"
`journal`	string	"lancet", "lancet_oncology", "lancet_gh"
`language`	string	"en" or "zh"

Export Figures

POST /api/export/figures

Export analysis visualizations in publication-ready format.

Parameter	Type	Description
`project_id`	string	Project ID
`format`	string	"tiff", "eps", "png", "svg"
`dpi`	integer	Resolution: 300 (default), 600

Download

GET /api/export/{export_id}/download

Download a generated export file by its ID.

The API docs are also available as interactive Swagger UI at /api/docs and ReDoc at /api/redoc when running the server locally.