Skip to content

About

new alphavantage api

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

AlphaVantage Rust Client

Build Status

A high-performance, async Rust client library and data pipeline for financial market data. Built with a modular workspace architecture, it integrates with AlphaVantage, CoinGecko, CoinMarketCap, and other data sources, featuring TimescaleDB storage, advanced caching, and comprehensive cryptocurrency coverage.

Status: Under active development.

Features

  • Multi-source data integration — AlphaVantage, CoinGecko, CoinMarketCap, CoinPaprika, CoinCap, SosoValue, GitHub
  • Async architecture — Built on Tokio with full concurrency support
  • Two front-ends — A Clap-based CLI (av) for ETL and queries, and an Actix-web UI (av-web) for browsing the data
  • Response caching — Minimizes API calls and costs
  • TimescaleDB — Optimized time-series storage with hypertables
  • Comprehensive crypto — 10,000+ coins with metadata, social metrics, and market data from multiple providers
  • ETL process tracking — Monitoring with automatic retry mechanisms
  • Rate limiting — Intelligent limiting based on API tier (75/min free, 600/min premium)

Data Coverage

Category Details
Equities Stocks, ETFs, mutual funds, bonds with company fundamentals
Cryptocurrency Metadata, prices (intraday + daily), market pairs, social metrics, news
News & Sentiment NLP-powered sentiment analysis with topic categorization
Market Analytics Top gainers/losers tracking

Project Structure

alphavantage/
├── crates/
│   ├── av-core/              # Core types, traits, and configuration
│   ├── av-client/            # AlphaVantage API HTTP client
│   ├── av-models/            # Data models for API responses
│   ├── av-database/
│   │   └── postgres/         # PostgreSQL/TimescaleDB via Diesel ORM
│   ├── av-loaders/           # ETL data loaders (equities, news, prices)
│   ├── crypto-loaders/       # Cryptocurrency-specific loaders and providers
│   ├── av-api/               # Unified, feature-gated facade over the libraries
│   ├── av-cli/               # Command-line interface (binary: av)
│   └── av-web/               # Actix-web UI (binary: av-web)
├── migrations/               # Database migrations
├── timescale_setup/          # TimescaleDB Docker setup
└── data/                     # CSV data files for symbol imports

Crates

av-core

Core types, traits, error handling, and configuration shared across the workspace. Includes type-safe representations for intervals, exchanges, sectors, security types, currencies, and crypto symbols with FromStr implementations.

av-client

Pure async HTTP client for AlphaVantage API endpoints — time series, fundamentals, news sentiment, forex, and cryptocurrency. No database dependencies.

av-models

Serde-based data models for all API response types.

av-database-postgres

PostgreSQL/TimescaleDB integration via Diesel 2.3 ORM with diesel-async and BB8 connection pooling. Provides repository traits for all entity types with a unified cache layer.

av-loaders

ETL data loaders for equities, intraday/daily prices, company overviews, news with sentiment analysis, and top market movers. Includes batch processing, CSV import, and process state tracking.

crypto-loaders

Cryptocurrency-specific data loaders with multi-provider support:

  • Providers: CoinGecko, CoinMarketCap, CoinPaprika, CoinCap, SosoValue
  • Loaders: Symbol discovery, metadata, details, social metrics
  • Mapping: Cross-provider symbol mapping and discovery service

av-api

Unified facade over the library crates with Cargo feature flags so downstream code can take only the slice it needs:

Feature Pulls in Use when…
models av-models Deserialising cached JSON, no I/O
client + av-client (default) Calling Alpha Vantage HTTP endpoints
database + av-database-postgres + diesel Repository / query access
loaders + av-loaders (implies client+database) Running ETL
full Everything Used by the binaries

av-cli

Command-line interface (av binary) built with Clap. See CLI commands below.

av-web

Actix-web UI served on 0.0.0.0:8080 (override with AV_WEB_PORT). Uses Tera templates from crates/av-web/templates/ and static assets from crates/av-web/static/. The Alpha Vantage client is optional at startup — if ALPHA_VANTAGE_API_KEY is missing the server still serves read-only pages (/search, /news, /movers, /sources, /chart) and only /load is disabled.

Routes:

