Duration

20 minutes

Lab goals

The primary goal of this lab is to use the JSON type provider in the F# REPL to connect to a remote data source, extract and process specific data. The high level steps you will perform are:

1. Create a new F# library application (you'll be working with the script file).
2. Download FSharp Data using NuGet.
3. Load the JSON Type Provider with data from OpenWeatherMap.org.
4. Connect to the weather service and access to the weather data for your chosen city.
5. Convert temperatures from Kelvin to either Celsius or Fahrenheit.
6. Run your code in the REPL.

Steps

Create a new F# library application and add the F# Data package

1. Create a new F# library application.
2. Display the REPL (F# Interactive).
3. Add the FSharp.Data type provider package using NuGet. This will download the appropriate DLL file which we can then reference in our script.
4. Open the script.fsx file - this is where we will add our code.
5. Add a reference and open the FSharp.Data.dll library in your script file. Recall that you will use the r# command to add the reference to the script.
6. Open the System.Net namespace which contains the JSON Type Provider.

Show Code

// Note the below path might be different in your environment
#r "./packages/FSharp.Data.2.3.0/lib/net40/FSharp.Data.dll"

open FSharp.Data
open System.Net

Load the JSON Type Provider

1. Visit http://openweathermap.org/appid to obtain a new API key. You will need the new details in order to use the Type Provider
2. Create a new type alias for the provider. Use the JsonProvider<> type and pass a reference URL for the weather service including the api key you obtained from openweathermap.org. This provides example data to the JSON Type Provider.
   

   type Weather = JsonProvider<"http://api.openweathermap.org/data/2.5/weather?q=Sydney&APPID=<apikey>">

Read the weather data

1. Open a browser to the reference implementation location http://api.openweathermap.org/data/2.5/weather?q=Sydney&APPID=<apikey> and examine the structure to understand what data will be imported. This will be helpful when you are working with the provider, and will help you appreciate just how much work the type provider does for you.
2. Next, create a function called displayWeather which will take a parameter city. city will be a string parameter, but it will be passed to the weather service as part of the URL, so will need to be URL encoded using the WebUtility.UrlEncode function to ensure it is in the correct format. Construct a string that appends the encoded city to "http://api.openweathermap.org/data/2.5/weather?q=Sydney&APPID=apikey".
3. Define a new value called info that retrieves the information from the Type Provider by calling the Weather.Load method passing in the constructed URL that includes the city.

Show Code

...

type Weather = JsonProvider<"http://api.openweathermap.org/data/2.5/weather?q=Sydney&APPID=apikey">

let displayWeather city = 
    let encodedCity = WebUtility.UrlEncode(city)
    let info = Weather.Load("http://api.openweathermap.org/data/2.5/weather?q=" + encodedCity + "&APPID=" + apiKey)

Display the weather data

The Type Provider you've created will provide you with plenty of information that is available that mirrors the structure diaplayed in JSON page in your browser.

1. In your displayWeather function, use printfn to display information about the location, and the current, minimum, and maximum temperatures. You can find more about the JSON data structure at the Open Weather Map API page.
2. Call displayWeather passing a city of your choice. The code below uses "New York".
3. Select the code and press Ctrl+Enter to run it in the REPL environment.

Show Code

...
let displayWeather city = 
    let encodedCity = WebUtility.UrlEncode(city)
    let info = Weather.Load("http://api.openweathermap.org/data/2.5/weather?q=" + encodedCity + "&APPID=" + apiKey)
    printfn "The forecast for %s today is %s" info.Name info.Weather.[0].Main 
    printfn "The location is (%f, %f)" info.Coord.Lat info.Coord.Lon
    printfn "The temperature forecast is %.1f with a Min: %.1f and Max: %.1f" info.Main.Temp info.Main.TempMin info.Main.TempMax

displayWeather "New York"

Convert temperatures from Kelvin

All the temperatures returned from the weather service are in degrees Kelvin. We'll provide an appropriate conversion to either Fahrenheit or Celsius.
To convert from Kelvin to Celsius, subtract 273.15 from the Kelvin amount.
To convert from Kelvin to Fahrenheit, multiply the Kelvin amount by 1.8 (9/5) and then subtract 459.67 from the result.

1. Create a kelvinToCelsius function that accepts a single parameter and performs the conversion to Celsius.
2. Create a kelvinToFarenheit function that accepts a point parameter and performs the conversion to Fahrenheit.
3. Use the conversion function of your choice to convert the temperature data.
4. Select the code and press CTRL+ENTER to run it in the REPL environment. If you need some help, the entire completed script is shown below.

Show Code

#r "packages/FSharp.Data.2.3.0/lib/net40/FSharp.Data.dll"

open FSharp.Data
open System.Net

// You will need to sign-up to openweathermap.org in order to obtain an API key. 
// Replace all occurrances of  with the value you get from there
let apiKey = ""
  
type Weather = JsonProvider<"http://api.openweathermap.org/data/2.5/weather?q=Sydney&APPID=">

let kelvinToCelsius k = 
    (float k) - 273.15

let kelvinToFarenheit k = 
    (float k) * 9. / 5. - 459.67

let conversion = kelvinToCelsius

let displayWeather city = 
    let encodedCity = WebUtility.UrlEncode(city)
    let info = Weather.Load("http://api.openweathermap.org/data/2.5/weather?q=" + encodedCity + "&APPID=" + apiKey)
    printfn "The forecast for %s today is %s" info.Name info.Weather.[0].Main 
    printfn "The location is (%f, %f)" info.Coord.Lat info.Coord.Lon
    printfn "The temperature forecast is %.1f with a Min: %.1f and Max: %.1f" (conversion info.Main.Temp) (conversion info.Main.TempMin) (conversion info.Main.TempMax)

displayWeather "New York"

Additional Reading

There are various ways to measure temperature such as Kelvin, Celsius and Fahrenheit. These units are good candidates for using F#'s awesome feature: Units of Measure. Open the Script file in the Additional folder for the lab and exam the code. It shows an improved version using Units of Measure. Examine how the [<Measure>] attribute and the units are applied against the values from the REST service.

Show Code

#r "packages/FSharp.Data.2.3.0/lib/net40/FSharp.Data.dll"

open FSharp.Data
open System.Net

[<Measure>] type Kelvin
[<Measure>] type Celsius
[<Measure>] type Fahrenheit

let convertKelvintoCelsius (temp : float<Kelvin>) = 
    (temp / 1.0<Kelvin> - 273.) * 1.0<Celsius>

let convertKelvintoFahrenheit (temp : float<Kelvin>) = 
    (temp / 1.0<Kelvin> * 9. / 5. - 459.67) * 1.0<Fahrenheit>

// You will need to sign-up to openweathermap.org in order to obtain an API key. 
// Replace all occurrances of <apikey> with the value you get from there
let apiKey = "<apikey>"

let weatherForCityUrl city = 
    let encodedCity = WebUtility.UrlEncode(city)
    "http://api.openweathermap.org/data/2.5/weather?q=" + encodedCity + "&APPID=" + apiKey

type Weather = JsonProvider<"http://api.openweathermap.org/data/2.5/weather?q=Sydney&APPID=<apikey>">

let displayWeather city = 
    let info = Weather.Load(weatherForCityUrl city)

    // Change the following to convertKelvintoFahrenheit if thats your local UOM
    let convert = convertKelvintoCelsius

    let actualTemp = convert <| (float info.Main.Temp) * 1.0<Kelvin>
    let minTemp = convert <|(float info.Main.TempMin) * 1.0<Kelvin>
    let maxTemp = convert <|(float info.Main.TempMax) * 1.0<Kelvin>

    printfn "The forecast for %s today is %s" info.Name info.Weather.[0].Main 
    printfn "The details for today is %.1f with a Min: %.1f and Max: %.1f" (float actualTemp) (float minTemp) (float maxTemp) 
    printfn "The location is (%f, %f)" info.Coord.Lat info.Coord.Lon
 
displayWeather "New York"

Summary

During this lab you have gained experience connecting to the JSON type provider and extracting data from it.