# alpha_vantage: A Python Wrapper for the Alpha Vantage Financial Data API

> The alpha_vantage package wraps Alpha Vantage's HTTP endpoints in Python classes that return JSON, pandas data frames or CSV, and version 3.0.0 widened coverage to options, commodities and economic indicators. It is a thin client, so every limit you hit is Alpha Vantage's, not the library's.

**RomelTorres/alpha_vantage** — A python wrapper for Alpha Vantage API for financial data.

- Repository: https://github.com/RomelTorres/alpha_vantage
- Stars: 4,923 · Forks: 781
- Language: Python
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/romeltorres-alpha-vantage

## The gap alpha_vantage fills between an API key and a data frame

Alpha Vantage publishes a free financial data API that returns JSON. Calling it directly means handling query strings, retrying on timeouts, and reshaping nested JSON into something a model or a chart can consume. The alpha_vantage package does that reshaping in Python. Each data domain gets its own class, so TimeSeries handles prices, TechIndicators handles indicators, and the 3.0.0 release notes say options, commodities and economic indicators are now covered as well. The intended audience is a developer who already writes Python, wants stock or cryptocurrency data, and does not want to maintain a client for one vendor. The README is explicit that a free API key is required and points to the Alpha Vantage support page to request one. If you do not want to write code at all, the README instead points to spreadsheet add-ons and a hosted service, which is a fair signal about where this library sits: it is for people who are already in a Python environment.

## How the wrapper turns Alpha Vantage responses into objects

The design is a thin client, not an abstraction layer. You instantiate a class with your key, call a method named after the endpoint, and receive a two-tuple: the data and a metadata dictionary. The README's first example returns an intraday series for GOOGL together with the call's metadata. Output format is a constructor argument rather than a per-call one, so output_format='pandas' changes every call made through that object. Column names are not normalized. The README states that from version 1.8.0 the data frame columns match exactly what Alpha Vantage returns in its JSON, which means your code inherits the vendor's naming conventions and any changes to them. Indexing is also a constructor choice: indexing_type='date' gives a date string index, indexing_type='integer' gives an integer index. Two constraints stand out. CSV output is not available for ForeignExchange and TechIndicators, because the README says the underlying endpoints do not support it either. And pandas is not a dependency: it was removed as a hard requirement in 1.6.0, so the pandas path only exists if you install pandas yourself.

## Installing alpha_vantage and pulling your first intraday series

Installation is a single pip command. The package name on PyPI uses a hyphen while the import name uses an underscore, which is the first thing that trips people up.

```bash
pip install alpha_vantage
```

If you want data frames rather than raw dictionaries, install pandas in the same step. The README gives this as the supported way to get pandas support.

```bash
pip install alpha_vantage pandas
```

Then import the class for your data domain, pass your key, and call the endpoint. The README's example returns two values: the intraday data and the metadata for the call. If you would rather not put the key in source, the README states it can be stored in the ALPHAVANTAGE_API_KEY environment variable.

```python
from alpha_vantage.timeseries import TimeSeries
ts = TimeSeries(key='YOUR_API_KEY')
data, meta_data = ts.get_intraday('GOOGL')
```

To work with data frames, set the format on the constructor. Note that indexing_type defaults to 'date' according to the README, so you only pass it when you want integer indexing instead.

```python
from alpha_vantage.timeseries import TimeSeries
ts = TimeSeries(key='YOUR_API_KEY', output_format='pandas', indexing_type='date')
data, meta_data = ts.get_intraday(symbol='MSFT', interval='1min', outputsize='full')
```

Historical slices are the other feature worth knowing before you write your own loop. Version 3.0.0 added support for the month parameter on technical indicators, and the README shows it on both TimeSeries and TechIndicators. Passing month='2014-01' with interval='30min' returns that month's data instead of the most recent window.

```python
from alpha_vantage.timeseries import TimeSeries
from alpha_vantage.techindicators import TechIndicators
ts = TimeSeries(key='YOUR_API_KEY')
ti = TechIndicators(key='YOUR_API_KEY')
data, meta_data = ts.get_intraday('GOOGL', month='2014-01', interval='30min')
data, meta_data = ti.get_sma('GOOGL', month='2014-01', interval='30min')
```

## Retries, rapidAPI keys and the constructor flags that matter

Two constructor arguments carry most of the operational weight. The retries counter defaults to 5 and exists to reduce connection errors when the API does not respond in time; the README shows it being set on the TimeSeries constructor. That is a client-side retry, so it does not raise your quota, it only changes how patiently the library waits. The second is rapidapi=True, which lets you pass a rapidAPI key instead of a direct Alpha Vantage key. If you are porting from IEX Cloud, which the release notes say shut down in 2024, the 3.0.0 notes describe the release as friendly for that migration, but the repository does not publish a step-by-step porting guide, so expect to map endpoint names yourself.

