← Back to Help Center
🦢 Swan Score API Configuration Guide
🦢 Ethical Investment Intelligence System
Philosophy: "An important criterion for me is that the company is good for humanity"
Complete API configuration guide for Swan Score's multi-source ESG data aggregation system with centralized key management and intelligent source-key mapping.
🌱 ESG & Sustainability
Environmental, Social, Governance scoring from multiple validated sources
💡 Innovation Metrics
R&D spending, technology advancement, and innovation scoring
🏰 Economic Moat
Competitive advantages, market dominance, and financial strength
⚖️ Technology Ethics
AI ethics, data privacy, and technology's impact on humanity
🔑 Centralized Management
Save API keys once, use across all Swan Score data sources
🆓 Public APIs
Many sources require no API keys — completely free to use
📊 Swan Score Data Sources Overview
Swan Score uses multiple specialized data sources to create comprehensive ethical investment scores. The system automatically maps your saved API keys to the appropriate services based on your data source selections.
🌱 ESG & Sustainability Data Sources
Select Data Source
→
Choose API Key
→
Auto-Configuration
Available Sources:
- 📊 Yahoo Finance (ESG Scores) — 🔓 Public API — Direct ESG scores from Yahoo Finance
- 📈 Alpha Vantage (ESG & News) — ✅ API Key Required — Company fundamentals + news sentiment analysis
- 🌍 World Bank (Development Impact) — 🔓 Open Data — Global development and sustainability metrics
- 🧪 Mock Data — 🧪 Testing — Realistic sample data for testing
🌿 Environmental Compliance Sources
Available Sources:
- 🇺🇸 EPA Envirofacts — 🏛️ US Government — Environmental violations, compliance history, emissions data
- 🇪🇺 European Environment Agency — 🏛️ EU Government — European environmental compliance data
- 🧪 Mock Data — 🧪 Testing — Sample environmental data
💡 Innovation & Technology Metrics
Available Sources:
- 📈 Alpha Vantage — ✅ API Key Required — Company overview, R&D metrics, sector analysis
- 📊 Financial Modeling Prep — ✅ API Key Required — Financial innovation metrics, R&D spending
- 🧪 Mock Data — 🧪 Testing — Sample innovation metrics
🏰 Economic Moat Analysis
Available Sources:
- 📈 Alpha Vantage — ✅ API Key Required — ROE, profit margins, financial strength
- 📊 Yahoo Finance — 🔓 Public API — Governance metrics, market position
- 📊 Financial Modeling Prep — ✅ API Key Required — Comprehensive financial analysis
- 🧪 Mock Data — 🧪 Testing — Sample moat analysis
⚖️ Technology Ethics & Impact
Available Sources:
- 📰 Alpha Vantage (News Sentiment) — ✅ API Key Required — AI ethics news analysis
- 📊 Yahoo Finance (ESG Tech) — 🔓 Public API — Technology component of ESG scores
- 👥 Community Validation — 🔮 Coming Soon — Peer-to-peer community ethics validation
- 🧪 Mock Data — 🧪 Testing — Sample ethics data
🔑 API Keys & Configuration
🔑 Centralized Key Management System
Swan Score uses a smart API key management system where you save each API key once in the API Keys section, then select which key to use for each data source via dropdown menus.
Required API Keys for Full Functionality
📈 Alpha Vantage (Recommended)
- Free Tier: 25 calls per day
- Usage: Company fundamentals, news sentiment, financial metrics
- Get Key: alphavantage.co
- Swan Score Uses: ESG analysis, Innovation metrics, Moat analysis, Technology ethics
📊 Financial Modeling Prep (Recommended Enhancement)
- Free Tier: 250 calls per day
- Usage: Comprehensive financial data, innovation metrics
- Get Key: financialmodelingprep.com
- Swan Score Uses: Innovation analysis, Moat analysis
🔗 OpenFIGI (Optional)
- Free Tier: 10,000 calls per day
- Usage: Security identification, enhanced industry classification
- Get Key: openfigi.com
- Swan Score Uses: Better industry categorization for moat analysis
📋 Step-by-Step Configuration Guide
-
Open API Configuration Tab
Navigate to the ⚙️ API Configuration tab in TradePro Portfolio Manager
-
Configure API Keys (Once)
Scroll down to the "🦢 Swan Score API Keys" section and save your API keys:
OpenFIGI API Key: your_openfigi_key (optional)
Alpha Vantage: Use existing key from main API Keys section
Financial Modeling Prep: Use existing key from main API Keys section
Note: You only need to save each key once. The system will make them available across all Swan Score data sources.
-
Configure Swan Score Data Sources
In the "🦢 Swan Score Data Sources" section, configure each data type:
- ESG & Sustainability Data: Select your preferred source (Yahoo Finance is free)
- Environmental Compliance: EPA Envirofacts (free) or European EEA
- Innovation & Technology: Choose Alpha Vantage or FMP
- Economic Moat Analysis: Alpha Vantage or FMP for comprehensive data
- Technology Ethics: Alpha Vantage for news sentiment analysis
-
Select API Keys for Each Source
For each data source that requires an API key, use the dropdown to select which saved key to use:
Source: Alpha Vantage
→
Key: Alpha Vantage 🔑
→
Status: ✅ Connected
-
Verify Connection Status
Check the connection status indicators next to each data source:
- ✅ API Key Available — Ready to use
- 🔓 Available (Public API) — No key required
- ❌ No API Key Configured — Needs configuration
-
Test Swan Score Integration
Run a stock analysis to test Swan Score functionality:
- Go to 📈 Stock Analysis tab
- Enter a stock symbol (e.g., AAPL, GOOGL)
- Click "Analyze Stock"
- Check Analysis Results for Swan Score section
🦢 Swan Score Calculation & Policies
⚠️ "Honest Data" Policy
Important: A Swan Score of 0 (or very low) often indicates missing data or API errors rather than poor ethical performance.
We believe in transparent data. Instead of guessing or filling gaps with averages, we report 0 to alert you that the data source failed or returned no information. Always check the individual component scores to identify which data points are missing.
🧮 The Swan Score Formula
The Total Swan Score (0–100) is calculated using a weighted additive model that prioritizes ethical impact:
Total Score = (Innovation × 0.25) + (Moat × 0.25) + (Ethics × 0.50)
- Innovation (25%): R&D spending, tech advancement, future-readiness.
- Moat (25%): Competitive advantage, financial strength, market position.
- Ethics (50%): ESG performance, environmental compliance, social impact.
Note: This formula ensures that a company must be "good for humanity" (Ethics) to achieve a high score, regardless of its financial dominance.
💡 Best Practices & Tips
💡 Free API Strategy
To maximize free usage:
- Start with Public APIs: Yahoo Finance, EPA, World Bank require no keys
- Add Alpha Vantage: 25 free calls/day for enhanced ESG analysis
- Upgrade gradually: Add FMP (250/day) for innovation metrics
- Use Mock Data: For testing and development without API usage
⚙️ Recommended Configurations
🆓 Completely Free Setup
- ESG Data: Yahoo Finance (Public)
- Environmental: EPA Envirofacts (Public)
- Innovation: Mock Data (Testing)
- Economic Moat: Yahoo Finance (Public)
- Technology Ethics: Mock Data (Testing)
⭐ Enhanced Setup (Recommended)
- ESG Data: Alpha Vantage (25 calls/day)
- Environmental: EPA Envirofacts (Public)
- Innovation: Alpha Vantage or FMP
- Economic Moat: Alpha Vantage
- Technology Ethics: Alpha Vantage (News Sentiment)
🏆 Professional Setup
- ESG Data: Alpha Vantage + World Bank
- Environmental: EPA + European EEA
- Innovation: FMP + Alpha Vantage
- Economic Moat: Financial Modeling Prep
- Technology Ethics: Alpha Vantage + Community (Coming Soon)
🔧 Troubleshooting
Common Issues & Solutions
❌ "No API Key Configured" Error
Solution:
- Save the required API key in the API Keys section
- Return to Swan Score data source configuration
- Select the saved key from the dropdown
- Verify connection status shows ✅
⚠️ Dropdown Shows "No API Key Required" Only
This is normal for:
- Yahoo Finance (Public API)
- EPA Envirofacts (Government API)
- World Bank Open Data
- Mock Data sources
⚠️ API Rate Limits Exceeded
Solutions:
- Switch to public APIs (Yahoo Finance, EPA)
- Use Mock Data for testing
- Wait for rate limit reset (daily/monthly)
- Upgrade to paid API plan
🤖 Swan AI Forecast (Live Features)
The Swan AI Forecast module is now fully integrated into the Community Dashboard. It leverages your configured APIs to generate predictive ethical scores with granular visibility.
📊 Granular Breakdown
New in Phase 3: Visual breakdown of the "Swan Score" into 4 key components:
- Innovation: R&D & Tech Growth
- Economic Moat: Competitive Advantage
- Tech Ethics: Data Privacy & AI Safety
- Environmental: Carbon Footprint & ESG
🔗 Smart Integration
The frontend ML engine (SwanScoringEngine) now normalizes data from disparate sources (EPA, Yahoo, World Bank) into a unified 0–100% score, replacing previous simulation data.
✨ Enhanced UI
The new scrollable detailed view allows for deep dives into component scores. The panel automatically calculates component weights when live data is engaged.
🔮 Future Enhancements
👥 Community Validation System
Coming soon: Peer-to-peer ESG validation where the community can validate and score companies based on ethical criteria. This will add human judgment to complement automated ESG scoring.
🌍 Global ESG Expansion
Additional data sources being integrated:
- MSCI ESG Ratings (when available)
- Sustainalytics ESG Risk Ratings
- Bloomberg ESG Data
- CDP Climate Change Data
🤖 AI-Enhanced Analysis
Machine learning enhancements in development:
- Automated ESG news sentiment analysis
- Predictive ESG score trends
- Industry-specific ESG benchmarking
- Real-time ESG event detection
📚 Support & Resources
🦢 Ready to Start Ethical Investing?
With Swan Score API Configuration complete, you now have access to comprehensive ethical investment analysis combining ESG data, innovation metrics, economic moat analysis, and technology ethics assessment.
Next Step: Run your first Swan Score analysis on a stock and see the detailed ethical investment breakdown!