Skip to main content

fauna_api/
maps.rs

1use chrono::{DateTime, Utc};
2use futures_util::StreamExt;
3use serde::{Deserialize, Serialize};
4use serde_json::json;
5
6use crate::authentification::CredentialsOrApiKey;
7use crate::error::Result;
8use crate::groups::Group;
9use crate::http::{client, encode, ok};
10
11#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
12pub struct Coordinates {
13    pub latitude: f64,
14    pub longitude: f64,
15}
16
17/// A place to start or end at: coordinates, an address, or a place id. Set one.
18#[derive(Debug, Clone, Default, Serialize, Deserialize)]
19pub struct Waypoint {
20    #[serde(default, skip_serializing_if = "Option::is_none")]
21    pub coordinates: Option<Coordinates>,
22    #[serde(default, skip_serializing_if = "Option::is_none")]
23    pub address: Option<String>,
24    #[serde(default, skip_serializing_if = "Option::is_none")]
25    pub place: Option<String>,
26}
27
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct Place {
30    pub id: String,
31    pub name: String,
32    pub address: String,
33    pub coordinates: Coordinates,
34}
35
36/// One autocomplete match. `place` resolves through `geocode` with a place waypoint.
37#[derive(Debug, Clone, Serialize, Deserialize)]
38pub struct Suggestion {
39    pub place: String,
40    pub name: String,
41    pub description: String,
42}
43
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
45#[serde(rename_all = "lowercase")]
46pub enum TravelMode {
47    Drive,
48    Walk,
49    Transit,
50    Flight,
51}
52
53#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
54pub struct Money {
55    pub amount: f64,
56    pub currency: String,
57}
58
59/// One instruction along a route. Transit steps also carry the line, stops and times.
60#[derive(Debug, Clone, Serialize, Deserialize)]
61pub struct Step {
62    pub mode: TravelMode,
63    pub instruction: String,
64    /// Meters.
65    pub distance: f64,
66    /// Seconds.
67    pub duration: f64,
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub line: Option<String>,
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub vehicle: Option<String>,
72    #[serde(default, skip_serializing_if = "Option::is_none")]
73    pub stops: Option<u32>,
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub from: Option<String>,
76    #[serde(default, skip_serializing_if = "Option::is_none")]
77    pub to: Option<String>,
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub departure: Option<DateTime<Utc>>,
80    #[serde(default, skip_serializing_if = "Option::is_none")]
81    pub arrival: Option<DateTime<Utc>>,
82}
83
84#[derive(Debug, Clone, Serialize, Deserialize)]
85pub struct Route {
86    pub mode: TravelMode,
87    /// Seconds.
88    pub duration: f64,
89    /// Meters.
90    pub distance: f64,
91    pub path: Vec<Coordinates>,
92    pub steps: Vec<Step>,
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub fare: Option<Money>,
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub departure: Option<DateTime<Utc>>,
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub arrival: Option<DateTime<Utc>>,
99}
100
101#[derive(Debug, Clone, Serialize, Deserialize)]
102pub struct Airport {
103    pub code: String,
104    pub name: String,
105    pub city: String,
106    pub country: String,
107    pub coordinates: Coordinates,
108    /// Meters from the point searched.
109    pub distance: f64,
110    pub large: bool,
111}
112
113#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
114#[serde(rename_all = "lowercase")]
115pub enum Units {
116    Metric,
117    Imperial,
118}
119
120#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
121#[serde(rename_all = "snake_case")]
122pub enum Condition {
123    Clear,
124    PartlyCloudy,
125    Cloudy,
126    Fog,
127    Rain,
128    Showers,
129    Thunderstorm,
130    Snow,
131    Sleet,
132    Hail,
133    Wind,
134    Unknown,
135}
136
137#[derive(Debug, Clone, Serialize, Deserialize)]
138pub struct ForecastDay {
139    /// The local date, YYYY-MM-DD.
140    pub date: String,
141    pub high: f64,
142    pub low: f64,
143    pub condition: Condition,
144    pub summary: String,
145    /// Chance of precipitation, 0 to 100.
146    pub precipitation: f64,
147    pub wind: f64,
148    #[serde(default, skip_serializing_if = "Option::is_none")]
149    pub sunrise: Option<DateTime<Utc>>,
150    #[serde(default, skip_serializing_if = "Option::is_none")]
151    pub sunset: Option<DateTime<Utc>>,
152}
153
154#[derive(Debug, Clone, Serialize, Deserialize)]
155#[serde(rename_all = "camelCase")]
156pub struct ForecastHour {
157    pub time: DateTime<Utc>,
158    pub temperature: f64,
159    pub feels_like: f64,
160    pub condition: Condition,
161    pub summary: String,
162    pub precipitation: f64,
163    pub wind: f64,
164}
165
166/// Temperatures in °C and wind in km/h for metric, °F and mph for imperial.
167#[derive(Debug, Clone, Serialize, Deserialize)]
168#[serde(rename_all = "camelCase")]
169pub struct Forecast {
170    pub units: Units,
171    pub time_zone: String,
172    pub days: Vec<ForecastDay>,
173    pub hours: Vec<ForecastHour>,
174}
175
176#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
177#[serde(rename_all = "lowercase")]
178pub enum MapTheme {
179    Light,
180    Dark,
181}
182
183/// What a map must show while its tiles are on screen.
184#[derive(Debug, Clone, Serialize, Deserialize)]
185pub struct Attribution {
186    pub text: String,
187    pub logo: String,
188}
189
190/// Prepaid map tiles. The pass id is all a tile request needs.
191#[derive(Debug, Clone, Serialize, Deserialize)]
192#[serde(rename_all = "camelCase")]
193pub struct TilePass {
194    pub id: String,
195    pub tiles: u32,
196    pub expires: DateTime<Utc>,
197    pub size: u32,
198    pub max_zoom: u32,
199    pub attribution: Attribution,
200}
201
202#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
203pub struct Bounds {
204    pub north: f64,
205    pub south: f64,
206    pub east: f64,
207    pub west: f64,
208}
209
210/// The `options` argument of `search_places`.
211#[derive(Debug, Clone, Copy, Default)]
212pub struct PlaceSearchOptions {
213    pub near: Option<Coordinates>,
214    pub radius: Option<f64>,
215    pub max: Option<u32>,
216}
217
218/// The `options` argument of `autocomplete`.
219#[derive(Debug, Clone, Copy, Default)]
220pub struct AutocompleteOptions {
221    pub near: Option<Coordinates>,
222}
223
224/// The `options` argument of `get_routes`.
225#[derive(Debug, Clone, Default)]
226pub struct RouteOptions {
227    pub modes: Option<Vec<TravelMode>>,
228    pub departure: Option<DateTime<Utc>>,
229    pub arrival: Option<DateTime<Utc>>,
230}
231
232/// The `options` argument of `get_airports`.
233#[derive(Debug, Clone, Copy, Default)]
234pub struct AirportOptions {
235    pub max: Option<u32>,
236    pub large: Option<bool>,
237}
238
239/// The `options` argument of `get_weather`.
240#[derive(Debug, Clone, Copy, Default)]
241pub struct WeatherOptions {
242    pub days: Option<u32>,
243    pub hours: Option<u32>,
244    pub units: Option<Units>,
245}
246
247/// The `options` argument of `create_tile_pass`.
248#[derive(Debug, Clone, Default)]
249pub struct TilePassOptions {
250    pub theme: Option<MapTheme>,
251    pub tiles: Option<u32>,
252    pub language: Option<String>,
253    pub region: Option<String>,
254}
255
256/// Find places for an address, coordinates (reverse lookup) or a place id.
257pub async fn geocode(
258    authorization: &CredentialsOrApiKey,
259    query: &Waypoint,
260    group: Option<&Group>,
261) -> Result<Vec<Place>> {
262    let mut request = client()
263        .post(format!("{}/maps/geocode", crate::get_url()))
264        .header(
265            "Authorization",
266            match authorization {
267                CredentialsOrApiKey::Credentials(credentials) => {
268                    format!("Token {}", credentials.token)
269                }
270                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
271            },
272        );
273    if let Some(group) = group {
274        request = request.header("Group", &group.id);
275    }
276    let response = request.json(&json!({ "query": query })).send().await?;
277    Ok(ok(response).await?.json().await?)
278}
279
280pub async fn search_places(
281    authorization: &CredentialsOrApiKey,
282    text: &str,
283    options: &PlaceSearchOptions,
284    group: Option<&Group>,
285) -> Result<Vec<Place>> {
286    let mut request = client()
287        .post(format!("{}/maps/places/search", crate::get_url()))
288        .header(
289            "Authorization",
290            match authorization {
291                CredentialsOrApiKey::Credentials(credentials) => {
292                    format!("Token {}", credentials.token)
293                }
294                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
295            },
296        );
297    if let Some(group) = group {
298        request = request.header("Group", &group.id);
299    }
300    let response = request
301        .json(&json!({
302            "text": text,
303            "near": options.near,
304            "radius": options.radius,
305            "max": options.max,
306        }))
307        .send()
308        .await?;
309    Ok(ok(response).await?.json().await?)
310}
311
312pub async fn autocomplete(
313    authorization: &CredentialsOrApiKey,
314    text: &str,
315    options: &AutocompleteOptions,
316    group: Option<&Group>,
317) -> Result<Vec<Suggestion>> {
318    let mut request = client()
319        .post(format!("{}/maps/places/autocomplete", crate::get_url()))
320        .header(
321            "Authorization",
322            match authorization {
323                CredentialsOrApiKey::Credentials(credentials) => {
324                    format!("Token {}", credentials.token)
325                }
326                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
327            },
328        );
329    if let Some(group) = group {
330        request = request.header("Group", &group.id);
331    }
332    let response = request
333        .json(&json!({ "text": text, "near": options.near }))
334        .send()
335        .await?;
336    Ok(ok(response).await?.json().await?)
337}
338
339/// Drive, walk and transit routes between two waypoints, one per mode that has
340/// one. Flights come from Travel.
341pub async fn get_routes(
342    authorization: &CredentialsOrApiKey,
343    from: &Waypoint,
344    to: &Waypoint,
345    options: &RouteOptions,
346    group: Option<&Group>,
347) -> Result<Vec<Route>> {
348    let mut request = client()
349        .post(format!("{}/maps/routes", crate::get_url()))
350        .header(
351            "Authorization",
352            match authorization {
353                CredentialsOrApiKey::Credentials(credentials) => {
354                    format!("Token {}", credentials.token)
355                }
356                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
357            },
358        );
359    if let Some(group) = group {
360        request = request.header("Group", &group.id);
361    }
362    let response = request
363        .json(&json!({
364            "from": from,
365            "to": to,
366            "modes": options.modes,
367            "departure": options.departure,
368            "arrival": options.arrival,
369        }))
370        .send()
371        .await?;
372    Ok(ok(response).await?.json().await?)
373}
374
375/// The nearest airports with scheduled flights, closest first. Free.
376pub async fn get_airports(
377    authorization: &CredentialsOrApiKey,
378    near: &Coordinates,
379    options: &AirportOptions,
380) -> Result<Vec<Airport>> {
381    let response = client()
382        .post(format!("{}/maps/airports", crate::get_url()))
383        .header(
384            "Authorization",
385            match authorization {
386                CredentialsOrApiKey::Credentials(credentials) => {
387                    format!("Token {}", credentials.token)
388                }
389                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
390            },
391        )
392        .json(&json!({ "near": near, "max": options.max, "large": options.large }))
393        .send()
394        .await?;
395    Ok(ok(response).await?.json().await?)
396}
397
398/// Daily (up to 10) and hourly (up to 240) forecasts for a point.
399pub async fn get_weather(
400    authorization: &CredentialsOrApiKey,
401    at: &Coordinates,
402    options: &WeatherOptions,
403    group: Option<&Group>,
404) -> Result<Forecast> {
405    let mut request = client()
406        .post(format!("{}/maps/weather", crate::get_url()))
407        .header(
408            "Authorization",
409            match authorization {
410                CredentialsOrApiKey::Credentials(credentials) => {
411                    format!("Token {}", credentials.token)
412                }
413                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
414            },
415        );
416    if let Some(group) = group {
417        request = request.header("Group", &group.id);
418    }
419    let response = request
420        .json(&json!({
421            "at": at,
422            "days": options.days,
423            "hours": options.hours,
424            "units": options.units,
425        }))
426        .send()
427        .await?;
428    Ok(ok(response).await?.json().await?)
429}
430
431/// Buy a pass for `tiles` map tiles (default 150). Tiles are billed up front,
432/// when the pass is bought.
433pub async fn create_tile_pass(
434    authorization: &CredentialsOrApiKey,
435    options: &TilePassOptions,
436    group: Option<&Group>,
437) -> Result<TilePass> {
438    let mut request = client()
439        .post(format!("{}/maps/tiles/pass", crate::get_url()))
440        .header(
441            "Authorization",
442            match authorization {
443                CredentialsOrApiKey::Credentials(credentials) => {
444                    format!("Token {}", credentials.token)
445                }
446                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
447            },
448        );
449    if let Some(group) = group {
450        request = request.header("Group", &group.id);
451    }
452    let response = request
453        .json(&json!({
454            "theme": options.theme,
455            "tiles": options.tiles,
456            "language": options.language,
457            "region": options.region,
458        }))
459        .send()
460        .await?;
461    Ok(ok(response).await?.json().await?)
462}
463
464/// A tile URL template with `{z}`, `{x}` and `{y}` left in, the way map libraries take them.
465pub fn get_tile_url(pass: &TilePass) -> String {
466    format!(
467        "{}/maps/tile?pass={}&z={{z}}&x={{x}}&y={{y}}",
468        crate::get_url(),
469        encode(&pass.id)
470    )
471}
472
473/// One map tile image, read as it streams in.
474pub async fn get_tile(
475    pass: &TilePass,
476    z: u32,
477    x: u32,
478    y: u32,
479    on_loaded: Option<impl Fn(u64)>,
480) -> Result<Vec<u8>> {
481    let response = client()
482        .get(format!(
483            "{}/maps/tile?pass={}&z={z}&x={x}&y={y}",
484            crate::get_url(),
485            encode(&pass.id)
486        ))
487        .send()
488        .await?;
489    let response = ok(response).await?;
490
491    let mut buffer = Vec::new();
492    let mut loaded = 0u64;
493    let mut body = response.bytes_stream();
494    while let Some(chunk) = body.next().await {
495        let chunk = chunk?;
496        loaded += chunk.len() as u64;
497        buffer.extend_from_slice(&chunk);
498        if let Some(on_loaded) = &on_loaded {
499            on_loaded(loaded);
500        }
501    }
502    Ok(buffer)
503}
504
505/// The attribution for what a map shows right now. Free; call it as the view moves.
506pub async fn get_attribution(pass: &TilePass, zoom: u32, bounds: &Bounds) -> Result<Attribution> {
507    let response = client()
508        .get(format!(
509            "{}/maps/tiles/attribution?pass={}&zoom={zoom}&north={}&south={}&east={}&west={}",
510            crate::get_url(),
511            encode(&pass.id),
512            bounds.north,
513            bounds.south,
514            bounds.east,
515            bounds.west
516        ))
517        .send()
518        .await?;
519    Ok(ok(response).await?.json().await?)
520}