How Dynamic Personalization of API Documentation Improves the Developer Experience

When ProgrammableWeb gets wind of a new API or new activty on an existing API, I occasionally take some time out to get hands-on with it. And every now and then, I come across a feature -- sometimes a feature I've seen before -- that compels me to write an article like this one that's just a reminder of how it's often the little things that count when it comes to making API consumption so much easier for developers. Today, that API is the Planet OS API

The Planet OS API is remarkable in that it's an API that offers standard access -- based on a single API design -- to nearly 50 datasets that Planet OS curates from a diverse sent of international agencies that offer what can best be described as earth science data (though many have to do with the weather). For example, whereas one dataset is an Ocean Wave Model that comes from NOAA, another is an ocean surface current analysis that comes from NASA. According to Planet OS product marketing manager Annika Ljash, new datasets are added all the time. Across all datasets, "there are over 2,100 variables of high-quality climate, weather and oceanic data freely available for our users" Ljash told ProgrammableWeb.

To be clear, the specific data that's available from each API isn't exactly the same. Each API returns a completely different data set involving entirely different fields of data. Whereas one dataset might return five fields per record, another might return 10. But there's one API for accessing each dataset and that API accepts some standard query parameters that work across all datasets (for example, the latitude and longitude of the observation that you're hoping to access). There's metadata that goes along with each dataset and the API offers a standard way for requesting that too. Included in that metadata for a given dataset is a list of fields that are available in that dataset and subsequent API calls can filter the response down to one or more specific fields per record. Like any nicely designed API, the Planet OS API offers pagination controls in the form of fields such as count (the number of records to retrieve with each call) and offset (where, relative to the beginning of the database to pick off the next group of records). 

But there were a couple of features of Planet OS' developer portal that I really like to see in other portals. Both were based on my identity and the Planet OS website knows who I am when I arrive because in order to use the free tier of the API, I had to register as a user of the site. After registering, the site undoubtedly issued a cookie to me so that it can read that cookie and recognize who I am on subsquent visits. Based on that identity management, it was able to offer me personalized help as I was bouncing around the developer portal. For example, one great feature that more developer portals should offer is some form of chat functionality so that developers can get immediate help from an API evangelist who works for the API provider. Not only does Planet OS offer that capability, as you can see from the screenshot below, it personalizes it by addresssing me as "David."  

Partial screenshot of PlanetOS developer portal showing personalized chat help

Is there some form of rocket science that makes this work? No. But is it a nice touch? Does it make me as a developer feel welcome in Planet OS's developer community? Does it make me feel help is only a few keystrokes away? You're damn right it does. But that's not all that Planet OS does to make my life easier as a developer. After signing-up as a registered user of, the site also issues me an API key. API keys are usually long strings of numbers and digits that have to be provided with every API request. In the earlier days of the API economy, API keys were an important part of an API's security.

Today, API keys are so easily discoverable that they cannot be relied on to prevent unauthorized access of an API. But they're great as unique identifiers for keeping track of which registered users like me are using an API, what parts of the API we're accessing, and how frequently we're accessing them. One of the great things about Planet OS's developer portal is that just about everywhere where an API key is shown as a parameter in a sample API call, the sample within the documentation includes my actual API key (sandwiched between the lat and lon parameters) instead of the obligatory placeholder (eg: "{api key}").  For example, the partial screenshot below of Planet OS's documentation for its dataset associated with NOAA's US East Coast WaveWatch data shows a functioning endpoint and query string.

Partial screenshot from developer portal that shows how example code in the documentation is prepopulated with API key and current longitude

What makes this great is how it already includes my actual API key (which I obfuscated for obvious reasons) which makes the entire string cuttable and directly pastable into my API calls whether they're run from my source code in a language like Javascript or Python, or from the cURL utility at my command prompt.

I was curious to know if Planet OS was using an off-the-shelf solution for these highly personalized samples since. "The dataset detail pages are created from scratch. We don't use any third-party libs there. It's a bit of Python and JavaScript" Planet OS developer evangelist Ilya Khamushkin told me via email. "We have a lightweight billing solution that integrates users and their API credentials, usage, etc. That is how we can pre-populate API keys for authenticated users. The long-term plan is to make this per-dataset sample query generator into an API Query Builder UI." 

Given how the fields of data vary from one data set to the other, that sort of innovation would of course be a very welcome addition to Planet OS's developer portal. For example, one of the standard query parameters that works across all data sets is the "var" parameter (short for "variable"). An example query string (sans my actual API key) shows this parameter in action with one of Planet OS's datasets:,water_v&apikey=Davids_API_Key

Take note of how my query string uses the "var" parameter to ask the API for just two of the fields available through this particular API; "salinity" and "water_v."  Unless you're a bit of domain expert with the sort of data that Planet OS deals with and you want to keep referring back to the dataset documentation to figure out all the fieldnames, building these sorts of queries can be laborious. But if Planet OS offers an interactive query builder of the sort that Khamushkin says is in the works, it make the developer portal that much more useful to developers who prefer not to test long complicated query strings out with their source code. 

One other opportunity for personalization that Planet OS could take advantage of is to automatically populate the query strings with a latitude and longitude that's relatively close to the user's current location (these details can be retrieved from the user's browser if the user explicity allows it). In fact, the prepopulated longitude that I observed in some of the sample query strings (using the variable "lon") was so close to my actual longitude that I thought this was what Planet OS was doing. But, as it turns out, it was purely coincidental. Khamushkin was quick to disabuse me of that assumption. 

Be sure to read the next API Design article: API Provider’s Checklist For API Endpoint, Resource, and Payload Planning


Comments (0)