LED-BOARD/client/openweathermap/README.md

openweathermap

...is a rust crate which lets you easily access current weather data from OpenWeatherMap. This is an unofficial extension I have made to learn rust a little but I hope you have fun with it.

Contents

• Contents
• How to use
  • Get continuous weather updates
    • First: Start polling
    • Then: Get weather updates
      • Nothing New: None
      • Weather Update: CurrentWeather
      • Some Error: Err
  • Get weather just once
• Reference Documentation
• Links
  • Website
  • github repository
  • on crates.io
• License

How to use

First add this crate to your dependencies in you Cargo.toml file:

[dependencies]
openweathermap = "0.2.4"

Get continuous weather updates

Then use the crate in your rust source file by calling openweathermap::init() which returns a receiver object. You can then use this receiver object to call openweathermap::update() to get weather updates like in the following example:

extern crate openweathermap;

use openweathermap::{init,update};

fn main() {
    // start our observatory via OWM
    let receiver = &init("Berlin,DE", "metric", "en", "<APIKEY>", 10);
    loop {
        match update(receiver) {
            Some(response) => match response {
                Ok(current) => println!(
                    "Today's weather in {} is {}",
                    current.name.as_str(),
                    current.weather[0].main.as_str()
                ),
                Err(e) => println!("Could not fetch weather because: {}", e),
            },
            None => (),
        }
    }
}

First: Start polling

init() spawns a thread which then will periodically poll OpenWeatherMap for the latest current weather report. You then can use update() to ask for it.

Then: Get weather updates

There are three possible kinds of result you get from update() which you will have to face:

Nothing New: None

update() returns None if there is currently no new update available. Which means: You wont get any update twice! In other words: update() is not caching the last weather update for you.

Weather Update: CurrentWeather

If a new update was downloaded by the polling thread update() returns some CurrentWeather object. CurrentWeather is a nested struct with the already parsed json properties. Those are well described here.

Some Error: Err

On error update() returns some String object which includes a brief error description.

Errors may occur...

• initially while there is no update yet you will get an Err which includes exactly the String "loading..." (predefined in openweathermap::LOADING).
• if a server error response was received (e.g. 401 Unauthorized if an invalid API key was used).
• on json errors while parsing the response from OpenWeatherMap.

Get weather just once

If you need the weather just once you may use the method weather() which envelopes init() and update() into one single synchronous or asynchronous call. After the first successful weather update the spawned thread will stop immediately and you get the result in return.

extern crate openweathermap;
use openweathermap::blocking::weather;

fn main() {
    // start our observatory via OWM
    match &weather("Berlin,DE", "metric", "en", "<APIKEY>") {
        Ok(current) => println!(
            "Today's weather in {} is {}",
            current.name.as_str(),
            current.weather[0].main.as_str()
        ),
        Err(e) => println!("Could not fetch weather because: {}", e),
    }
}

There is a blocking and a non-blocking variant of weather():

• The above example uses the synchronous (blocking) variant openweathermap::blocking::weather which wont return until there is a new update.
• If you like to deal with the returned future by yourself just use openweathermap::weather and asynchronously await the result until there is any.

Reference Documentation

Beside this introduction there is a reference documentation which can be found here.

Links

Website

This README tastes better at openweathermap.thats-software.com.

github repository

For the source code see this repository at github.com.

on crates.io

Published at crates.io.

License

openweathermap is licensed under the MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)