Mystery Incorporated


Programming, photography, news, culture, and cartoons

home | rss | atom

Add to Google

Checking in with Kaiser Permanente’s API


March 16th, 2014 [programming]

kpHere’s a simple web app that uses data from the Kaiser Permanente API. Interchange by Kaiser Permanente offers a Location API with four functions you can query. I built the KP Explorer using the Get KP Facilities List call.

I had originally planned a more robust program to demo for the Transportation + Health meetup that was co-sponsored by Mobility Lab and Kaiser Permanente, but couldn’t get the API working in time, so this app doesn’t do much more than demonstrate that the API works.

The program uses geolocation to find your location, or you can enter a place in the search field, or just pan and zoom to a new location and hit “find facilities.” If you’re in one of the 9 states (plus DC) served by KP, you’ll see their facilities.

Like most APIs, the KP API requires the programmer to register and use a key with every query. This was the first time I used an API where the key was required to be hidden in an HTTP header parameter. For my PHP proxy script, I had to figure out how to do that. It turns out to be rather easy:

<?php
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, "https://api.kp.org/v1/locator/facility?" . $_SERVER['QUERY_STRING']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('consumer-key: YOURKEYHERE'));
echo curl_exec($ch);
curl_close($ch);
?>

By just passing along whatever parameters the proxy script gets, it leaves all the flexibility to the JavaScript program calling it. That code looks like:

var center = map.getCenter();  
xmlhttp = new XMLHttpRequest(); 
xmlhttp.open("GET", "http://mvjantzen.com/tools/kp/getfacilities.php?latitude=" + 
  center.lat() + "&longitude=" + center.lng());  
xmlhttp.onreadystatechange = function() {
  if (this.readyState == 4 && this.status == 200) 
    {postFacilitiesFromBounds(xmlhttp.responseText)}
  }; 
xmlhttp.send();

You can see the only parameters I’m sending are the coordinates for the center of the map. Unfortunately all of KP’s geographic searches are radius-based; it’s impossible to use a bounding box, so the zoom setting of the user’s map doesn’t affect what’s returned. (The default radius is 10 miles.) Last month I wrote why I prefer bounding-box searches: For Geo Searches, Radius: Bad; Box: Good. Though converting coordinates to distances is tricky (you need to use a projection), you could approximate a radius using the viewport’s diagonal.

Hovering over one of the KP icons reveals more information about that facility.

Once I got the API working, I wanted to make the map itself emphasize healthy options for getting to the facilities. I wanted to highlight transit and biking, and de-emphasize highways. I used the Styled Maps feature of the Google Maps JavaScript API to subtly change the map’s colors and features, removing the icons for highways.

var styles = [  
  {featureType: "all", stylers: [{lightness: 22, saturation: 16}]},
  {featureType: "poi.park", elementType: "geometry", stylers: [{color: "#98E398"}]},
  {featureType: "water", elementType: "geometry", stylers: [{color: "#00A8E3"}]},
  {featureType: "road", elementType: "geometry", stylers: [{color: "#FFFFFF"}]},
  {featureType: "road.highway", elementType: "labels.icon", stylers: [{visibility: "off"}]}
  ];

Then I decided to add icons for Metro stations and for Capital Bikeshare stations. Because this is just a demo, the information is static, so new stations aren’t automatically added. And of course the stations are useful only if you’re looking in the Washington, DC region. The KP Explorer was a fun exercise for mapping a new API, and perhaps it might be useful for KP’s customers.

2 Responses to “Checking in with Kaiser Permanente’s API”

  • Steven Vance says:

    Why did you use cURL and not file_get_contents($url)?

    I’m curious why they don’t have the API key as part of the URL like most APIs I use (which are mostly mapping and geocoding APIs).

    • admin says:

      I don’t think file_get_contents lets you modify the header, where the “consumer-key” parameter has to go. I think using the HTTP header is considered more secure because it’s not normally visible to the user. Though in this case, that wouldn’t be a problem, since the request goes from a proxy script to a server without a browser client.

  • Leave a reply



Site by M.V. Jantzen
mvs202 "at" gmail.com
twitter.com/mvs202