open_notify

Fetch information about spotting International Space Station from open-notify.org.

open_notify

...is a rust crate which lets you easily access current spotting information from open-notify.org. 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 ISS updates
    • First: Start polling
    • Then: Get ISS spotting updates
      • Nothing New: None
      • ISS spotting Update: Vec<Spot>
      • Some Error: Err
  • Get ISS spots 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]
open_notify = "0.1.7"

Get continuous ISS updates

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

extern crate open_notify;

use open_notify::{find_current, init, update};

fn main() {
    // start our observatory via OWM
    let receiver = &init(52.520008, 13.404954, 0.0, 90);
    loop {
        match update(receiver) {
            Some(response) => match response {
                Ok(spots) => println!(
                    "ISS is {}",
                    match find_current(spots,None) {
                        Some(_s) => "visible",
                        None => "invisible",
                    }
                ),
                Err(e) => println!("Could not fetch ISS spotting info because: {}", e),
            },
            None => (),
        }
    }
}

First: Start polling

init() spawns a thread which then will periodically poll api.open-notify.org for the current ISS position. You then can use update() to ask for it.

Then: Get ISS spotting 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 update for you.

ISS spotting Update: Vec<Spot>

If a new update was downloaded by the polling thread update() returns some Vec<Spot> object. Vec<Spot> includes a list of spotting events.

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 open_notify::LOADING).
• if a server error response was received (e.g. 500 Internal Server Error if an invalid API key was used).
• on json errors while parsing the response from api.open_notify.org.

Get ISS spots just once

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

extern crate open_notify;
use open_notify::blocking::spot;

fn main() {
    // start our observatory via OWM
    match &spot(52.520008, 13.404954, 0.0) {
        Ok(spots) => println!(
            "ISS is {}",
            match find_current(spots,None) {
                Some(_s) => "visible",
                None => "invisible",
            }
        ),
        Err(e) => println!("Could not fetch ISS spotting info because: {}", e),
    }
}

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

• The above example uses the synchronous (blocking) variant open_notify::blocking::spot which wont return until there is a new update.
• If you like to deal with the returned future by yourself just use open_notify::spot 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 open_notify.thats-software.com.

github repository

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

on crates.io

Published at crates.io.

License

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