finance-query-core 0.3.0

A Rust client library for Yahoo Finance API - fetch quotes, historical data, financials, streaming, and more
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

use serde::{Deserialize, Serialize};

/// ESG (Environmental, Social, Governance) sustainability scores
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SustainabilityScores {
    pub symbol: String,
    /// Total ESG score
    pub total_esg: Option<f64>,
    /// Environmental score
    pub environment_score: Option<f64>,
    /// Social score
    pub social_score: Option<f64>,
    /// Governance score
    pub governance_score: Option<f64>,
    /// Controversy level (0-5, higher is worse)
    pub controversy_level: Option<u8>,
    /// ESG percentile rank
    pub percentile: Option<f64>,
    /// Peer group
    pub peer_group: Option<String>,
    /// ESG performance relative to peers
    pub peer_esg_score_performance: Option<String>,
    /// Related controversy topics
    pub related_controversy: Option<Vec<String>>,
}

impl SustainabilityScores {
    pub(crate) fn from_yahoo_response(
        symbol: String,
        response: YahooEsgResponse,
    ) -> Result<Self, crate::client::YahooError> {
        let result = response.quote_summary.result.first().ok_or_else(|| {
            crate::client::YahooError::ParseError("No ESG data in response".to_string())
        })?;

        let esg = &result.esg_scores;

        Ok(Self {
            symbol,
            total_esg: esg.total_esg.as_ref().and_then(|v| v.raw),
            environment_score: esg.environment_score.as_ref().and_then(|v| v.raw),
            social_score: esg.social_score.as_ref().and_then(|v| v.raw),
            governance_score: esg.governance_score.as_ref().and_then(|v| v.raw),
            controversy_level: esg.highest_controversy.and_then(|v| u8::try_from(v).ok()),
            percentile: esg.percentile.as_ref().and_then(|v| v.raw),
            peer_group: esg.peer_group.clone(),
            peer_esg_score_performance: esg
                .peer_esg_score_performance
                .as_ref()
                .and_then(|v| v.raw.clone()),
            related_controversy: esg.related_controversy.clone(),
        })
    }

    /// Check if ESG data is available
    pub fn has_data(&self) -> bool {
        self.total_esg.is_some()
    }

    /// Get a simple ESG rating (A, B, C, D, F based on total score)
    pub fn rating(&self) -> Option<&'static str> {
        self.total_esg.map(|score| {
            if score >= 70.0 {
                "A"
            } else if score >= 50.0 {
                "B"
            } else if score >= 30.0 {
                "C"
            } else if score >= 20.0 {
                "D"
            } else {
                "F"
            }
        })
    }
}

// Internal Yahoo response structures
#[derive(Debug, Deserialize)]
pub(crate) struct YahooEsgResponse {
    #[serde(rename = "quoteSummary")]
    pub quote_summary: EsgQuoteSummaryData,
}

#[derive(Debug, Deserialize)]
pub(crate) struct EsgQuoteSummaryData {
    pub result: Vec<EsgQuoteSummaryResult>,
}

#[derive(Debug, Deserialize)]
pub(crate) struct EsgQuoteSummaryResult {
    #[serde(rename = "esgScores")]
    pub esg_scores: EsgScoresData,
}

#[derive(Debug, Deserialize)]
pub(crate) struct EsgScoresData {
    #[serde(rename = "totalEsg")]
    pub total_esg: Option<YahooNumericValue>,
    #[serde(rename = "environmentScore")]
    pub environment_score: Option<YahooNumericValue>,
    #[serde(rename = "socialScore")]
    pub social_score: Option<YahooNumericValue>,
    #[serde(rename = "governanceScore")]
    pub governance_score: Option<YahooNumericValue>,
    #[serde(rename = "highestControversy")]
    pub highest_controversy: Option<i32>,
    pub percentile: Option<YahooNumericValue>,
    #[serde(rename = "peerGroup")]
    pub peer_group: Option<String>,
    #[serde(rename = "peerEsgScorePerformance")]
    pub peer_esg_score_performance: Option<YahooStringValue>,
    #[serde(rename = "relatedControversy")]
    pub related_controversy: Option<Vec<String>>,
}

#[derive(Debug, Deserialize)]
pub(crate) struct YahooNumericValue {
    pub raw: Option<f64>,
}

#[derive(Debug, Deserialize)]
pub(crate) struct YahooStringValue {
    pub raw: Option<String>,
}