## Where alpha_vantage stops and Alpha Vantage begins

The most important limitation is structural: this library has no data of its own. Rate limits, entitlement tiers, symbol coverage and endpoint deprecations all belong to Alpha Vantage. The 3.0.0 notes record that sector performance, extended intraday and the FCAS crypto rating were deprecated, and the wrapper simply reflects that. When an endpoint disappears, your code breaks until the library updates, and the gap between releases can be long: 3.0.0 shipped in July 2024, after 2.3.1 in December 2020. A second limitation is format coverage. CSV is unavailable for ForeignExchange and TechIndicators, so a pipeline that standardizes on CSV has to special-case those two domains. Third, the wrapper is not a caching or storage layer. Nothing in the README suggests it persists responses, so repeated calls hit your quota again. Finally, the setup.py classifiers still list Python 2.7 and 3.4 through 3.8, which does not match the modern Python most teams run; the README does not state a supported Python range, so treat that list as stale metadata rather than a promise.

## alpha_vantage compared with calling the API or using another client

The obvious alternative is not another Python package but the HTTP API itself. Alpha Vantage's own documentation is the source of truth, and calling it with requests gives you control over parsing, caching and retry policy. The trade-off is real: you write the JSON-to-data-frame conversion that this library already provides, and you re-implement the retries counter. A second alternative is a spreadsheet route. The README points to the official Google Sheets and Excel add-ons and to Wisesheets for code-less access, which suits analysts who want a cell range rather than a script. The difference in approach is that the add-ons keep data inside the spreadsheet and update in place, while alpha_vantage returns objects into a Python process where you decide what to do with them. Neither is a substitute for the other, and the README presents them side by side rather than ranking them.

## Maintenance, release cadence and the MIT licence

The repository is not archived. The last push was on 2026-07-26, which is recent enough that the project has not been abandoned, but the release history is uneven: 3.0.0 in July 2024 followed 2.3.1 in December 2020, so a three-and-a-half-year gap sits between the two most recent releases. Budget for the possibility that a new Alpha Vantage endpoint exists before this wrapper supports it. The dependency surface is small, which keeps upgrade cost low: setup.py lists aiohttp and requests as install requirements, with pandas as an extra. That aiohttp dependency is what backs the asyncio support introduced in 2.2.0. The licence is MIT, which permits commercial and closed-source use and requires preserving the copyright notice; LICENSE.txt is at the repository root. This is a description of the licence text, not legal advice, and if you redistribute the package inside a product you should read LICENSE.txt yourself.

## Conclusion

Adopt alpha_vantage if you already have an Alpha Vantage key and want pandas data frames without writing your own HTTP layer; the retries counter and the month parameter are the two features that save the most code. Do not adopt it if you need a vendor-independent data layer, because every endpoint, format restriction and rate limit belongs to Alpha Vantage. Before committing, verify your key's current entitlement, confirm whether the endpoints you need return CSV or not, and check that your pandas version matches what you install alongside it.

## FAQ

### How do I install alpha_vantage in Python?

Run pip install alpha_vantage. If you want pandas data frames, install pandas in the same command, since pandas was removed as a hard dependency in version 1.6.0.

### How do I use the alpha_vantage API key?

Pass it to the constructor of the class you use, as in TimeSeries(key='YOUR_API_KEY'). The README also states the key can be stored in the ALPHAVANTAGE_API_KEY environment variable, and a rapidAPI key works if you set rapidapi=True.

### How do I use the alpha_vantage API in Python?

Import the class for your data domain, create it with your key, and call the method for the endpoint you want. The call returns a tuple of the data and a metadata dictionary, and you can set output_format='pandas' on the constructor to get data frames instead of JSON.

### What is alpha_vantage used for?

It is a Python wrapper for the Alpha Vantage API, used to fetch stock and cryptocurrency data and finance indicators. Version 3.0.0 added support for options, commodities and economic indicators.

### Is alpha_vantage free to use?

The package itself is MIT licensed and installs from PyPI at no cost. The data comes from Alpha Vantage, which requires a key that the README says can be requested for free; the library does not set the terms or limits of that access.

## Sources

- [Issues](https://github.com/RomelTorres/alpha_vantage/issues)
- [License: MIT](https://github.com/RomelTorres/alpha_vantage/blob/develop/LICENSE)
- [README](https://github.com/RomelTorres/alpha_vantage/blob/develop/README.md)
- [Releases](https://github.com/RomelTorres/alpha_vantage/releases)
- [RomelTorres/alpha_vantage on GitHub](https://github.com/RomelTorres/alpha_vantage)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/romeltorres-alpha-vantage