{"id":31794429,"url":"https://github.com/kanutocd/twelvedata_ruby","last_synced_at":"2025-10-10T19:45:39.948Z","repository":{"id":59158284,"uuid":"382899193","full_name":"kanutocd/twelvedata_ruby","owner":"kanutocd","description":"A  Ruby Client Library for Twelve Data API","archived":false,"fork":false,"pushed_at":"2025-07-06T16:04:18.000Z","size":524,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-22T06:57:19.531Z","etag":null,"topics":["api-client","financial-data","httpx","ruby","ruby-gem","rubygem","twelve-data","twelvedata"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/kanutocd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2021-07-04T16:31:47.000Z","updated_at":"2025-08-11T04:43:38.000Z","dependencies_parsed_at":"2025-07-02T14:33:51.602Z","dependency_job_id":null,"html_url":"https://github.com/kanutocd/twelvedata_ruby","commit_stats":null,"previous_names":["kanutocd/twelvedata_ruby","kanroyalhigh/twelvedata_ruby"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/kanutocd/twelvedata_ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Ftwelvedata_ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Ftwelvedata_ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Ftwelvedata_ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Ftwelvedata_ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kanutocd","download_url":"https://codeload.github.com/kanutocd/twelvedata_ruby/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanutocd%2Ftwelvedata_ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002300,"owners_count":26083342,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api-client","financial-data","httpx","ruby","ruby-gem","rubygem","twelve-data","twelvedata"],"created_at":"2025-10-10T19:45:36.577Z","updated_at":"2025-10-10T19:45:39.942Z","avatar_url":"https://github.com/kanutocd.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TwelvedataRuby\n\n[![Gem Version](https://badge.fury.io/rb/ruby.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/ruby)\n\nA Ruby client library for accessing [Twelve Data's](https://twelvedata.com) comprehensive financial API. Get real-time and historical data for stocks, forex, cryptocurrencies, ETFs, indices, and more.\n\n## Features\n\n- 🚀 **Modern Ruby** - Requires Ruby 3.4.0+, follows modern Ruby practices\n- 📈 **Comprehensive API Coverage** - All Twelve Data endpoints supported\n- 🔒 **Type Safety** - Strong parameter validation and error handling\n- 📊 **Multiple Formats** - JSON and CSV response formats\n- 🧪 **Well Tested** - 100% test coverage\n- 🔧 **Developer Friendly** - Excellent error messages and debugging support\n- ⚡ **High Performance** - Built on HTTPX for concurrent requests\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'twelvedata_ruby'\n```\n\nAnd then execute:\n\n```bash\nbundle install\n```\n\nOr install it yourself as:\n\n```bash\ngem install twelvedata_ruby\n```\n\n## Quick Start\n\n### 1. Get Your API Key\n\nSign up for a free API key at [Twelve Data](https://twelvedata.com/pricing).\n\n### 2. Basic Usage\n\n```ruby\nrequire 'twelvedata_ruby'\n\n# Option 1: Configure with API key directly\nclient = TwelvedataRuby.client(apikey: \"your-api-key-here\")\n\n# Option 2: Use environment variable (recommended)\nENV['TWELVEDATA_API_KEY'] = 'your-api-key-here'\nclient = TwelvedataRuby.client\n\n# Get a stock quote\nresponse = client.quote(symbol: \"AAPL\")\nputs response.parsed_body\n# =\u003e {\n#   symbol: \"AAPL\",\n#   name: \"Apple Inc\",\n#   exchange: \"NASDAQ\",\n#   currency: \"USD\",\n#   datetime: \"2024-01-15\",\n#   open: \"185.00\",\n#   high: \"187.50\",\n#   low: \"184.20\",\n#   close: \"186.75\",\n#   volume: \"45678900\",\n#   ...\n# }\n```\n\n## API Reference\n\n### Stock Market Data\n\n```ruby\n# Real-time quote\nclient.quote(symbol: \"AAPL\")\nclient.quote(symbol: \"GOOGL\", exchange: \"NASDAQ\")\n\n# Current price only\nclient.price(symbol: \"TSLA\")\n\n# Historical time series data\nclient.time_series(\n  symbol: \"AAPL\",\n  interval: \"1day\",\n  start_date: \"2024-01-01\",\n  end_date: \"2024-01-31\"\n)\n\n# End of day prices\nclient.eod(symbol: \"MSFT\")\n\n# Search for symbols\nclient.symbol_search(symbol: \"Apple\")\n```\n\n### Forex \u0026 Currency\n\n```ruby\n# Exchange rates\nclient.exchange_rate(symbol: \"USD/EUR\")\n\n# Currency conversion\nclient.currency_conversion(symbol: \"USD/EUR\", amount: 100)\n\n# Available forex pairs\nclient.forex_pairs\n```\n\n### Cryptocurrency\n\n```ruby\n# Crypto quotes\nclient.quote(symbol: \"BTC/USD\")\n\n# Available cryptocurrencies\nclient.cryptocurrencies\n\n# Crypto exchanges\nclient.cryptocurrency_exchanges\n```\n\n### Market Reference Data\n\n```ruby\n# Available stocks\nclient.stocks(exchange: \"NASDAQ\")\n\n# ETF information\nclient.etf\n\n# Market indices\nclient.indices\n\n# Stock exchanges\nclient.exchanges\n\n# Technical indicators\nclient.technical_indicators\n```\n\n### Account \u0026 Usage\n\n```ruby\n# Check API usage\nusage = client.api_usage\nputs \"Current usage: #{usage.parsed_body[:current_usage]}/#{usage.parsed_body[:plan_limit]}\"\n```\n\n## Advanced Usage\n\n### Response Formats\n\n```ruby\n# JSON response (default)\nresponse = client.quote(symbol: \"AAPL\", format: :json)\ndata = response.parsed_body # Hash\n\n# CSV response\nresponse = client.quote(symbol: \"AAPL\", format: :csv)\ntable = response.parsed_body # CSV::Table\n\n# Save CSV to file\nresponse = client.time_series(\n  symbol: \"AAPL\",\n  interval: \"1day\",\n  format: :csv,\n  filename: \"apple_daily.csv\"\n)\nresponse.save_to_file(\"./data/apple_data.csv\")\n```\n\n### Error Handling\n\n```ruby\nresponse = client.quote(symbol: \"INVALID\")\n\nif response.error\n  case response.error\n  when TwelvedataRuby::UnauthorizedResponseError\n    puts \"Invalid API key\"\n  when TwelvedataRuby::NotFoundResponseError\n    puts \"Symbol not found\"\n  when TwelvedataRuby::TooManyRequestsResponseError\n    puts \"Rate limit exceeded\"\n  else\n    puts \"Error: #{response.error.message}\"\n  end\nelse\n  puts response.parsed_body\nend\n```\n\n### Configuration Options\n\n```ruby\nclient = TwelvedataRuby.client(\n  apikey: \"your-api-key\",\n  connect_timeout: 5000,  # milliseconds\n  apikey_env_var_name: \"CUSTOM_API_KEY_VAR\"\n)\n\n# Update configuration later\nclient.configure(connect_timeout: 10000)\n\n# Or set individual options\nclient.apikey = \"new-api-key\"\nclient.connect_timeout = 3000\n```\n\n### Concurrent Requests\n\n```ruby\n# Create multiple requests\nrequests = [\n  TwelvedataRuby::Request.new(:quote, symbol: \"AAPL\"),\n  TwelvedataRuby::Request.new(:quote, symbol: \"GOOGL\"),\n  TwelvedataRuby::Request.new(:quote, symbol: \"MSFT\")\n]\n\n# Send them concurrently\nresponses = TwelvedataRuby::Client.request(requests)\nresponses.each_with_index do |http_response, index|\n  response = TwelvedataRuby::Response.resolve(http_response, requests[index])\n  puts requests[index].query_params[:symbol] + \": \" + response.parsed_body[:close]\nend\n```\n\n### Complex Data Queries\n\n```ruby\n# POST request for complex data\nresponse = client.complex_data(\n  symbols: \"AAPL,GOOGL,MSFT\",\n  intervals: \"1day,1week\",\n  start_date: \"2024-01-01\",\n  end_date: \"2024-01-31\",\n  methods: \"time_series\"\n)\n```\n\n## Response Objects\n\n### Response Methods\n\n```ruby\nresponse = client.quote(symbol: \"AAPL\")\n\n# Response status\nresponse.success?           # =\u003e true/false\nresponse.http_status_code   # =\u003e 200\nresponse.status_code        # =\u003e API status code\n\n# Content information\nresponse.content_type       # =\u003e :json, :csv, :plain\nresponse.body_bytesize      # =\u003e response size in bytes\n\n# Parsed data\nresponse.parsed_body        # =\u003e Hash, CSV::Table, or String\nresponse.body              # =\u003e alias for parsed_body\n\n# Error information\nresponse.error             # =\u003e nil or ResponseError instance\n\n# File operations\nresponse.attachment_filename  # =\u003e \"filename.csv\" if present\nresponse.save_to_file(\"path/to/file.csv\")\nresponse.dump_parsed_body     # =\u003e serialized content\n\n# Debugging\nresponse.to_s              # =\u003e human-readable summary\nresponse.inspect           # =\u003e detailed inspection\n```\n\n### Error Types\n\n```ruby\n# Base error types\nTwelvedataRuby::Error                    # Base error class\nTwelvedataRuby::ConfigurationError       # Configuration issues\nTwelvedataRuby::NetworkError            # Network connectivity issues\n\n# API endpoint errors\nTwelvedataRuby::EndpointError           # Invalid endpoint usage\nTwelvedataRuby::EndpointNameError       # Invalid endpoint name\nTwelvedataRuby::EndpointParametersKeysError     # Invalid parameters\nTwelvedataRuby::EndpointRequiredParametersError # Missing required parameters\n\n# API response errors\nTwelvedataRuby::ResponseError           # Base response error\nTwelvedataRuby::BadRequestResponseError         # 400 errors\nTwelvedataRuby::UnauthorizedResponseError       # 401 errors\nTwelvedataRuby::ForbiddenResponseError          # 403 errors\nTwelvedataRuby::NotFoundResponseError           # 404 errors\nTwelvedataRuby::TooManyRequestsResponseError    # 429 errors\nTwelvedataRuby::InternalServerResponseError     # 500 errors\n```\n\n## Available Endpoints\n\n| Endpoint                   | Method | Required Parameters                              | Description                |\n| -------------------------- | ------ | ------------------------------------------------ | -------------------------- |\n| `quote`                    | GET    | `symbol`                                         | Real-time stock quote      |\n| `price`                    | GET    | `symbol`                                         | Current stock price        |\n| `time_series`              | GET    | `symbol`, `interval`                             | Historical price data      |\n| `eod`                      | GET    | `symbol`                                         | End of day price           |\n| `exchange_rate`            | GET    | `symbol`                                         | Forex exchange rate        |\n| `currency_conversion`      | GET    | `symbol`, `amount`                               | Currency conversion        |\n| `symbol_search`            | GET    | `symbol`                                         | Search for symbols         |\n| `earliest_timestamp`       | GET    | `symbol`, `interval`                             | Earliest available data    |\n| `api_usage`                | GET    | -                                                | API usage statistics       |\n| `stocks`                   | GET    | -                                                | Available stocks           |\n| `forex_pairs`              | GET    | -                                                | Available forex pairs      |\n| `cryptocurrencies`         | GET    | -                                                | Available cryptocurrencies |\n| `etf`                      | GET    | -                                                | Available ETFs             |\n| `indices`                  | GET    | -                                                | Available indices          |\n| `exchanges`                | GET    | -                                                | Available exchanges        |\n| `cryptocurrency_exchanges` | GET    | -                                                | Available crypto exchanges |\n| `technical_indicators`     | GET    | -                                                | Available indicators       |\n| `earnings`                 | GET    | `symbol`                                         | Earnings data              |\n| `earnings_calendar`        | GET    | -                                                | Earnings calendar          |\n| `complex_data`             | POST   | `symbols`, `intervals`, `start_date`, `end_date` | Complex data queries       |\n\nFor complete parameter documentation, visit [Twelve Data's API documentation](https://twelvedata.com/docs).\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\nbundle exec rspec\n\n# Run with coverage\nCOVERAGE=true bundle exec rspec\n\n# Run specific test file\nbundle exec rspec spec/lib/twelvedata_ruby/client_spec.rb\n\n# Run with profile information\nPROFILE=true bundle exec rspec\n```\n\n### Code Quality\n\n```bash\n# Run RuboCop\nbundle exec rubocop\n\n# Auto-fix issues\nbundle exec rubocop -A\n\n# Generate documentation\nbundle exec yard doc\n```\n\n### Debugging\n\n```ruby\n# Enable debugging output\nrequire 'pry'\n\nclient = TwelvedataRuby.client(apikey: \"your-key\")\nresponse = client.quote(symbol: \"AAPL\")\n\n# Debug response\nbinding.pry\n\n# Inspect request details\nputs response.request.to_h\nputs response.request.full_url\nputs response.request.query_params\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Run the test suite (`bundle exec rspec`)\n5. Run RuboCop (`bundle exec rubocop`)\n6. Commit your changes (`git commit -am 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## Release Process\n\n#### Quick Release Guide\n\n```bash\n# 1. Prepare release\nbin/release prepare --version 0.4.1\n\n# 2. Push changes\ngit push origin main\n\n# 3. Create GitHub release with tag v0.4.1\n# → Automatic publication to RubyGems.org via GitHub Actions\n```\n\n#### Release Helper Commands\n\n```bash\n# Check if ready for release\nbin/release check\n\n# Auto-bump version\nbin/release bump --type patch    # 0.4.0 → 0.4.1\nbin/release bump --type minor    # 0.4.0 → 0.5.0\nbin/release bump --type major    # 0.4.0 → 1.0.0\n\n# Dry run (test without changes)\nbin/release prepare --version 0.4.1 --dry-run\n```\n\n#### GitHub Workflows\n\n- **CI**: Runs tests, linting, and security scans on every push/PR\n- **Release**: Automatically publishes to RubyGems.org when GitHub release is created\n- **Documentation**: Updates GitHub Pages with latest API docs\n\n#### Manual Release (Advanced)\n\n```bash\n# Trigger release workflow manually\ngh workflow run release.yml \\\n  --field version=0.4.1 \\\n  --field dry_run=false\n```\n\n## License\n\nThis gem is available as open source under the terms of the [MIT License](LICENSE).\n\n## Code of Conduct\n\nEveryone interacting in the TwelvedataRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).\n\n## Support\n\n- 📖 [API Documentation](https://kanutocd.github.io/twelvedata_ruby)\n- 🐛 [Issue Tracker](https://github.com/kanutocd/twelvedata_ruby/issues)\n- 📧 Email: kenneth.c.demanawa@gmail.com\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n\n## Notice\n\nThis is not an official Twelve Data Ruby library. The author of this gem is not affiliated with Twelve Data in any way, shape or form. Twelve Data APIs and data are Copyright © 2024 Twelve Data Pte. Ltd.\n\n---\n\n**Made with ❤️ by the Ruby community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanutocd%2Ftwelvedata_ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanutocd%2Ftwelvedata_ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanutocd%2Ftwelvedata_ruby/lists"}