ferric_fred/
series_data_request.rs

1use chrono::NaiveDate;
2
3use crate::{Client, RegionalData, Result, SeriesId};
4
5/// A builder for a GeoFRED / Maps `series/data` request, returned by
6/// [`Client::series_data`] — one regional series' values across regions, over
7/// time.
8///
9/// Only `series_id` is required; with no date set FRED returns the most recent
10/// date. Set an optional single [`date`](SeriesDataRequest::date) or a
11/// [`start_date`](SeriesDataRequest::start_date) (which returns every date from
12/// then on), and finish with [`send`](SeriesDataRequest::send).
13///
14/// ```no_run
15/// # async fn run(client: &ferric_fred::Client) -> ferric_fred::Result<()> {
16/// use ferric_fred::SeriesId;
17/// let data = client
18///     .series_data(&SeriesId::new("SMU56000000500000001"))
19///     .send()
20///     .await?;
21/// println!("{} dates", data.meta.data.len());
22/// # Ok(())
23/// # }
24/// ```
25#[derive(Debug, Clone)]
26#[must_use = "a SeriesDataRequest does nothing until you call `.send()`"]
27pub struct SeriesDataRequest<'a> {
28    client: &'a Client,
29    series_id: SeriesId,
30    date: Option<NaiveDate>,
31    start_date: Option<NaiveDate>,
32}
33
34impl<'a> SeriesDataRequest<'a> {
35    pub(crate) fn new(client: &'a Client, series_id: SeriesId) -> Self {
36        Self {
37            client,
38            series_id,
39            date: None,
40            start_date: None,
41        }
42    }
43
44    /// Return data for a single date (`date`). With neither this nor
45    /// [`start_date`](Self::start_date) set, FRED returns the most recent date.
46    pub fn date(mut self, date: NaiveDate) -> Self {
47        self.date = Some(date);
48        self
49    }
50
51    /// Return data for every date from `start_date` onward.
52    pub fn start_date(mut self, start_date: NaiveDate) -> Self {
53        self.start_date = Some(start_date);
54        self
55    }
56
57    /// Run the request and return the regional data.
58    ///
59    /// # Errors
60    ///
61    /// Returns an error if the request fails to send, FRED returns a non-success
62    /// status, or the response body cannot be deserialized. An unknown or
63    /// non-regional series id surfaces as a clear [`Error::Api`](crate::Error::Api)
64    /// naming the id — FRED answers that case with a bare HTTP 500, which the
65    /// client rewrites into an actionable message.
66    pub async fn send(self) -> Result<RegionalData> {
67        self.client.execute_series_data(&self).await
68    }
69
70    /// Serialize the set parameters to FRED query key/value pairs. `api_key` and
71    /// `file_type` are added by the client, not here.
72    pub(crate) fn query_params(&self) -> Vec<(&'static str, String)> {
73        let mut params: Vec<(&'static str, String)> = Vec::new();
74        params.push(("series_id", self.series_id.as_str().to_owned()));
75        if let Some(date) = self.date {
76            params.push(("date", date.to_string()));
77        }
78        if let Some(start_date) = self.start_date {
79            params.push(("start_date", start_date.to_string()));
80        }
81        params
82    }
83}
84
85#[cfg(test)]
86mod tests {
87    use super::*;
88
89    fn test_client() -> Client {
90        Client::new("test-key").expect("client builds")
91    }
92
93    #[test]
94    fn defaults_send_only_the_series_id() {
95        let client = test_client();
96        let request = client.series_data(&SeriesId::new("SMU56000000500000001"));
97        assert_eq!(
98            request.query_params(),
99            vec![("series_id", "SMU56000000500000001".to_owned())]
100        );
101    }
102
103    #[test]
104    fn date_and_start_date_serialize() {
105        let client = test_client();
106        let request = client
107            .series_data(&SeriesId::new("SMU56000000500000001"))
108            .date(NaiveDate::from_ymd_opt(2013, 1, 1).unwrap())
109            .start_date(NaiveDate::from_ymd_opt(2010, 1, 1).unwrap());
110        let params = request.query_params();
111        for expected in [
112            ("series_id", "SMU56000000500000001"),
113            ("date", "2013-01-01"),
114            ("start_date", "2010-01-01"),
115        ] {
116            assert!(
117                params.contains(&(expected.0, expected.1.to_owned())),
118                "missing {expected:?} in {params:?}"
119            );
120        }
121    }
122}
ferric_fred/series_data_request.rs

ferric_fred/
series_data_request.rs
