# finance-query
Generated Python client for **Finance Query v2** (3.0.0), bundling the server it talks to — there is nothing to deploy and no endpoint to configure.
```bash
pip install finance-query
```
```python
from finance_query import Client
with Client() as client:
result = client.get_analysis(...)
```
An `AsyncClient` with the same methods is importable alongside `Client`. Errors raise subclasses of `ApiError`; rate limits retry automatically, honoring `Retry-After`.
## Embedded server
Constructing a client starts the bundled `finance-query-server` on a port it picks itself, and the process is reaped when yours exits. Two environment variables change that:
- `FINANCE_QUERY_BASE_URL` — talk to an already-running instance and spawn nothing.
- `FINANCE_QUERY_SERVER_BIN` — use a different server binary.
`stop_embedded_servers()` shuts it down early; `EmbeddedServer.start()` manages one by hand.
Pass `DEFAULT_BASE_URL` (`https://finance-query.com`) to use the hosted deployment instead.
### Configuring it
The server reads the same environment a deployment sets it with. `server_env` supplies that per client:
```python
client = Client(server_env={"REDIS_URL": "...", "EDGAR_EMAIL": "..."})
```
Those values win over the ambient environment; anything left out falls back to what this process — or a `.env` file the server itself reads — already provides. Clients asking for different `server_env` get their own server process. The `ServerEnv` TypedDict spells every knob:
| `PORT` | `8000` | Server Configuration |
| `HOST` | `0.0.0.0` | Bind address. 0.0.0.0 serves every interface; an SDK-spawned server sets 127.0.0.1 so nothing off the machine can reach it |
| `LOG_LEVEL` | `INFO` | Logging Options: DEBUG, INFO, WARNING, ERROR |
| `LOG_FORMAT` | `json` | Options: json, text |
| `REDIS_URL` | _unset_ | Redis Cache (optional) |
| `RATE_LIMIT_PER_MINUTE` | `600` | Rate Limiting Requests per minute, applied independently per client IP (default: 600 = 10 req/sec) |
| `DEFAULT_INTERVAL` | `1d` | API Defaults Options: 1m, 5m, 15m, 30m, 1h, 1d, 1wk, 1mo, 3mo |
| `DEFAULT_RANGE` | `1mo` | Options: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max |
| `RECOMMENDATIONS_LIMIT` | `5` | Default Query Limits |
| `SEARCH_HITS` | `10` | |
| `SCREENERS_COUNT` | `25` | |
| `EDGAR_EMAIL` | _unset_ | SEC EDGAR Integration (optional) Contact email required by SEC - included in User-Agent header Leave commented out to disable EDGAR endpoints |
| `FRED_API_KEY` | _unset_ | FRED API Integration (optional) Free API key from https://fred.stlouisfed.org/docs/api/api_key.html Leave commented out to disable /v2/fred/* endpoints Note: If running a public server, your terms of use must state that users are bound by the FRED API Terms of Use: https://fred.stlouisfed.org/docs/api/terms_of_use.html |
| `POLYGON_API_KEY` | _unset_ | Polygon.io - https://polygon.io/dashboard/api-keys |
| `FMP_API_KEY` | _unset_ | Financial Modeling Prep - https://site.financialmodelingprep.com/developer/docs |
| `ALPHAVANTAGE_API_KEY` | _unset_ | Alpha Vantage - https://www.alphavantage.co/support/#api-key |
| `BLS_API_KEY` | _unset_ | US Bureau of Labor Statistics - https://data.bls.gov/registrationEngine/ Raises the request quota; the BLS API also works unregistered |
| `OPENFIGI_API_KEY` | _unset_ | OpenFIGI - https://www.openfigi.com/api Raises the rate limit on symbol lookups; works unregistered |
## Methods
- `get_analysis` — `GET /v2/analysis/{symbol}/{type}`: Get analysis data
- `get_batch_capital_gains` — `GET /v2/capital-gains`: Get batch capital gains history
- `get_batch_charts` — `GET /v2/charts`: Get batch historical chart data
- `get_batch_dividends` — `GET /v2/dividends`: Get batch dividend history
- `get_batch_financials` — `GET /v2/financials`: Get batch financial statements
- `get_batch_indicators` — `GET /v2/indicators`: Get batch technical indicators
- `get_batch_options` — `GET /v2/options`: Get batch options chains
- `get_batch_recommendations` — `GET /v2/recommendations`: Get batch stock recommendations
- `get_batch_splits` — `GET /v2/splits`: Get batch stock split history
- `get_calendar` — `GET /v2/calendar`: Get upcoming financial event calendar
- `get_capital_gains` — `GET /v2/capital-gains/{symbol}`: Get capital gains distribution history
- `get_chart` — `GET /v2/chart/{symbol}`: Get historical chart data
- `get_commitments_of_traders` — `GET /v2/cftc/cot/{symbol}`: Weekly CFTC Commitments of Traders positioning (keyless)
- `get_commodity` — `GET /v2/commodities/{symbol}`: Get a commodity's current quote
- `get_company_profile` — `GET /v2/company-profile/{symbol}`: Get company profile
- `get_congressional_trades` — `GET /v2/filings/{symbol}/congressional-trades`: Congressional trading disclosures for a symbol
- `get_crypto_coin` — `GET /v2/crypto/coins/{id}`: Single coin by CoinGecko ID
- `get_crypto_coins` — `GET /v2/crypto/coins`: Top coins by market cap
- `get_crypto_global` — `GET /v2/crypto/global`: Aggregate global cryptocurrency market statistics
- `get_crypto_news` — `GET /v2/crypto/news`: Market-wide crypto news
- `get_crypto_search` — `GET /v2/crypto/search`: Search CoinGecko's coin universe by free-text query
- `get_crypto_trending` — `GET /v2/crypto/trending`: Coins trending on CoinGecko over the last 24h
- `get_currencies` — `GET /v2/currencies`: Get available currencies
- `get_dividends` — `GET /v2/dividends/{symbol}`: Get dividend history and analytics
- `get_earnings_surprises` — `GET /v2/earnings-surprises/{symbol}`: Get earnings-surprise history
- `get_earnings_transcript` — `GET /v2/earnings-transcript/{symbol}`: Get earnings call transcript
- `get_edgar_cik` — `GET /v2/edgar/cik/{symbol}`: Resolve ticker to CIK
- `get_edgar_facts` — `GET /v2/edgar/facts/{symbol}`: Get XBRL financial data
- `get_edgar_search` — `GET /v2/edgar/search`: Search SEC filings
- `get_edgar_submissions` — `GET /v2/edgar/submissions/{symbol}`: Get SEC filing history
- `get_etf_profile` — `GET /v2/etf-profile/{symbol}`: Get ETF profile and holdings
- `get_exchanges` — `GET /v2/exchanges`: Get supported exchanges
- `get_executive_compensation` — `GET /v2/executive-compensation/{symbol}`: Disclosed executive compensation by year.
- `get_fails_to_deliver` — `GET /v2/filings/{symbol}/fails-to-deliver`: Fails-to-deliver records for a symbol
- `get_fear_and_greed` — `GET /v2/fear-and-greed`: Fear & Greed Index
- `get_feeds` — `GET /v2/feeds`: RSS/Atom news feeds
- `get_filing_sections` — `GET /v2/filings/{symbol}/sections`: Get sectioned text of one SEC filing
- `get_financials` — `GET /v2/financials/{symbol}/{statement}`: Get financial statements
- `get_forex` — `GET /v2/forex/{from}/{to}`: Get a currency pair's current exchange rate
- `get_forex_news` — `GET /v2/forex/news`: Market-wide forex news
- `get_fred_series` — `GET /v2/fred/series/{id}`: FRED time series
- `get_fred_treasury_yields` — `GET /v2/fred/treasury-yields`: US Treasury yield curve
- `get_futures` — `GET /v2/futures/{symbol}`: Get a futures contract's current quote
- `get_gdelt_news` — `GET /v2/gdelt/news/{symbol}`: Worldwide news mentioning a symbol (GDELT, keyless)
- `get_general_news` — `GET /v2/news`: Get general market news
- `get_grading_actions` — `GET /v2/grading-actions/{symbol}`: Provider-routed analyst upgrades and downgrades.
- `get_holders` — `GET /v2/holders/{symbol}/{type}`: Get holder data
- `get_hours` — `GET /v2/hours`: Get market hours
- `get_index_constituent_changes` — `GET /v2/indices/{symbol}/constituent-changes`: Additions and removals from an index's constituent list.
- `get_index_constituents` — `GET /v2/index-constituents/{symbol}`: Get an index's current constituent list
- `get_indicators` — `GET /v2/indicators/{symbol}`: Get technical indicators
- `get_indices` — `GET /v2/indices`: Get world market indices
- `get_industry` — `GET /v2/industries/{industry}`: Get industry data
- `get_key_metrics_ttm` — `GET /v2/key-metrics-ttm/{symbol}`: Trailing-twelve-month key metrics.
- `get_market_calendar` — `GET /v2/market-calendar`: Get a market-wide event calendar
- `get_market_summary` — `GET /v2/market-summary`: Get market summary
- `get_metrics` — `GET /v2/metrics`: Prometheus metrics
- `get_news` — `GET /v2/news/{symbol}`: Get news for a symbol
- `get_options` — `GET /v2/options/{symbol}`: Get options chain
- `get_press_releases` — `GET /v2/press-releases/{symbol}`: Get a company's own press releases
- `get_price_target_consensus` — `GET /v2/price-target-consensus/{symbol}`: Get consensus analyst price target
- `get_price_target_summary` — `GET /v2/price-target-summary/{symbol}`: Analyst price-target counts and averages per window.
- `get_protocol_tvl` — `GET /v2/crypto/coins/{id}/tvl`: A DeFi protocol's total value locked (DefiLlama, keyless).
- `get_protocol_tvl_history` — `GET /v2/crypto/coins/{id}/tvl-history`: A protocol's TVL history, oldest first.
- `get_quote` — `GET /v2/quote/{symbol}`: Get quote for a symbol
- `get_quote_type` — `GET /v2/quote-type/{symbol}`: Get quote type
- `get_quotes` — `GET /v2/quotes`: Get quotes for multiple symbols
- `get_rating_consensus` — `GET /v2/rating-consensus/{symbol}`: Get consensus rating rollup
- `get_ratios_ttm` — `GET /v2/ratios-ttm/{symbol}`: Trailing-twelve-month financial ratios.
- `get_recommendations` — `GET /v2/recommendations/{symbol}`: Get similar stock recommendations
- `get_risk` — `GET /v2/risk/{symbol}`: Risk analytics
- `get_risk_factors` — `GET /v2/filings/{symbol}/risk-factors`: Get risk factors extracted from SEC filings
- `get_screeners` — `GET /v2/screeners/{screener}`: Get screener results
- `get_sector` — `GET /v2/sectors/{sector}`: Get sector data
- `get_sector_pe` — `GET /v2/sector-pe`: Get price/earnings ratios by sector
- `get_sector_performance` — `GET /v2/sector-performance`: Get aggregate performance for every sector
- `get_sector_performance_history` — `GET /v2/sector-performance/history`: Sector performance per session.
- `get_short_volume` — `GET /v2/short-volume/{symbol}`: Daily FINRA short-sale volume for a symbol (keyless).
- `get_spark` — `GET /v2/spark`: Get batch sparkline data
- `get_splits` — `GET /v2/splits/{symbol}`: Get stock split history
- `get_symbol_details` — `GET /v2/symbol-details/{symbol}`: Reference detail for one symbol.
- `get_transcript` — `GET /v2/transcripts/{symbol}`: Get earnings transcript
- `get_transcripts` — `GET /v2/transcripts/{symbol}/all`: Get all earnings transcripts
- `get_trending` — `GET /v2/trending`: Get trending tickers
- `health_check` — `GET /v2/health`: Health check
- `lookup` — `GET /v2/lookup`: Look up symbols by type
- `ping` — `GET /v2/ping`: Ping endpoint
- `post_backtest` — `POST /v2/backtest/{symbol}`: Run a strategy backtest
- `post_custom_screener` — `POST /v2/screeners/custom`: Custom screener query
- `search` — `GET /v2/search`: Search symbols and companies