Life Expectancy

Once you have an API key, you can set up the MCP server for direct tool access from Claude Code, Cursor, or VS Code. See MCP_SETUP.md.

How It Works

import { SequoiaCodesClient } from "@sequoiaport/codes";

const client = new SequoiaCodesClient({
  apiKey: process.env.SEQUOIA_CODES_API_KEY!,
});

Available Operations

client.lifeExpectancy.lookupByAge({ age, gender? })

Get life expectancy for a specific age.

const result = await client.lifeExpectancy.lookupByAge({ age: 65 });
// result.result → { age_start: 65, gender: "total", ex: 19.09, qx: 0.01548, lx: 82565, ... }

Gender defaults to "total" (both sexes combined, per CMS WCMSA standard). Options: "male", "female", "total".

client.lifeExpectancy.lookupBatch({ ages, gender? })

Batch lookup for multiple ages in a single call.

const results = await client.lifeExpectancy.lookupBatch({
  ages: [30, 50, 65, 80],
  gender: "female",
});
// results.results → [{ age_start: 30, ex: 53.02, ... }, { age_start: 50, ex: 33.81, ... }, ...]

client.lifeExpectancy.getTable({ gender?, min_age?, max_age? })

Get the full actuarial life table or a filtered range.

// Full table (101 rows, ages 0-100)
const table = await client.lifeExpectancy.getTable({ gender: "total" });

// Filtered range
const seniors = await client.lifeExpectancy.getTable({
  gender: "male",
  min_age: 65,
  max_age: 85,
});

client.lifeExpectancy.getVersion()

Get metadata about the active life table dataset (NVSR volume, data year, source URL).

const version = await client.lifeExpectancy.getVersion();
// version.versions → [{ data_year: 2021, nvsr_volume: 75, nvsr_issue: 2, source_url: "...", ... }]

client.lifeExpectancy.getStats()

Get database statistics.

const stats = await client.lifeExpectancy.getStats();

client.lifeExpectancy.health()

Engine health check.

const health = await client.lifeExpectancy.health();
// health → { status: "healthy", engine: "life-expectancy", version: "1.0.0", database: { status: "ok", ... } }

REST API (curl)

# Lookup life expectancy at age 65
curl -X GET "https://api.sequoiacodes.com/v1/lifeExpectancy/lookupByAge?age=65&gender=total" \
  -H "Authorization: Bearer $SEQUOIA_CODES_API_KEY"

# Batch lookup
curl -X GET "https://api.sequoiacodes.com/v1/lifeExpectancy/lookupBatch?ages=[30,50,70]&gender=female" \
  -H "Authorization: Bearer $SEQUOIA_CODES_API_KEY"

# Full life table
curl -X GET "https://api.sequoiacodes.com/v1/lifeExpectancy/getTable?gender=total" \
  -H "Authorization: Bearer $SEQUOIA_CODES_API_KEY"

# Dataset version info
curl -X GET "https://api.sequoiacodes.com/v1/lifeExpectancy/getVersion" \
  -H "Authorization: Bearer $SEQUOIA_CODES_API_KEY"

Response Fields

Each life expectancy result includes:

• age_start - Age at start of interval (0-100)
• age_end - Age at end of interval (null for terminal "100 and older")
• gender - "male", "female", or "total"
• data_year - Year the data represents (e.g., 2021)
• source - Data source identifier
• qx - Probability of death between age_start and age_end
• lx - Number of survivors at age_start (out of 100,000 birth cohort)
• dx - Number of deaths between age_start and age_end
• lx_person_years - Person-years lived in the interval
• tx - Total person-years remaining above age_start
• ex - Life expectancy at age_start (in years)
• nvsr_volume - NVSR volume number (optional)
• nvsr_issue - NVSR issue number (optional)
• cms_reference - CMS reference identifier (optional)