Single record Documentation

For single records, use the web based calculators.

Simply complete the form on the left of the page, submitting any measurements taken from the individual. Please see below for the mandatory input values for each calculator. You will be prompted if any of these are missing, or if any errors are encountered.

Usage notes

Please use fractional ages (to one decimal place) where possible for pediatric cases for more accurate calculations.

Note that for TLCO and Volume, ethnicity is not configurable as the calculations were derived from Caucasian data only. Thus all TLCO and Volume data are based on Caucasian ethnicity. For Spirometry, the data is calculated based on the ethnicity value you provide in the Spirometry input menu. For convenience, the ethnicity provided for Spirometry data calculations is updated at the bottom of the table and is visible in the output when the table data is printed using the "Print" button.

The calculator API will be accessed to perform the calculation and the results will appear in the table. You will be able to print the contents of the table or export the data in Excel or CSV format.

Multiple record Documentation

For multiple records, use the Excel file processing functionality.

Prepare your Excel file (.xls or .xlsx) with the mandatory and optional input values for your calculator of interest and upload to the dedicated input field on the left of the calculator page.

Note that the all endpoint (see below) is used for the Excel calculator and thus the mandatory variables to include in your Excel file are age, height, sex and ethnic. See the all documentation below for the optional input values. Ethnicity is a mandatory variable so that the calculations for Spirometry can be performed and your data for Spirometry will be returned based on the ethnicity value you provide on each row (see below for valid values). However, for TLCO and Volume, ethnicity is not configurable as the calculations were derived from Caucasian data only. Thus all TLCO and Volume data are based on ethnic=1 (Caucasian) regardless of the value you provide.

Usage notes

Please use fractional ages (to one decimal place) where possible for pediatric cases for more accurate calculations.

Either the first worksheet in your workbook will be searched for input values or if you name the worksheet containing your input data "calcData", then this worksheet will be preferentially used. Only the first 1000 records will be processed.

The calculator API will be accessed for each row of your file to perform the calculation and the results will appear in adjacent columns to your data in an Excel file that will be returned to you automatically. You should be able to find this in your usual Downloads folder or be prompted to save to a location of your choice. Any errors for each row of data will also be provided in this file. See below for the return order of the columns.

Note that for modern browsers such as Chrome, Firefox, Safari, IE 10+ and Edge no data will be written to the server, but for IE 9 and below a results file will be written but deleted after 24hrs

It should be noted that the Excel calculator does not adjust for partial pressure of oxygen or dead space, and measured values should be corrected prior to submitting your file for calculation of predicted values

Note that missing values on non-mandatory variables are replaced by zero in the output

Longitudinal Analysis Documentation

Please see the help on the Lung Tracker page for details on how to perform longitudinal analysis.

Programatic Access API Documentation

For programatic access, use the RESTful API directly.

You will need an API key to access the API, please click here for instructions on how to apply for a key.

The API can be accessed by any programming language that can submit a URL and process a returned JSON object.

There are a variety of languages that can be used to access the API and we provide some use cases below.

The API accepts GET requests to either retrieve calculation data or the full documentation (indeed this documentation page is partly compiled from a GET request to the API). These requests both return data in the form of JSON objects. See below for info on each endpoint.

We offer three affordable cost plans, each with a limit on the number of queries per month. All keys expire after 1 year.

If none of the above plans suit your needs, please contact us to discuss your requirements. We can make higher volume usage plans as well as POST method (current plans are based on GET requests) usage plans available.

Usage notes

Please use fractional ages (to one decimal place) where possible for pediatric cases for more accurate calculations.

Note that missing values on non-mandatory variables are replaced by zero in the output

The endpoints for the three calculators are tlco, spiro, volume and all. See the documentation below for all mandatory and optional variables and please note the reference to Ethnicity in the all endpoint.

To access the API use a GET request to https://gli-api.ersnet.org/public/type/<endpoint>/[remaining variables below as param/value/]

To access the API documentation use a GET request to https://gli-api.ersnet.org/public/docs

For either of the above you will need to provide your API key. See below use cases for how to do this.

API use cases

  $(document).ready(function(){
   var rest_url = "https://gli-api.ersnet.org/public/";
   var apikey = "[myAPI_key]";

   $("#clickme").click(function(){
    var xmlhttp = new XMLHttpRequest();
    xmlhttp.onreadystatechange = function() {
        if (this.readyState == 4 && this.status == 200) {
            var myObj = JSON.parse(this.responseText);
            console.log(myObj.tlcoM);
            // other fields can be populated here
        }
    };
    xmlhttp.open("GET", rest_url+"type/tlco/age/7/height/124/sex/m", true);
    xmlhttp.setRequestHeader("x-api-key", apikey);
    xmlhttp.send();
   });

  });

  $(document).ready(function(){
   var rest_url = "https://gli-api.ersnet.org/public/";
   var apikey = "[myAPI_key]";

   $("#clickme").click(function(){

    $.ajax({
     "url": rest_url+"type/tlco/age/7/height/124/sex/m",
     "method": "GET",
     "headers": {
        'x-api-key':apikey
     },
     "dataType": "json",
     "beforeSend": function(){
      // Handle the beforeSend event
      // Have somewhere on the page to store errors
      $("#errors").html("");
     },
     "complete": function(){
     },
     "success": function( myObj, textStatus, jqXHR ){
      // the object will either have errors in it or the contents of an API query
      // if errors
      if (myObj.errors == ""){
        $("#tlcoM").html(myObj.tlcoM);
      }
      else {
        $("#errors").html( myObj.errors );
      }
     },
     "error": function( jqXHR, textStatus, errorThrown ){
      alert( "Error detected when sending data\n" + textStatus + "\n" + errorThrown );
     }
    });

   });

  });

  #!/usr/bin/perl

  use strict;
  use REST::Client;
  use JSON;
  use Data::Dumper;

  my $client = REST::Client->new();
  my $rest_url = "https://gli-api.ersnet.org/public/";
  my $apikeyname = "x-api-key";
  my $apikey = "[myAPI_key]";

  $client->GET("$rest_url"."type/tlco/age/7/height/124/sex/m",{$apikeyname => $apikey});
  my $json = $client->responseContent();

  my $text = decode_json($json);
  print Dumper($text) . "\n";

  import requests
  import json

  rest_url = "https://gli-api.ersnet.org/public/"
  apikeyname = "x-api-key"
  apikey = "[myAPI_key]"
  params = "type/tlco/age/7/height/124/sex/m"
  headers = {apikeyname: apikey}
  r = requests.get(rest_url + params, headers=headers, verify=True)
  tlco = json.loads(r.text)
  tlco['tlcoM']

  curl -i -X GET -H "x-api-key: [myAPI_key]" https://gli-api.ersnet.org/public/type/tlco/age/27/height/127/sex/m

  library(httr)
  library(jsonlite)
  rest_url <- "https://gli-api.ersnet.org/public/"
  apikey <- "[myAPI_key]"
  response <- GET(paste0(rest_url,"type/tlco/age/7/height/124/sex/m"), add_headers("x-api-key" = apikey))
  tlco <- content(response, type="application/json")
  tlco$tlcoM