{"id":15288006,"url":"https://github.com/cameron-kurth/elixir_alpha_vantage","last_synced_at":"2025-04-13T06:34:20.121Z","repository":{"id":57478834,"uuid":"232005774","full_name":"Cameron-Kurth/elixir_alpha_vantage","owner":"Cameron-Kurth","description":"A lightweight Elixir wrapper for the Alpha Vantage API.","archived":false,"fork":false,"pushed_at":"2024-05-07T01:54:57.000Z","size":115,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T23:04:51.930Z","etag":null,"topics":["elixir","hex"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cameron-Kurth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-06T02:06:48.000Z","updated_at":"2024-12-19T00:30:07.000Z","dependencies_parsed_at":"2025-04-13T06:34:12.115Z","dependency_job_id":null,"html_url":"https://github.com/Cameron-Kurth/elixir_alpha_vantage","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cameron-Kurth%2Felixir_alpha_vantage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cameron-Kurth%2Felixir_alpha_vantage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cameron-Kurth%2Felixir_alpha_vantage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cameron-Kurth%2Felixir_alpha_vantage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cameron-Kurth","download_url":"https://codeload.github.com/Cameron-Kurth/elixir_alpha_vantage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248674894,"owners_count":21143761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","hex"],"created_at":"2024-09-30T15:43:45.066Z","updated_at":"2025-04-13T06:34:20.092Z","avatar_url":"https://github.com/Cameron-Kurth.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alpha Vantage\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Hex version badge](https://img.shields.io/hexpm/v/alpha_vantage.svg)](https://hex.pm/packages/alpha_vantage)\n\nA lightweight Elixir wrapper for the [Alpha Vantage API](https://www.alphavantage.co/).\n\n## Installation\n\nAdd `:alpha_vantage` to your depency list in the `mix.exs` file.\n\n```elixir\ndef deps do\n  [\n    {:alpha_vantage, \"~\u003e 0.3\"}\n  ]\nend\n```\n\nYou can now run `mix deps.get`.\n\n## Configuration\n\nWithin `config.exs` or within the environment specific config files (e.g. `dev.exs`) add your Alpha Vantage API [key](https://www.alphavantage.co/support/#api-key) and set your response timeout threshold.\n\n```elixir\nconfig :alpha_vantage,\n  api_key: \"YOUR_API_KEY\",\n  recv_timeout: 5_000\n```\n\nNote that certain requests to the Alpha Vantage API regularly take longer than HTTPoison's default timeout of 5000ms, hence the configurability for a higher tolerance.\n\n## Usage\n\nThe modules and their respective functions and naming conventions within this library are meant to mirror the Alpha Vantage API documentation as closely as possible for easy cross-referencing and implementation. The only notable divergence from this approach is the `AlphaVantage.query/1` function described immediately below.\n\n### Query\n\nThe intent of `query/1` is to provide a method for end-users to more flexibly compose their queries to the Alpha Vantage API, similarly to building the URL by hand. The primary benefit of this is the ability to quickly implement new functions from Alpha Vantage that might not yet be implemented in this library.\n\nParameters, both required and optional, may be passed as keyword lists.\n```elixir\niex\u003e AlphaVantage.query(function: \"GLOBAL_QUOTE\", symbol: \"AAPL\")\n{:ok,\n %{\n   \"Global Quote\" =\u003e %{\n     \"01. symbol\" =\u003e \"AAPL\",\n     \"02. open\" =\u003e \"182.3540\",\n     \"03. high\" =\u003e \"184.2000\",\n     \"04. low\" =\u003e \"180.4200\",\n     \"05. price\" =\u003e \"181.7100\",\n     \"06. volume\" =\u003e \"76286731\",\n     \"07. latest trading day\" =\u003e \"2024-05-06\",\n     \"08. previous close\" =\u003e \"183.3800\",\n     \"09. change\" =\u003e \"-1.6700\",\n     \"10. change percent\" =\u003e \"-0.9107%\"\n   }\n }}\n```\n\n\u003e [!NOTE]  \n\u003e This method will inform you if invalid functions or parameters are passed. Alpha Vantage returns these errors with a 200 status code, but they are cast to a 400 in the `AlphaVantage.Error` struct. Similarly, rate limit errors are cast to a 429 status code.\n```elixir\niex\u003e AlphaVantage.query(function: \"QUOTE\", symbol: \"AAPL\")\n{:error,\n %AlphaVantage.Error{\n   body: \"This API function (QUOTE) does not exist.\",\n   status_code: 400\n }}\n\niex\u003e AlphaVantage.query(function: \"GLOBAL_QUOTE\", s: \"AAPL\")\n{:error,\n %AlphaVantage.Error{\n   body: \"Invalid API call. Please retry or visit the documentation (https://www.alphavantage.co/documentation/) for GLOBAL_QUOTE.\",\n   status_code: 400\n }}\n```\n\nParameters may also be passed as a map.\n```elixir\niex\u003e AlphaVantage.query(%{function: \"EMA\", symbol: \"SPY\", interval: \"30min\", time_period: 2, series_type: \"close\"})\n{:ok,\n %{\n   \"Meta Data\" =\u003e %{\n     \"1: Symbol\" =\u003e \"SPY\",\n     \"2: Indicator\" =\u003e \"Exponential Moving Average (EMA)\",\n     \"3: Last Refreshed\" =\u003e \"2020-01-03 16:00:00\",\n     \"4: Interval\" =\u003e \"30min\",\n     \"5: Time Period\" =\u003e 2,\n     \"6: Series Type\" =\u003e \"close\",\n     \"7: Time Zone\" =\u003e \"US/Eastern\"\n   },\n   \"Technical Analysis: EMA\" =\u003e %{\n     \"2019-12-10 10:00\" =\u003e %{\"EMA\" =\u003e \"313.6772\"},\n     \"2019-12-09 12:00\" =\u003e %{\"EMA\" =\u003e \"314.6798\"},\n     \"2019-12-16 15:30\" =\u003e %{\"EMA\" =\u003e \"319.7121\"},\n     \"2019-12-19 11:30\" =\u003e %{\"EMA\" =\u003e \"320.3790\"},\n     \"2019-12-20 10:00\" =\u003e %{\"EMA\" =\u003e \"320.6725\"},\n     \"2019-12-20 13:00\" =\u003e %{...},\n     ...\n   }\n }}\n```\n\n### Stock Time Series Example\n```elixir\niex\u003e AlphaVantage.StockTimeSeries.monthly(\"AAPL\")\n{:ok,\n %{\n   \"Meta Data\" =\u003e %{\n     \"1. Information\" =\u003e \"Monthly Prices (open, high, low, close) and Volumes\",\n     \"2. Symbol\" =\u003e \"AAPL\",\n     \"3. Last Refreshed\" =\u003e \"2024-05-06\",\n     \"4. Time Zone\" =\u003e \"US/Eastern\"\n   },\n   \"Monthly Time Series\" =\u003e %{\n     \"2010-07-30\" =\u003e %{\n       \"1. open\" =\u003e \"254.3000\",\n       \"2. high\" =\u003e \"265.9900\",\n       \"3. low\" =\u003e \"239.6000\",\n       \"4. close\" =\u003e \"257.2500\",\n       \"5. volume\" =\u003e \"559632300\"\n     },\n     \"2024-02-29\" =\u003e %{\n       \"1. open\" =\u003e \"183.9850\",\n       \"2. high\" =\u003e \"191.0500\",\n       \"3. low\" =\u003e \"179.2500\",\n       \"4. close\" =\u003e \"180.7500\",\n       \"5. volume\" =\u003e \"1161711745\"\n     },\n     \"2007-10-31\" =\u003e %{\"1. open\" =\u003e \"154.6300\", \"2. high\" =\u003e \"190.1200\", ...},\n     \"2017-11-30\" =\u003e %{\"1. open\" =\u003e \"169.8700\", ...},\n     \"2017-09-29\" =\u003e %{...},\n     ...\n   }\n }}\n ```\n\n### Forex (FX) Example\n```elixir\niex\u003e AlphaVantage.Forex.exchange_rate(\"USD\", \"CAD\")\n{:ok,\n %{\n   \"Realtime Currency Exchange Rate\" =\u003e %{\n     \"1. From_Currency Code\" =\u003e \"USD\",\n     \"2. From_Currency Name\" =\u003e \"United States Dollar\",\n     \"3. To_Currency Code\" =\u003e \"CAD\",\n     \"4. To_Currency Name\" =\u003e \"Canadian Dollar\",\n     \"5. Exchange Rate\" =\u003e \"1.30000000\",\n     \"6. Last Refreshed\" =\u003e \"2020-01-05 20:21:01\",\n     \"7. Time Zone\" =\u003e \"UTC\",\n     \"8. Bid Price\" =\u003e \"1.29990000\",\n     \"9. Ask Price\" =\u003e \"1.30010000\"\n   }\n }}\n```\n\n### Cryptocurrencies Example\n```elixir\niex\u003e AlphaVantage.Cryptocurrencies.monthly(\"BTC\", \"CNY\")\n{:ok,\n %{\n   \"Meta Data\" =\u003e %{\n     \"1. Information\" =\u003e \"Monthly Prices and Volumes for Digital Currency\",\n     \"2. Digital Currency Code\" =\u003e \"BTC\",\n     \"3. Digital Currency Name\" =\u003e \"Bitcoin\",\n     \"4. Market Code\" =\u003e \"CNY\",\n     \"5. Market Name\" =\u003e \"Chinese Yuan\",\n     \"6. Last Refreshed\" =\u003e \"2020-01-05 00:00:00\",\n     \"7. Time Zone\" =\u003e \"UTC\"\n   },\n   \"Time Series (Digital Currency Monthly)\" =\u003e %{\n     \"2017-09-30\" =\u003e %{\n       \"1a. open (CNY)\" =\u003e \"32667.42879500\",\n       \"1b. open (USD)\" =\u003e \"4689.89000000\",\n       \"2a. high (CNY)\" =\u003e \"34403.92794500\",\n       \"2b. high (USD)\" =\u003e \"4939.19000000\",\n       \"3a. low (CNY)\" =\u003e \"19621.81350000\",\n       \"3b. low (USD)\" =\u003e \"2817.00000000\",\n       \"4a. close (CNY)\" =\u003e \"30498.51140500\",\n       \"4b. close (USD)\" =\u003e \"4378.51000000\",\n       \"5. volume\" =\u003e \"27634.18912000\",\n       \"6. market cap (USD)\" =\u003e \"27634.18912000\"\n     },\n     \"2017-10-31\" =\u003e %{\n       \"1a. open (CNY)\" =\u003e \"30498.37209500\",\n       \"1b. open (USD)\" =\u003e \"4378.49000000\",\n       \"2a. high (CNY)\" =\u003e \"45261.88865500\",\n       \"2b. high (USD)\" =\u003e \"6498.01000000\",\n       \"3a. low (CNY)\" =\u003e \"28628.20500000\",\n       \"3b. low (USD)\" =\u003e \"4110.00000000\",\n       \"4a. close (CNY)\" =\u003e \"45018.02650000\",\n       \"4b. close (USD)\" =\u003e \"6463.00000000\",\n       \"5. volume\" =\u003e \"41626.38846300\",\n       \"6. market cap (USD)\" =\u003e \"41626.38846300\"\n     },\n     ...\n   }\n }}\n```\n\n### Technical Indicators Example\n```elixir\niex\u003e AlphaVantage.TechnicalIndicators.mom(\"AAPL\", \"monthly\", 6, \"close\")\n{:ok,\n %{\n   \"Meta Data\" =\u003e %{\n     \"1: Symbol\" =\u003e \"AAPL\",\n     \"2: Indicator\" =\u003e \"Momentum (MOM)\",\n     \"3: Last Refreshed\" =\u003e \"2020-01-03\",\n     \"4: Interval\" =\u003e \"monthly\",\n     \"5: Time Period\" =\u003e 6,\n     \"6: Series Type\" =\u003e \"close\",\n     \"7: Time Zone\" =\u003e \"US/Eastern Time\"\n   },\n   \"Technical Analysis: MOM\" =\u003e %{\n     \"2011-06-30\" =\u003e %{\"MOM\" =\u003e \"13.1100\"},\n     \"2010-06-30\" =\u003e %{\"MOM\" =\u003e \"40.7980\"},\n     \"2006-10-31\" =\u003e %{\"MOM\" =\u003e \"10.6900\"},\n     \"2012-02-29\" =\u003e %{\"MOM\" =\u003e \"157.6100\"},\n     \"2003-02-28\" =\u003e %{\"MOM\" =\u003e \"0.2600\"},\n     \"2011-09-30\" =\u003e %{\"MOM\" =\u003e \"32.8125\"},\n     \"2016-02-29\" =\u003e %{...},\n     ...\n   }\n }}\n```\n\n### Sector Performances Example\n```elixir\niex\u003e AlphaVantage.SectorPerformances.sector()\n{:ok,\n %{\n   \"Meta Data\" =\u003e %{\n     \"Information\" =\u003e \"US Sector Performance (realtime \u0026 historical)\",\n     \"Last Refreshed\" =\u003e \"2020-01-05 15:14:28 US/Eastern\"\n   },\n   \"Rank A: Real-Time Performance\" =\u003e %{\n     \"Communication Services\" =\u003e \"-0.55%\",\n     \"Consumer Discretionary\" =\u003e \"-0.85%\",\n     \"Consumer Staples\" =\u003e \"-0.17%\",\n     \"Energy\" =\u003e \"-0.34%\",\n     \"Financials\" =\u003e \"-1.10%\",\n     \"Health Care\" =\u003e \"-0.85%\",\n     \"Industrials\" =\u003e \"-0.12%\",\n     \"Information Technology\" =\u003e \"-1.06%\",\n     \"Materials\" =\u003e \"-1.62%\",\n     \"Real Estate\" =\u003e \"0.81%\",\n     \"Utilities\" =\u003e \"0.11%\"\n   },\n   \"Rank B: 1 Day Performance\" =\u003e %{\n     \"Communication Services\" =\u003e \"-0.55%\",\n     \"Consumer Discretionary\" =\u003e \"-0.85%\",\n     \"Consumer Staples\" =\u003e \"-0.17%\",\n     \"Energy\" =\u003e \"-0.34%\",\n     \"Financials\" =\u003e \"-1.10%\",\n     \"Health Care\" =\u003e \"-0.85%\",\n     \"Industrials\" =\u003e \"-0.12%\",\n     \"Information Technology\" =\u003e \"-1.06%\",\n     \"Materials\" =\u003e \"-1.62%\",\n     \"Real Estate\" =\u003e \"0.81%\",\n     \"Utilities\" =\u003e \"0.11%\"\n   },\n   ...\n }}\n```\n\n## A Note on Tests\n\nCurrently, the free API key limitation of 5 requests per minute prevent the test suite from being run in its entirety, so please note that it is often easiest to run specific tests. This is a self-inflicted problem, as calling the API directly for tests was opted for in lieu of mocking responses in order to signal changes to the Alpha Vantage API. This approach is subject to change.\n\n## Contributing\n\nContributions are welcome and much appreciated, particularly as we try to keep up with new features from Alpha Vantage. Please feel free to open an issue in advance of any work to confirm that any new features are not already being accounted for or to more generally discuss updates prior to implementation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameron-kurth%2Felixir_alpha_vantage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcameron-kurth%2Felixir_alpha_vantage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameron-kurth%2Felixir_alpha_vantage/lists"}