GLI Calculator Documentation

This documentation covers the use of the web based calculators for single- and multi-record/individual processing and use of the underlying RESTful API for programatic access.

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.

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.

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

Programatic Access API Documentation

For programatic access, use the RESTful API directly.

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 examples

You will need an API key to access the API, please click here to apply for a key. This key will give you access to 100,000 queries per month and will expire after 1 year.

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.

TLCO

Mandatory variables are:

variabledescriptiontyperange

These are listed in the order they appear in a submitted Excel file.

For each predicted output variable (M), the associated variability around the median (S) and the skewness (L) are output by the API but are excluded from the Excel output

variabledescription

Spirometry

Mandatory variables are:

variabledescriptiontyperange

These are listed in the order they appear in a submitted Excel file

For each predicted output variable (M), the associated variability around the median (S) and the skewness (L) are output by the API but are excluded from the Excel output

variabledescription

Lung Volume

Mandatory variables are:

variabledescriptiontyperange

These are listed in the order they appear in a submitted Excel file

For each predicted output variable (M), the associated variability around the median (S) and the skewness (L) are output by the API but are excluded from the Excel output

variabledescription

All

Mandatory variables are:

RE: ethnic. Note that TLCO and Volume calculations are based on Caucasian data only but your data for Spirometry will be returned based on the ethnicity value you provide

variabledescriptiontyperange

These are listed in the order they appear in a submitted Excel file

For each predicted output variable (M), the associated variability around the median (S) and the skewness (L) are output by the API but are excluded from the Excel output

variabledescription

API use cases

JavaScript
  $(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();
   });

  });
Please do not use this method on a public web page as this will expose your api-key
jQuery
  $(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 );
     }
    });

   });

  });
Please do not use this method on a public web page as this will expose your api-key
Perl
  #!/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";
Python
  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
  curl -i -X GET -H "x-api-key: [myAPI_key]" https://gli-api.ersnet.org/public/type/tlco/age/27/height/127/sex/m
R
  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