Crate meteomatics

Expand description

Rust Meteomatics API connector: meteomatics

meteomatics is a native rust library that presents an easy interface for various types of queries to the Meteomatics weather and climate API (https://www.meteomatics.com/en/). The key functionality is based around the APIClient together with abstractions for location (Point) and grid (BBox) information. The APIClient exposes functions that allow to asynchronously request data from the API. The functions usually require some information about the time and place of the desired information. Based on the given information the client then builds the relevant query URL and handles the HTTP response appropriately.

Polars

Polars is a DataFrame library for Rust. It is based on Apache Arrow’s memory model. Apache arrow
provides very cache efficient columnar data structures and is becoming the defacto standard for 
columnar data.

Often times the HTTP response from the API can be converted to a polars DataFrame. These DataFrames allow fast and efficient data access and modification (see the examples for more details on this). For more information on polars itself please check https://docs.rs/polars/latest/polars/index.html.

Chrono

Time is represented using the chrono library’s DateTime and Duration features in the Utc timezone. This means that you either convert the requested time from your local time to Utc using Local and DateTime::from_utc() or that you directly create the time information using Utc.ymd().and_hms_micro(). More information about chrono can be found here https://docs.rs/chrono/latest/chrono/index.html.

use chrono::{DateTime, Local, Utc, TimeZone};
 
// This is a DateTime represented in the Local time zone.
let dt_local = Local.ymd(2014, 7, 8).and_hms_micro(15, 0, 0, 0);
// This creates a DateTime in the Utc time zone.
let dt_utc = DateTime::<Utc>::from_utc(dt_local.naive_utc(), Utc);
println!("Local: {} and corresponding Utc: {}.", dt_local.to_rfc3339(), dt_utc.to_rfc3339());

Overview

The example below illustrates how the information for the APIClient can be created using the Point abstraction together with information about the time and parameter (temperature 2 m above the ground). The time series runs from 1989-11-09T18:00:00.0Z to 1989-11-10T18:00:00.0Z in 12 hour steps. We can therefore expect temperature values for three points in time and a single point in space (lat: 52.52, lon: 13.405).

Parameters

The Meteomatics API provides an extensive list of weather parameters to chose from. A list of all available parameters can be found here https://www.meteomatics.com/en/api/available-parameters/alphabetic-list/.

use meteomatics::{APIClient, Point, TimeSeries};
use chrono::{Duration, Utc, TimeZone};
 
#[tokio::main]
async fn main(){
    // Credentials
    let api_key = "my_password";
    let api_user = "my_username";
 
    // Create client
    let client = APIClient::new(
        api_user,
        api_key,
        10, // < HTTP request timeout
    );
 
    // Time series specification
    let start_date = Utc.ymd(1989, 11, 9).and_hms_micro(18, 0, 0, 0);
    let time_series = TimeSeries {
        start: start_date,
        end: start_date + Duration::days(1),
        timedelta: Option::from(Duration::hours(12))
    };

    // Parameter selection
    let param = vec![String::from("t_2m:C")];

    // Location selection
    let coords = vec![Point { lat: 52.52, lon: 13.405 }];

    // Use API 
    let df = client
        .query_time_series(&time_series, &param, &coords, &None)
        .await
        .unwrap();
 
    println!("{:?}", df);
}

┌───────┬────────┬──────────────────────┬────────┐
│ lat   ┆ lon    ┆ validdate            ┆ t_2m:C │
│ ---   ┆ ---    ┆ ---                  ┆ ---    │
│ f64   ┆ f64    ┆ str                  ┆ f64    │
╞═══════╪════════╪══════════════════════╪════════╡
│ 52.52 ┆ 13.405 ┆ 1989-11-09T18:00:00Z ┆ 6.8    │
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 52.52 ┆ 13.405 ┆ 1989-11-10T06:00:00Z ┆ 1.4    │
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 52.52 ┆ 13.405 ┆ 1989-11-10T18:00:00Z ┆ 5.3    │
└───────┴────────┴──────────────────────┴────────┘

Re-exports

pub use client::APIClient;

pub use location::Point;

pub use location::BBox;

pub use util::TimeSeries;

Modules

Client

Location

Util

Structs

DataFrame

A contiguous growable collection of Series that have the same length.

DateTime

ISO 8601 combined date and time with time zone.

Duration

ISO 8601 time duration with nanosecond precision. This also allows for the negative duration; see individual methods for details.

Local

The local timescale. This is implemented via the standard time crate.

Utc

The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).