# Alpha Vantage Client
A comprehensive, configuration-driven Python client for Alpha Vantage API with
support for all endpoints including stocks, forex, crypto, commodities, economic
indicators, and Alpha Intelligence features.
## Features
- **Complete API Coverage**: All Alpha Vantage endpoints including premium
features
- **Configuration-Driven**: Easy-to-use endpoint configuration system
- **Default Parameters**: Set defaults at client initialization for cleaner code
- **Type Safety**: Full type hints and validation
- **Developer-Friendly**: Beautiful output formatting and comprehensive
documentation
- **Easy Discovery**: Built-in endpoint discovery and filtering
## Supported Endpoints
### 📈 Time Series & Quotes
- Intraday, daily, weekly, monthly time series
- Real-time quotes and bulk quotes
- Market status
### 📊 Technical Indicators
- Moving averages (SMA, EMA, WMA, DEMA, TEMA, etc.)
- Momentum indicators (RSI, MACD, Stochastic, etc.)
- Trend indicators (ADX, Aroon, etc.)
- Volatility indicators (Bollinger Bands, ATR, etc.)
- Volume indicators (OBV, MFI, etc.)
- And many more...
### 🏢 Fundamental Data
- Company overview and financial statements
- Earnings and dividends
- ETF profiles and holdings
- Options data
### 🌍 Economic Indicators
- GDP, inflation, unemployment
- Treasury yields, federal funds rate
- Retail sales, durable goods
- Nonfarm payroll
### 🛢️ Commodities
- Energy (WTI, Brent, Natural Gas)
- Metals (Copper, Aluminum)
- Agriculture (Wheat, Corn, Cotton, Sugar, Coffee)
### 💱 Forex & Crypto
- Currency exchange rates
- Forex time series
- Cryptocurrency data
### 🧠 Alpha Intelligence
- News sentiment analysis
- Earnings call transcripts
- Insider transactions
- Top gainers/losers
- Advanced analytics (fixed and sliding window)
## Installation
```bash
pip install alpha-vantage-client
```
## Quick Start
```python
from alpha_vantage_client import AlphaVantageClient
# Initialize with your API key
client = AlphaVantageClient(
api_key="YOUR_API_KEY",
default_symbol="AAPL",
default_datatype="json"
)
# Get stock data
data = client.query("time_series_daily", symbol="AAPL")
# Get technical indicators
sma_data = client.query("sma", symbol="AAPL", interval="daily", series_type="close", time_period=20)
# Get economic data
gdp_data = client.query("real_gdp", interval="quarterly")
# Get news sentiment
news_data = client.query("news_sentiment", tickers="AAPL,TSLA", topics="technology")
```
## Advanced Usage
### Setting Defaults
```python
client = AlphaVantageClient(
api_key="YOUR_API_KEY",
default_symbol="AAPL",
default_datatype="json",
default_interval="daily",
default_series_type="close",
default_time_period=20
)
# Now you can call methods without specifying common parameters
sma_data = client.query("sma") # Uses defaults
rsi_data = client.query("rsi") # Uses defaults
```
### Discovering Endpoints
```python
# Get all available endpoints
all_endpoints = client.get_available_endpoints()
# Get endpoints by category
economic_endpoints = client.get_available_endpoints(category="economic")
tech_indicators = client.get_available_endpoints(category="technical_indicators")
# Search for specific endpoints
gdp_endpoints = client.get_available_endpoints(filter_by="gdp")
# Get detailed information
detailed_info = client.get_available_endpoints(detailed=True, category="economic")
```
### Advanced Analytics
```python
# Fixed window analytics
analytics = client.query("analytics_fixed_window",
SYMBOLS="AAPL,MSFT,IBM",
RANGE="2023-07-01",
INTERVAL="DAILY",
CALCULATIONS="MEAN,STDDEV,CORRELATION")
# Sliding window analytics
sliding_analytics = client.query("analytics_sliding_window",
SYMBOLS="AAPL,IBM",
RANGE="2month",
INTERVAL="DAILY",
WINDOW_SIZE=20,
CALCULATIONS="MEAN,STDDEV(annualized=True)")
```
## Configuration
The client supports extensive configuration options with intelligent defaults:
```python
client = AlphaVantageClient(
api_key="YOUR_API_KEY",
# Time series defaults
default_symbol="AAPL",
default_interval="daily",
default_outputsize="compact",
default_datatype="json",
# Technical indicator defaults
default_series_type="close",
default_time_period=20,
# Other defaults
default_adjusted=True,
default_extended_hours=False
)
```
### Intelligent Defaults
The client applies defaults intelligently based on each endpoint's validation
rules:
- **Commodities** (sugar, wheat, etc.): No default interval applied (uses API
default)
- **Economic indicators** (GDP, CPI, etc.): No default interval applied
- **Time series**: Default `interval="daily"` applied
- **Technical indicators**: Default `interval="daily"` and `series_type="close"`
applied
This prevents validation errors when defaults don't match endpoint requirements.
## Error Handling
The client provides clear error messages and validation:
```python
try:
data = client.query("sma", symbol="INVALID", interval="invalid")
except ValueError as e:
print(f"Validation error: {e}")
except RuntimeError as e:
print(f"API error: {e}")
```
## Development
### Installation for Development
```bash
git clone https://github.com/yourusername/alpha-vantage-client.git
cd alpha-vantage-client
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
pytest --cov=alpha_vantage_client
```
### Code Formatting
```bash
black alpha_vantage_client/
flake8 alpha_vantage_client/
mypy alpha_vantage_client/
```
## Documentation
- [Full API Documentation](https://alpha-vantage-client.readthedocs.io/)
- [Alpha Vantage API Reference](https://www.alphavantage.co/documentation/)
- [Changelog](CHANGELOG.md) - See what's new in each version
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
for details.
## Support
- 📧 Email: your.email@example.com
- 🐛 Issues:
[GitHub Issues](https://github.com/yourusername/alpha-vantage-client/issues)
- 📖 Documentation:
[Read the Docs](https://alpha-vantage-client.readthedocs.io/)
## Acknowledgments
- [Alpha Vantage](https://www.alphavantage.co/) for providing the financial data
APIs
- The Python community for excellent tools and libraries
Raw data
{
"_id": null,
"home_page": null,
"name": "alpha-vantage-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Judah Boyce <judahworkflow@gmail.com>",
"keywords": "alpha-vantage, finance, stocks, crypto, forex, api, trading, market-data",
"author": null,
"author_email": "Judah Boyce <judahworkflow@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/a6/36a7dd8c33dc97859937d5a197fcd1e67ee824d9206cbb6d18b7f8cbc0dc/alpha_vantage_client-0.1.1.tar.gz",
"platform": null,
"description": "# Alpha Vantage Client\n\nA comprehensive, configuration-driven Python client for Alpha Vantage API with\nsupport for all endpoints including stocks, forex, crypto, commodities, economic\nindicators, and Alpha Intelligence features.\n\n## Features\n\n- **Complete API Coverage**: All Alpha Vantage endpoints including premium\n features\n- **Configuration-Driven**: Easy-to-use endpoint configuration system\n- **Default Parameters**: Set defaults at client initialization for cleaner code\n- **Type Safety**: Full type hints and validation\n- **Developer-Friendly**: Beautiful output formatting and comprehensive\n documentation\n- **Easy Discovery**: Built-in endpoint discovery and filtering\n\n## Supported Endpoints\n\n### \ud83d\udcc8 Time Series & Quotes\n\n- Intraday, daily, weekly, monthly time series\n- Real-time quotes and bulk quotes\n- Market status\n\n### \ud83d\udcca Technical Indicators\n\n- Moving averages (SMA, EMA, WMA, DEMA, TEMA, etc.)\n- Momentum indicators (RSI, MACD, Stochastic, etc.)\n- Trend indicators (ADX, Aroon, etc.)\n- Volatility indicators (Bollinger Bands, ATR, etc.)\n- Volume indicators (OBV, MFI, etc.)\n- And many more...\n\n### \ud83c\udfe2 Fundamental Data\n\n- Company overview and financial statements\n- Earnings and dividends\n- ETF profiles and holdings\n- Options data\n\n### \ud83c\udf0d Economic Indicators\n\n- GDP, inflation, unemployment\n- Treasury yields, federal funds rate\n- Retail sales, durable goods\n- Nonfarm payroll\n\n### \ud83d\udee2\ufe0f Commodities\n\n- Energy (WTI, Brent, Natural Gas)\n- Metals (Copper, Aluminum)\n- Agriculture (Wheat, Corn, Cotton, Sugar, Coffee)\n\n### \ud83d\udcb1 Forex & Crypto\n\n- Currency exchange rates\n- Forex time series\n- Cryptocurrency data\n\n### \ud83e\udde0 Alpha Intelligence\n\n- News sentiment analysis\n- Earnings call transcripts\n- Insider transactions\n- Top gainers/losers\n- Advanced analytics (fixed and sliding window)\n\n## Installation\n\n```bash\npip install alpha-vantage-client\n```\n\n## Quick Start\n\n```python\nfrom alpha_vantage_client import AlphaVantageClient\n\n# Initialize with your API key\nclient = AlphaVantageClient(\n api_key=\"YOUR_API_KEY\",\n default_symbol=\"AAPL\",\n default_datatype=\"json\"\n)\n\n# Get stock data\ndata = client.query(\"time_series_daily\", symbol=\"AAPL\")\n\n# Get technical indicators\nsma_data = client.query(\"sma\", symbol=\"AAPL\", interval=\"daily\", series_type=\"close\", time_period=20)\n\n# Get economic data\ngdp_data = client.query(\"real_gdp\", interval=\"quarterly\")\n\n# Get news sentiment\nnews_data = client.query(\"news_sentiment\", tickers=\"AAPL,TSLA\", topics=\"technology\")\n```\n\n## Advanced Usage\n\n### Setting Defaults\n\n```python\nclient = AlphaVantageClient(\n api_key=\"YOUR_API_KEY\",\n default_symbol=\"AAPL\",\n default_datatype=\"json\",\n default_interval=\"daily\",\n default_series_type=\"close\",\n default_time_period=20\n)\n\n# Now you can call methods without specifying common parameters\nsma_data = client.query(\"sma\") # Uses defaults\nrsi_data = client.query(\"rsi\") # Uses defaults\n```\n\n### Discovering Endpoints\n\n```python\n# Get all available endpoints\nall_endpoints = client.get_available_endpoints()\n\n# Get endpoints by category\neconomic_endpoints = client.get_available_endpoints(category=\"economic\")\ntech_indicators = client.get_available_endpoints(category=\"technical_indicators\")\n\n# Search for specific endpoints\ngdp_endpoints = client.get_available_endpoints(filter_by=\"gdp\")\n\n# Get detailed information\ndetailed_info = client.get_available_endpoints(detailed=True, category=\"economic\")\n```\n\n### Advanced Analytics\n\n```python\n# Fixed window analytics\nanalytics = client.query(\"analytics_fixed_window\",\n SYMBOLS=\"AAPL,MSFT,IBM\",\n RANGE=\"2023-07-01\",\n INTERVAL=\"DAILY\",\n CALCULATIONS=\"MEAN,STDDEV,CORRELATION\")\n\n# Sliding window analytics\nsliding_analytics = client.query(\"analytics_sliding_window\",\n SYMBOLS=\"AAPL,IBM\",\n RANGE=\"2month\",\n INTERVAL=\"DAILY\",\n WINDOW_SIZE=20,\n CALCULATIONS=\"MEAN,STDDEV(annualized=True)\")\n```\n\n## Configuration\n\nThe client supports extensive configuration options with intelligent defaults:\n\n```python\nclient = AlphaVantageClient(\n api_key=\"YOUR_API_KEY\",\n # Time series defaults\n default_symbol=\"AAPL\",\n default_interval=\"daily\",\n default_outputsize=\"compact\",\n default_datatype=\"json\",\n \n # Technical indicator defaults\n default_series_type=\"close\",\n default_time_period=20,\n \n # Other defaults\n default_adjusted=True,\n default_extended_hours=False\n)\n```\n\n### Intelligent Defaults\n\nThe client applies defaults intelligently based on each endpoint's validation\nrules:\n\n- **Commodities** (sugar, wheat, etc.): No default interval applied (uses API\n default)\n- **Economic indicators** (GDP, CPI, etc.): No default interval applied\n- **Time series**: Default `interval=\"daily\"` applied\n- **Technical indicators**: Default `interval=\"daily\"` and `series_type=\"close\"`\n applied\n\nThis prevents validation errors when defaults don't match endpoint requirements.\n\n## Error Handling\n\nThe client provides clear error messages and validation:\n\n```python\ntry:\n data = client.query(\"sma\", symbol=\"INVALID\", interval=\"invalid\")\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\nexcept RuntimeError as e:\n print(f\"API error: {e}\")\n```\n\n## Development\n\n### Installation for Development\n\n```bash\ngit clone https://github.com/yourusername/alpha-vantage-client.git\ncd alpha-vantage-client\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\npytest --cov=alpha_vantage_client\n```\n\n### Code Formatting\n\n```bash\nblack alpha_vantage_client/\nflake8 alpha_vantage_client/\nmypy alpha_vantage_client/\n```\n\n## Documentation\n\n- [Full API Documentation](https://alpha-vantage-client.readthedocs.io/)\n- [Alpha Vantage API Reference](https://www.alphavantage.co/documentation/)\n- [Changelog](CHANGELOG.md) - See what's new in each version\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file\nfor details.\n\n## Support\n\n- \ud83d\udce7 Email: your.email@example.com\n- \ud83d\udc1b Issues:\n [GitHub Issues](https://github.com/yourusername/alpha-vantage-client/issues)\n- \ud83d\udcd6 Documentation:\n [Read the Docs](https://alpha-vantage-client.readthedocs.io/)\n\n## Acknowledgments\n\n- [Alpha Vantage](https://www.alphavantage.co/) for providing the financial data\n APIs\n- The Python community for excellent tools and libraries\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive Python client for Alpha Vantage API with configuration-driven endpoints",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/Judah-fuego/alpha-vantage-client/issues",
"Homepage": "https://github.com/Judah-fuego/alpha_vantage",
"Repository": "https://github.com/Judah-fuego/alpha_vantage",
"Source Code": "https://github.com/Judah-fuego/alpha-vantage-client"
},
"split_keywords": [
"alpha-vantage",
" finance",
" stocks",
" crypto",
" forex",
" api",
" trading",
" market-data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b547a88995089dd1831edf2a1c875ea7498d393a5e43e9cf1650392c57a51b2a",
"md5": "791ec0a79fb24efe07363303e7b14dad",
"sha256": "a3610c82a48969ecd2e9bf78d27813b274e59c6b0c5dd759c744d0b51be8fbbe"
},
"downloads": -1,
"filename": "alpha_vantage_client-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "791ec0a79fb24efe07363303e7b14dad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15892,
"upload_time": "2025-07-14T23:29:45",
"upload_time_iso_8601": "2025-07-14T23:29:45.945036Z",
"url": "https://files.pythonhosted.org/packages/b5/47/a88995089dd1831edf2a1c875ea7498d393a5e43e9cf1650392c57a51b2a/alpha_vantage_client-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2fa636a7dd8c33dc97859937d5a197fcd1e67ee824d9206cbb6d18b7f8cbc0dc",
"md5": "fa47c897c5d31d09155474d7b461f6aa",
"sha256": "0a9a7ca791bd1d399cfaa77f4135cd433f790337960257ed956aae81bf1fc4ad"
},
"downloads": -1,
"filename": "alpha_vantage_client-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "fa47c897c5d31d09155474d7b461f6aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20038,
"upload_time": "2025-07-14T23:29:47",
"upload_time_iso_8601": "2025-07-14T23:29:47.283488Z",
"url": "https://files.pythonhosted.org/packages/2f/a6/36a7dd8c33dc97859937d5a197fcd1e67ee824d9206cbb6d18b7f8cbc0dc/alpha_vantage_client-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 23:29:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Judah-fuego",
"github_project": "alpha-vantage-client",
"github_not_found": true,
"lcname": "alpha-vantage-client"
}
JSON
