PhenoAge Calculator API

Calculate biological age using our PhenoAge API. This endpoint provides biological age assessments using advanced algorithms based on comprehensive biometric markers, offering insights into health status by comparing biological age to chronological age.

For practical use cases, read more about our PhenoAge Calculator. For clinical studies and scientific details, see the PhenoAge scientific foundation. Or read about our entire Biometric Calculator suite.

API Endpoint

Base URL

https://api.lincolncannon.co/biometric/calculate

Method

• POST - All calculations are performed via POST requests

Headers

Request Parameters

Parameter Notes

• Numeric Validation: All biometric values must be positive numbers and finite
• Backward Compatibility: Legacy parameter names continue to work alongside new standardized names
• Unit Consistency: All units match standard laboratory reporting conventions

Legacy Support

The PhenoAge API maintains full backward compatibility with existing implementations. Both new and legacy parameter names are supported:

New Parameter Names (Recommended):

• ALB for Albumin
• CR for Creatinine
• GLU for Glucose
• LYMPH_PERCENT for Lymphocyte percentage

Legacy Parameter Names (Still Supported):

• Albumin (maps to ALB)
• Creatinine (maps to CR)
• Glucose (maps to GLU)

• Lymph (maps to LYMPH_PERCENT)

• No Breaking Changes: Existing API calls will continue to work without modification
• Same Units: All units remain consistent with previous versions
• Enhanced Validation: Additional validation has been added while maintaining compatibility

Recommended Implementation

For new integrations, use the new standardized parameter names (ALB, CR, GLU, LYMPH_PERCENT) as shown in the table above. For existing integrations, no changes are required - your current implementation will continue to work seamlessly using the legacy parameter names.

Response Structure

Example Request

{
  "TestType": "PhenoAge",
  "BirthDate": "1974-12-01",
  "TestDate": "2024-01-31",
  "ALB": 4.5,
  "ALP": 85,
  "CR": 1.11,
  "CRP": 0.88,
  "GLU": 92,
  "LYMPH_PERCENT": 36,
  "MCV": 90,
  "RDW": 12.9,
  "WBC": 5.1
}

Legacy Parameter Example

For backward compatibility, you can also use the legacy parameter names:

{
  "TestType": "PhenoAge",
  "BirthDate": "1974-12-01",
  "TestDate": "2024-01-31",
  "Albumin": 4.5,
  "ALP": 85,
  "Creatinine": 1.11,
  "CRP": 0.88,
  "Glucose": 92,
  "Lymph": 36,
  "MCV": 90,
  "RDW": 12.9,
  "WBC": 5.1
}

Example Response

{
  "function": "LincolnCannonLLCBiometric-prod-calculate",
  "result": {
    "biological": 42.92,
    "chronological": 49.17,
    "difference": -6.25,
    "PhenoAge1": 41.7651318173571,
    "adjustedPhenoAge1": 41.34673188557684,
    "PhenoAge2": 43.38113049985819,
    "adjustedPhenoAge2": 42.92193734280278
  },
  "message": "For a person with the specified biometrics and test date, we calculated a chronological age of 49.17 years and an estimated biological age of 42.92 years, which differ by -6.25 years."
}

Implementation Examples

JavaScript Implementation

async function calculatePhenoAge(biometricData) {
    const requestBody = {
        TestType: "PhenoAge",
        ...biometricData
    };

    try {
        const response = await fetch('https://api.lincolncannon.co/biometric/calculate', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'x-api-key': process.env.API_KEY
            },
            body: JSON.stringify(requestBody)
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error calculating PhenoAge:', error);
        throw error;
    }
}

// Usage example
const phenoAgeData = {
    BirthDate: '1974-12-01',
    TestDate: '2024-01-31',
    ALB: 4.5,
    ALP: 85,
    CR: 1.11,
    CRP: 0.88,
    GLU: 92,
    LYMPH_PERCENT: 36,
    MCV: 90,
    RDW: 12.9,
    WBC: 5.1
};

const phenoAgeResult = await calculatePhenoAge(phenoAgeData);
console.log('Biological Age:', phenoAgeResult.result.biological);
console.log('Age Difference:', phenoAgeResult.result.difference);

Legacy Parameter Example

For backward compatibility, you can also use the legacy parameter names:

// Legacy parameter example
const phenoAgeDataLegacy = {
    BirthDate: '1974-12-01',
    TestDate: '2024-01-31',
    Albumin: 4.5,
    ALP: 85,
    Creatinine: 1.11,
    CRP: 0.88,
    Glucose: 92,
    Lymph: 36,
    MCV: 90,
    RDW: 12.9,
    WBC: 5.1
};

Python Implementation

import requests
import os

class PhenoAgeCalculator:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.lincolncannon.co/biometric/calculate"
        self.headers = {
            'Content-Type': 'application/json',
            'x-api-key': api_key
        }

    def calculate_pheno_age(self, biometric_data):
        """Calculate biological age using PhenoAge"""
        request_body = {
            "TestType": "PhenoAge",
            **biometric_data
        }

        try:
            response = requests.post(
                self.base_url,
                headers=self.headers,
                json=request_body
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"Error calculating PhenoAge: {e}")
            raise

# Usage example
calculator = PhenoAgeCalculator(os.getenv('API_KEY'))

pheno_data = {
    'BirthDate': '1974-12-01',
    'TestDate': '2024-01-31',
    'ALB': 4.5,
    'ALP': 85,
    'CR': 1.11,
    'CRP': 0.88,
    'GLU': 92,
    'LYMPH_PERCENT': 36,
    'MCV': 90,
    'RDW': 12.9,
    'WBC': 5.1
}

pheno_result = calculator.calculate_pheno_age(pheno_data)
print(f"Biological Age: {pheno_result['result']['biological']} years")
print(f"Age Difference: {pheno_result['result']['difference']} years")

Legacy Parameter Example (Python)

For backward compatibility, you can also use the legacy parameter names:

# Legacy parameter example
pheno_data_legacy = {
    'BirthDate': '1974-12-01',
    'TestDate': '2024-01-31',
    'Albumin': 4.5,
    'ALP': 85,
    'Creatinine': 1.11,
    'CRP': 0.88,
    'Glucose': 92,
    'Lymph': 36,
    'MCV': 90,
    'RDW': 12.9,
    'WBC': 5.1
}

Error Handling

Common Error Responses

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "BirthDate Is Invalid: BirthDate Is Required",
    "details": {
      "field": "BirthDate",
      "value": null
    }
  }
}

Specific Validation Errors

Authentication

API Key Requirements

All requests to the PhenoAge API require authentication using an API key:

1. Obtain API Key: Contact Lincoln Cannon LLC to receive your API key
2. Include in Headers: Add your API key to the x-api-key header

Security Best Practices

Support & Troubleshooting

Common Issues

Testing Your Integration

1. Validate Date Formats: Ensure all dates use YYYY-MM-DD format
2. Check Biometric Ranges: Verify biometric values are realistic and within expected ranges
3. Error Handling: Implement proper error handling for API responses
4. Unit Verification: Confirm all biometric values use the correct units

Getting Help

If you encounter issues with the PhenoAge API:

1. Check Documentation: Review this guide for parameter requirements
2. Validate Input Data: Ensure all required fields are provided with correct formats
3. Test with Sample Data: Use the provided examples to verify your implementation
4. Contact Support: Reach out to Lincoln Cannon LLC for technical assistance