Path Method Purpose
/ GET Search form
/search GET Symbol search results
/news GET Sentiment-tagged news for a symbol
/movers GET Top gainers / losers
/sources GET News-source aggregation
/chart GET Time-series chart for a security ID
/load GET/POST ETL trigger (disabled without API key)

CLI commands

av load securities          # Load equity symbols from CSV
av load overviews           # Load company overview data
av load intraday            # Load intraday price data
av load daily               # Load daily price data
av load news                # Load news with sentiment
av load top-movers          # Load market movers
av load crypto              # Load crypto data
av load crypto-overview     # Load crypto overviews
av load crypto-markets      # Load exchange/market pair data
av load crypto-mapping      # Load symbol mappings
av load crypto-metadata     # Load crypto metadata
av load crypto-news         # Load crypto news
av load crypto-intraday     # Load crypto intraday prices
av load crypto-details      # Load crypto details
av load crypto-prices       # Load crypto prices
av sync market              # Sync equity market data
av sync crypto              # Sync cryptocurrency data
av query symbol             # Query a specific symbol
av query list-symbols       # List all symbols
av update stats             # View database statistics

Database Schema

PostgreSQL with TimescaleDB extensions. Key table groups:

Core: symbols, overviews, overviewexts, equity_details, intradayprices, summaryprices, topstats

Cryptocurrency: crypto_api_map, crypto_metadata, crypto_overview_basic, crypto_overview_metrics, crypto_technical, crypto_social, crypto_markets

News & Sentiment: newsoverviews, feeds, articles, article_media, article_quotes, article_symbols, article_tags, article_translations, sources, authors, authormaps, tickersentiments, topicmaps, topicrefs

System: api_response_cache, procstates, proctypes, states

Database Schema

Getting Started

Prerequisites

  • Rust 1.92+ (edition 2021)
  • Docker & Docker Compose
  • PostgreSQL client tools
  • AlphaVantage API key (get one here)

Installation

  1. Clone the repository:

    git clone https://github.com/dbrowne/alphavantage.git
    cd alphavantage
  2. Start TimescaleDB:

    cd timescale_setup
    make up
  3. Configure environment (do this before running diesel setup — it reads DATABASE_URL from .env):

    cp DOT_env_EXAMPLE .env
    # Edit .env with your API keys and database URL
  4. Run database migrations:

    cd crates/av-database/postgres
    diesel setup
    diesel migration run

    The Diesel CLI is required: cargo install diesel_cli --no-default-features --features postgres.

  5. Verify the database connection:

    PGPASSWORD=dev_pw psql -U ts_user -h localhost -p 6433 -d sec_master -c '\dt'
  6. Build:

    cargo build --release

Running the CLI

./target/release/av --help
# or, during development:
cargo run -p av-cli -- --help

Running the Web UI

cargo run -p av-web
# Server listens on http://0.0.0.0:8080 by default.

AV_WEB_PORT=9090 cargo run -p av-web      # override the port

The web UI loads its Tera templates relative to the av-web crate (via CARGO_MANIFEST_DIR), so when you deploy the release binary keep templates/ and static/ next to it — or run from the source tree.

Development

Mirrors the GitHub Actions workflow:

cargo build --verbose
cargo test --verbose
cargo fmt -- --check        # CI fails on unformatted code

Per-crate tests:

cargo test -p av-core
cargo test -p av-web -- --nocapture

Note: Loose integration files under the workspace-root tests/ directory are not picked up by cargo test (no parent Cargo.toml). They need to live under a crate's tests/ subdirectory to run.

See CLAUDE.md for a deeper architectural tour aimed at AI assistants and new contributors.

Key Dependencies

Crate Version Purpose
tokio 1.46 Async runtime
actix-web 4.x Web framework (av-web)
tera latest HTML templating (av-web)
diesel 2.3 ORM (PostgreSQL)
diesel-async 0.8 Async Diesel with BB8 pooling
reqwest 0.12 HTTP client
clap 4.4 CLI framework
serde 1.0 Serialization
chrono 0.4 Date/time handling
bigdecimal 0.4 Financial precision
tracing 0.1 Structured logging
thiserror 2.0 Error types

License

MIT

About

new alphavantage api

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages