Continued from page 1.
If you inspect the Weather Underground's JSON response closely, you'll see that it offers the current temperature with three different key:value pairs virtually every human will understand:
"temperature_string":"57.9 F (14.4 C)", "temp_f":57.9, "temp_c":14.4,
In contrast, the OpenWeatherMap API offers the following key:value pair by default:
So, what's happening here? Whether celsius or fahrenheit, if the temperature in Union Square in San Francisco is 289.2, everyone there would be reduced to ashen cinder. That can't be right, can it?
For kicks, I switched the Content-Type for OpenWeatherMap's response from JSON to XML using the following URL string:
http://api.openweathermap.org/data/2.5/weather?zip=94107&mode=xml&APPID=<<David's API key for OpenWeatherMap>>
and here's what I got:
<current> <city id="5391959" name="San Francisco"> <coord lon="-122.42" lat="37.77"/> <country>US</country> <sun rise="2016-08-29T13:38:19" set="2016-08-30T02:41:22"/> </city> <temperature value="289.34" min="286.15" max="300.15" unit="kelvin"/> <humidity value="72" unit="%"/> <pressure value="1020" unit="hPa"/> <wind> <speed value="5.1" name="Gentle Breeze"/> <gusts/> <direction value="280" code="W" name="West"/> </wind> <clouds value="90" name="overcast clouds"/> <visibility/> <precipitation mode="no"/> <weather number="500" value="light rain" icon="10d"/> <lastupdate value="2016-08-29T16:42:03"/> </current>
Notice anything? More specifically, the following field for current temperature:
<temperature value="289.34" min="286.15" max="300.15" unit="kelvin"/>
When OpenWeatherMap returns the temperature as part of it's default JSON payload, it offers the current temperature, the minimum, and the maximum. But when you switch the OpenWeatherMap response to the optional XML payload, not only was the data organized differently, there was an additional field of data called "unit"" and it contained "kelvin"; a minor but important detail that's missing from the JSON payload.
In fairness to OpenWeatherMaps, its API documentation says that "kelvin" is the default temperature representation for API responses. To switch to fahrenheit or celsius, the following URL strings would work:
fahrenheit: http://api.openweathermap.org/data/2.5/weather?zip=94107&units=imperial&APPID=... celsius: http://api.openweathermap.org/data/2.5/weather?zip=94107&units=metric&APPID=...
Even so, Allen's point is not only easily made between different offerings within the "weather reports" subject matter domain (the offerings from OpenWeatherMap and Weather Underground are very different), it's literally made within the same physical domain (opendatamaps.org) where the data is a tad more easily interpreted in one format (XML) than the other (JSON). There's no reason the same informative bit of data (units) could not have been included in the JSON payload.
So, is this a big deal? Or a big to do about nothing? To the extent that there are subject matter schema standards like schema.org, I agree that the more API's can conform to those standards, the easier it will be for machines to deal with the dynamic nature of certain APIs. But for developers and humans, even though there's a lot to be said for great documentation, the aforementioned weather examples which took me an extra two minutes to figure out would not have impeded my progress as a developer. That said, at bare minimum, there's something to be said for offering a consistent schema across the various possible serializations like XML and JSON.