REST API

The micromort package includes a full REST API with 30 endpoints for accessing risk data programmatically. The API is built with plumber and returns JSON with a standard response envelope.

Getting Started

Launch the API from R:

library(micromort)
launch_api()
#> ── Micromort Data API ──
#> ℹ Starting server at http://127.0.0.1:8080
#> ℹ Swagger docs: http://127.0.0.1:8080/__docs__/

The interactive Swagger UI at /__docs__/ lets you explore all endpoints, view parameter descriptions, and try requests directly in the browser.

Response Envelope

Every endpoint returns a standard JSON envelope:

{
  "data": [ ... ],
  "meta": {
    "source": "micromort v0.4.0",
    "endpoint": "/v1/risks/acute",
    "n_rows": 10,
    "timestamp": "2026-03-09T12:00:00Z",
    "params": { "category": "Medical" }
  }
}

The data field contains the result (array or object). The meta field includes package version, endpoint path, row count, ISO 8601 timestamp, and the query parameters used.

Core Risk Data

Acute risks

Retrieve enriched acute risk data with optional filtering by category, minimum micromort threshold, and result limit.

curl "http://localhost:8080/v1/risks/acute?category=Medical&limit=10"

Show code

show_target("vig_api_acute_sample")

Chronic risks

Query chronic lifestyle factors that gain or lose microlives per day.

curl "http://localhost:8080/v1/risks/chronic?direction=gain"

Show code

show_target("vig_api_chronic_gains")

Cancer risks

Cancer mortality by type, sex, and age group with family history multipliers.

curl "http://localhost:8080/v1/risks/cancer?age_group=All%20ages"

Show code

show_target("vig_api_cancer_top3")

Risk Analysis

Risk equivalence

Find activities with equivalent risk to a reference activity. The response includes the ratio (how many of the reference activity equals one of each comparison activity).

curl "http://localhost:8080/v1/analysis/equivalence?reference=Chest+X-ray+(radiation+per+scan)"

Show code

show_target("vig_api_equivalence_sample")

Exchange matrix

Build a cross-comparison matrix for multiple activities. This is a POST endpoint that accepts a JSON body with an optional activities array:

curl -X POST "http://localhost:8080/v1/analysis/exchange-matrix" \
  -H "Content-Type: application/json" \
  -d '{"activities": ["Skiing", "Scuba diving, trained", "Skydiving (US)"]}'

Unit Conversion

Convert between probability, micromorts, microlives, and loss of life expectancy.

# Probability to micromorts
curl "http://localhost:8080/v1/convert/to-micromort?prob=0.000001"

# Micromorts to probability
curl "http://localhost:8080/v1/convert/to-probability?micromorts=1"

# Loss of life expectancy (minutes)
curl "http://localhost:8080/v1/convert/lle?prob=0.00001&life_expectancy=40"

# Monetary value of a micromort (default VSL = $10M)
curl "http://localhost:8080/v1/convert/value?vsl=10000000"

Show code

show_target("vig_api_conversion_table")

Age-Based Hazard Rates

Calculate daily micromort exposure from background mortality at any age, using Gompertz-Makeham mortality models.

curl "http://localhost:8080/v1/convert/hazard-rate?age=50&sex=female"

Show code

show_target("vig_api_hazard_ages")

Full Endpoint Reference

All 30 API endpoints with their HTTP method, path, description, and parameters:

Show code

show_target("vig_api_endpoint_summary")

Using from R

You can call the API from R using httr2:

Show code

library(httr2)

base_url <- "http://localhost:8080"

# GET request with query parameters
resp <- request(base_url) |>
  req_url_path("/v1/risks/acute") |>
  req_url_query(category = "Sport", limit = 5) |>
  req_perform() |>
  resp_body_json()

# The data lives in resp$data
tibble::as_tibble(do.call(rbind, lapply(resp$data, as.data.frame)))

# POST request with JSON body
resp <- request(base_url) |>
  req_url_path("/v1/analysis/exchange-matrix") |>
  req_body_json(list(
    activities = c("Skiing", "Scuba diving, trained")
  )) |>
  req_perform() |>
  resp_body_json()

Reproducibility

Show code

sessionInfo()
R version 4.5.2 (2025-10-31)
Platform: aarch64-apple-darwin24.6.0
Running under: macOS Tahoe 26.4.1

Matrix products: default
BLAS:   /nix/store/gf17x1bj3m732n39jznn6kz69szbr5rb-blas-3/lib/libblas.dylib 
LAPACK: /nix/store/5kg4z5bffhr8nry8bl8l5wlxvpy54dm2-openblas-0.3.30/lib/libopenblasp-r0.3.30.dylib;  LAPACK version 3.12.0

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

time zone: Europe/Belfast
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] DT_0.34.0       targets_1.11.4  micromort_0.2.0 testthat_3.3.1 

loaded via a namespace (and not attached):
 [1] gtable_0.3.6       bslib_0.9.0        xfun_0.55          ggplot2_4.0.1     
 [5] htmlwidgets_1.6.4  processx_3.8.6     callr_3.7.6        crosstalk_1.2.2   
 [9] vctrs_0.6.5        tools_4.5.2        ps_1.9.1           generics_0.1.4    
[13] base64url_1.4      tibble_3.3.0       pkgconfig_2.0.3    data.table_1.18.0 
[17] checkmate_2.3.3    secretbase_1.0.5   RColorBrewer_1.1-3 S7_0.2.1          
[21] desc_1.4.3         assertthat_0.2.1   lifecycle_1.0.4    compiler_4.5.2    
[25] farver_2.1.2       credentials_2.0.3  brio_1.1.5         codetools_0.2-20  
[29] sass_0.4.10        htmltools_0.5.9    sys_3.4.3          usethis_3.2.1     
[33] yaml_2.3.12        jquerylib_0.1.4    pillar_1.11.1      openssl_2.3.4     
[37] cachem_1.1.0       tidyselect_1.2.1   digest_0.6.39      dplyr_1.1.4       
[41] purrr_1.2.0        arrow_22.0.0       rprojroot_2.1.1    fastmap_1.2.0     
[45] grid_4.5.2         cli_3.6.5          magrittr_2.0.4     pkgbuild_1.4.8    
[49] withr_3.0.2        prettyunits_1.2.0  scales_1.4.0       backports_1.5.0   
[53] bit64_4.6.0-1      rmarkdown_2.30     igraph_2.2.1       bit_4.6.0         
[57] otel_0.2.0         askpass_1.2.1      evaluate_1.0.5     knitr_1.51        
[61] rlang_1.1.6        gert_2.2.0         Rcpp_1.1.0         glue_1.8.0        
[65] pkgload_1.4.1      jsonlite_2.0.0     R6_2.6.1           fs_1.6.6          
[69] units_1.0-0