bililite.com

pediatrics and medical informatics from the heart of the midwest

Welcome to the bililite.com webservices

Web services are web pages designed to be used by other websites, rather than viewed directly by users. The bililite.com web services evolved from the original bilirubin graph to allow generation of many of the graphs that pediatricians need, such as height, weight, peak flows, and, of course, bilirubin levels. For instance, /webservices/wt.png will give you a growth chart for weight that you can use as the source of an <img> element on your website. Options are part of the query string: /webservices/wt.png?birth=2/12/1998&sex=male&date[]=4/12/1998&data[]=8&date[]=1/15/2004&data[]=25 sets the birth date and plots two points (at 2 months and 6 years) of his weight.

The web services are designed to be RESTful, which means that all the information needed to get the resource (the image or the data) is contained in the URL. The URL always looks like http://bililite.com/webservices/graph-type.output-type?options.

Graph types

As an aside, I thought about adding EKG parameters, but those aren't usually graphed and there isn't good percentile data, just normal/abnormal. If you would like that, please contact me. For EKG interpretation, see the University of Chicago Pediatric Cardiology site, especially their Pediatric Electrocardiography page.

Output types

  • csv
  • gif
  • html
  • jpg
  • js
  • pdf
  • png
  • txt
  • xml

html shows a simple form for entering data. gif, jpg, and png return an image of the graph. png returns the best output, but Microsoft Internet Explorer older than version 8 doesn't handle it particularly well (there's a pale blue background), so you can use gif instead. jpg is included for completeness, but the image is blurry. txt returns a very terse text; just the computed zones for the data. csv returns a Comma-Separated Values file that represents the raw data for the zone lines. xml and js return the data and the computed zones as XML or JSON, respectively. pdf creates a simple PDF file of the graph that can be easily printed. It allows for many more options.

Zones are also plotted on the graphs, such as the "Low Risk Zone" on a bilirubin graph, "50-75 %ile" on a growth chart, or "Green Zone" on a peak flow graph.

For more sophisticated websites, the web services can also calculate the appropriate zone and return the data in XML or JSON format or plain text. For example, /webservices/bili.xml?birth=1/1/2009 4am&date[]=1/2/2009 6am&data[]=4&date[]=1/3/2009&data[]=10 returns an XML structure like:

  <?xml version="1.0" encoding="UTF-8" ?> 
  <bililite-webservices>
    <title>Risk of Hyperbilirubinemia</title> 
    <birth>1230800400</birth> 
    <points>
      <point>
        <time>1230894000</time> 
        <value>4</value> 
        <label>Low Risk</label> 
      </point>
      <point>
        <time>1230958800</time> 
        <value>10</value> 
        <label>Low Intermediate Risk</label> 
      </point>
    </points>
  </bililite-webservices>

And /webservices/bili.js?birth=1/1/2009 4am&date[]=1/2/2009 6am&data[]=4&date[]=1/3/2009&data[]=10 returns a JSON structure like (on one line; separated here for legibility):

{
  "title": "Risk of Hyperbilirubinemia",
  "birth": 1230800400,
  "points": [
    {
      "time": 1230894000,
      "value": 4,
      "label": "Low Risk"
    },
    {
      "time": 1230958800,
      "value": 10,
      "label": "Low Intermediate Risk"
    }
  ]
}

Adding a callback=functionName to the js options creates a JSONP call; /webservices/bili.js?callback=foo&birth=1/1/2009 4am&date[]=1/2/2009 6am&data[]=4&date[]=1/3/2009&data[]=10 returns:

foo({
  "title": "Risk of Hyperbilirubinemia",
  "birth": 1230800400,
  "points": [
    {
      "time": 1230894000,
      "value": 4,
      "label": "Low Risk"
    },
    {
      "time": 1230958800,
      "value": 10,
      "label": "Low Intermediate Risk"
    }
  ]
})

The numbers represent the UNIX timestamp of the date and time, which is the number of seconds since midnight January 1, 1970.

Options

There are many options available, most with reasonable defaults.

General options

birth and birth-time
The patient's birth date and time. The two fields are concatenated and passed to strtotime to determine the date/time. Strtotime is very sophisticated; just about any format or words works. It assumes the American format for dates; "1/3/2009" is interpreted as January 3, 2009, not 1 March 2009. "1.3.2009" does use the European format; it is 1 March 2009. "today", "yesterday", "9 years 7 months ago" work as expected. The last format is very useful for older children; a seventeen-year-old would have birth=17 years ago without having to remember his exact birthdate. Most graphs do not need the time of birth; only the bilirubin plot does.
birth and birth-time are separate fields for the convenience of users who want to use HTML forms with separate input boxes for time and date, similar to my original bilirubin form. birth=1/2/2009 6am, birth=1/2/2009&birth-time=6am, and birth-time=1/2/2009 6am are all completely identical.
The default is the current time (for our servers in New York).
date[], time[] and data[]
To plot data on the graph, use pairs of date[]=date string&data[]=nnn for each data point. Don't forget the [] after the keywords. I apologize for the similarity between date and data; I've made that typo myself. Each date[] and time[] are combined as with birth and birth-time above. Be consistent in a single URL; use date[] and time[] or both for each data point, or the program will become horribly confused.
These dates are relative to the birth date, so date[]=5 years will correctly get the date 5 years from birth. However, the specific terms now, today, yesterday and tomorrow and any string with next or ago will be relative to the current time. So /webservices/pf.txt?birth=9 years ago&date[]=yesterday&data[]=160&date[]=today&data[]=240 finds the peak flow zones for today and yesterday for a 9-year-old. The term birth is also recognized.
The default time is the current time; if the data is not set it is ignored.
datablob
As an alternate to date[], time[] and data[] arrays, all the data can be sent as a single text string (as would be sent with a <textare> element). The format is a list of newline-delimited pairs, each pair being a tab, comma or semicolon-delimited date and data. Note that a newline is URL encoded as %0A.
So /webservices/pf.txt?birth=9 years ago&datablob=yesterday,160%0Atoday,240 would give the same result as the previous example.

Graph options

General graph options
graph-only
Set this to only output the graph itself, without axis labels or title. Default: not set.
ages-only
Set this to use ages (birth, 1 year, 2 years) for the x-axis rather than dates. Useful for printing a general-use graph, not personalized for a specific patient. Default: not set.
base-color
CSS color for the background of the axis labels and the title. Default: transparent, except for gif output, when it is white (the anti-aliasing looks ugly otherwise).
title
Title for the graph. Default: set by the type of graph.
format
Size of the graph, in pixels, in the form '(x,y)'. The parentheses are mandatory and no spaces are allowed. Default: (765,500).
For convenience with forms, the format can be specified with two parameters, xsize and ysize, both in pixels.
The format can also be one of the following predefined formats:
a3
297 × 420 mm
a4
210 × 297 mm
a5
148 × 210 mm
letter
8.5 x 11 inch
legal
8.5 x 14 inch
3r
3.5 x 5 inch (photograph size)
passport
2 x 2 inch
You can append a '-L' to the names above to draw in landscape mode; thus format=letter-L is 11 x 8.5 inches.
margin
Size of the margin around the graph, in pixels. format gives the total size; margin reduces the graph drawn. Default: 0.
The margins may also be specified individually, as tmargin, rmargin, bmargin, and lmargin for top, right, bottom, and left margins respectively.
background-color
CSS color of the graph itself. Default: lightgray.
min
Value for the low end of the vertical axis. This may be adjusted to a "round number" but will always be included in the graph. Can be a number or auto for the program to find a value that includes all the lines and data. Default: 0.
max
Value for the high end of the vertical axis. This may be adjusted to a "round number" but will always be included in the graph. Can be a number or auto for the program to find a value that includes all the lines and data. Default: auto.
time-min
Date and time for the low end of the horizontal axis. This may be adjusted to a "round number" but will always be included in the graph. Default: birth.
time-max
Date and time for the high end of the horizontal axis. This may be adjusted to a "round number" but will always be included in the graph. Default: 18 years 6 months.
Grid lines
grid-color
CSS color of the grid lines. Default: darkgray.
grid-thickness
Thickness of the grid lines, in pixels. Default: 1.
Title
title-color
CSS color of the title text. Default: black.
title-font
Font name of the title. Default: DroidSans-Bold (DroidSans-Bold).
title-fontsize
Size of the title text, in points. Default: 12
Axis labels
axis-color
CSS color of the axis labels. Default: black.
axis-font
Font name of the axis labels. Default: DroidSans (DroidSans).
axis-fontsize
Size of the axis labels, in points. Default: 8
tics
Approximate number of "tics" (values shown) on the vertical axis. This is taken as a guide, an order of magnitude only. Default: 7.
time-tics
Approximate number of "tics" (values shown) on the horizontal axis. This is taken as a guide, an order of magnitude only. Default: 8.
Labels (the zones in the graph)
labelline-color
CSS color of the zone lines. Default: black.
labelline-thickness
Thickness of the zone lines, in pixels. Default: 1.
label-color
CSS color of the zone labels. Default: black.
label-font
Font name of the zone labels. Default: DroidSans (DroidSans).
label-fontsize
Size of the zone labels, in points. Default: 10
label-mark
URL of the marker at each point on the zone lines, or leave unset to not show any marker (the lines will still be drawn). Default: not set.
Data points
dataline-color
CSS color of the lines between data points. Default: transparent (lines are not drawn).
dataline-thickness
Thickness of the lines between data points, in pixels. Default: 1.
mark
URL of the marker at each point on the zone lines, or leave unset to not show any marker (the lines will still be drawn). Default: Orange Asterisk http://bililite.com/images/silk/asterisk_orange.png.
Ages

The horizontal axis shows actual dates and times. It is also useful to show the patient's age, so the upper border of the graph is labelled with the patient's age at regular intervals.

ageline-color
CSS color of the age-indicating lines. Default: rgba(255,165,0,.3) (almost transparent orange).
ageline-thickness
Thickness of the age-indicating lines, in pixels. Default: 1.
age-color
CSS color of the age text. Default: rgba(255,165,0,.7) (semi-transparent orange).
age-font
Font name of the age text. Default: DroidSans (DroidSans).
age-fontsize
Size of the age, in points. Default: 8
age-tics
Approximate number of ages shown. This is taken as a guide, an order of magnitude only. Default: 5.

Please contact me if you have any request or questions.