{"id":48684042,"url":"https://github.com/klauern/clash-royale-api","last_synced_at":"2026-04-11T03:47:42.546Z","repository":{"id":331668591,"uuid":"1124965718","full_name":"klauern/clash-royale-api","owner":"klauern","description":"Clash Royale API client and analysis tool for deck building, card collection analysis, and event tracking","archived":false,"fork":false,"pushed_at":"2026-04-10T05:06:57.000Z","size":6949,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T03:47:37.656Z","etag":null,"topics":["api-client","clash-royale","deck-builder","game-analysis","golang"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/klauern.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-29T23:35:17.000Z","updated_at":"2026-04-05T15:15:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/klauern/clash-royale-api","commit_stats":null,"previous_names":["klauern/clash-royale-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/klauern/clash-royale-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klauern%2Fclash-royale-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klauern%2Fclash-royale-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klauern%2Fclash-royale-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klauern%2Fclash-royale-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/klauern","download_url":"https://codeload.github.com/klauern/clash-royale-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klauern%2Fclash-royale-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31668050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"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","clash-royale","deck-builder","game-analysis","golang"],"created_at":"2026-04-11T03:47:40.607Z","updated_at":"2026-04-11T03:47:42.536Z","avatar_url":"https://github.com/klauern.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clash Royale API Data Collector\n\n[![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?style=flat\u0026logo=go)](https://go.dev/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![GitHub Releases](https://img.shields.io/github/v/release/klauern/clash-royale-api)](https://github.com/klauern/clash-royale-api/releases)\n\nA comprehensive Go tool for collecting, analyzing, and tracking Clash Royale card data, player statistics, event decks, and intelligent deck building using the official Clash Royale API.\n\n## Quickstart\n\n```bash\n# 1. Get your API token from https://developer.clashroyale.com/\n# 2. Download the latest release for your platform\n# 3. Configure\ncp .env.example .env\n# Edit .env and add your API token\n\n# 4. Run\n./cr-api analyze --tag YOUR_PLAYER_TAG\n```\n\n## Features\n\n- 🎴 **Complete Card Database**: Access all Clash Royale cards with detailed statistics\n- 👤 **Player Profile Analysis**: Comprehensive player data including card collections\n- 🎯 **Player Context Awareness**: Arena-aware card validation, collection-based playability scoring, and level-based ladder analysis\n- 🏗️ **Intelligent Deck Building**: AI-powered deck recommendations based on your collection with evolution integration\n- 🔬 **Deck Analysis Suite**: Batch deck building, evaluation, comparison, and comprehensive reporting workflows\n- 📊 **Collection Analysis**: Detailed statistics on card levels, rarities, and upgrade priorities\n- 🎮 **Playstyle Analysis**: Analyze player's playstyle and get personalized deck recommendations\n- 🃏 **Event Deck Tracking**: Monitor and analyze performance in special events\n- 💾 **Data Persistence**: Save and track historical data over time\n- 📈 **CSV Export**: Export player data, card collections, and event statistics\n- 🔄 **Rate Limiting**: Built-in rate limiting to respect API limits\n- ⚡ **High Performance**: Go implementation provides superior performance and type safety\n\n## Documentation\n\n- **[Deck Building](docs/DECK_BUILDER.md)** - Algorithm details and Go API examples\n- **[Deck Analysis Suite](docs/DECK_ANALYSIS_SUITE.md)** - Batch deck building, evaluation, and comparison workflows\n- **[Evolution System](docs/EVOLUTION.md)** - Evolution mechanics and configuration\n- **[Event Tracking](docs/EVENT_TRACKING.md)** - Event deck analysis\n- **[CSV Exports](docs/CSV_EXPORTS.md)** - Export functionality\n- **[Deck Strategies](docs/DECK_STRATEGIES.md)** - Playstyle analysis and recommendations\n\n## Project Structure\n\n```\nclash-royale-api/\n├── .env.example               # Example configuration\n├── Taskfile.yml              # Task runner configuration\n├── cmd/                      # Command-line applications\n│   └── cr-api/              # Main CLI application\n├── pkg/                      # Go libraries\n│   ├── clashroyale/          # API client\n│   ├── analysis/             # Collection analysis \u0026 playstyle\n│   ├── deck/                 # Deck building algorithms\n│   └── events/               # Event deck tracking\n├── internal/                 # Internal packages\n│   ├── exporter/             # CSV export\n│   └── storage/              # Data persistence\n├── bin/                      # Built binaries\n├── data/                    # Data storage\n│   ├── evolution_shards.json # Evolution shard inventory\n│   ├── static/              # Static game data (cards.json cache)\n│   ├── players/             # Player profiles\n│   ├── analysis/            # Collection analysis\n│   ├── csv/                 # CSV exports\n│   └── event_decks/         # Event deck tracking\n├── scripts/                 # Utility scripts\n├── LICENSE                  # MIT License\n└── README.md                # This file\n```\n\n## Security Notice\n\n**⚠️ Important**: Never commit your `.env` file or API tokens to version control.\n\nThe `.env` file contains sensitive credentials and is **gitignored** by design. This repository includes `.env.example` as a safe template with placeholder values.\n\n**Local-only data**: The `data/` directory stores cached API responses, analysis results, and local artifacts. It is excluded from version control to keep the repository clean and avoid committing large generated files.\n\n## Installation\n\n**Binary Releases** (Recommended): Download from [Releases page](https://github.com/klauern/clash-royale-api/releases).\n\n**Build from Source** (Go 1.26+):\n```bash\ngit clone https://github.com/klauern/clash-royale-api.git\ncd clash-royale-api \u0026\u0026 task build\n```\n\n## CLI Usage\n\n```bash\n# Common commands (use --help for all options)\n./bin/cr-api player --tag PLAYER_TAG [--chests] [--save] [--export-csv]\n./bin/cr-api analyze --tag PLAYER_TAG [--save] [--export-csv]\n./bin/cr-api deck build --tag PLAYER_TAG [--strategy STRATEGY] [--verbose]\n./bin/cr-api events scan --tag PLAYER_TAG\n./bin/cr-api cards [--export-csv]\n\n# Deck building strategies: balanced (default), aggro, control, cycle, splash, spell\n./bin/cr-api deck build --tag PLAYER_TAG --strategy cycle --verbose\n\n# Deck Analysis Suite - systematic deck building and evaluation\n./bin/cr-api deck analyze-suite --tag PLAYER_TAG --strategies all --variations 2\n./bin/cr-api deck build-suite --tag PLAYER_TAG --strategies all --variations 3\n./bin/cr-api deck evaluate-batch --from-suite data/decks/suite_TAG.json --tag TAG\n./bin/cr-api deck compare --from-evaluations data/evaluations/evals_TAG.json --auto-select-top 5\n\n# Task runner (recommended)\ntask                     # Show all tasks\ntask run -- #PLAYER_TAG  # Analyze player\ntask test                # Run tests\n```\n\nSee feature-specific documentation for detailed command options:\n- [DECK_BUILDER.md](docs/DECK_BUILDER.md) - Deck building strategies and options\n- [DECK_ANALYSIS_SUITE.md](docs/DECK_ANALYSIS_SUITE.md) - Batch deck analysis workflows\n- [EVENT_TRACKING.md](docs/EVENT_TRACKING.md) - Event scanning and analysis\n- [CSV_EXPORTS.md](docs/CSV_EXPORTS.md) - Export formats and options\n- [EVOLUTION.md](docs/EVOLUTION.md) - Evolution shard management\n\n## Using as a Go Library\n\nFor complete Go API examples, integration patterns, and package documentation, see [DECK_BUILDER.md](docs/DECK_BUILDER.md).\n\n## Data Structure\n\nCard collections include name, level, rarity, count, and max_level. Analysis provides upgrade priorities, rarity breakdowns, and max-level card tracking. For evolution mechanics and configuration, see [EVOLUTION.md](docs/EVOLUTION.md).\n\n## Configuration\n\n**⚠️ Security**: Copy `.env.example` to `.env` and add your actual values. Never commit `.env` to version control.\n\n**Required**: `CLASH_ROYALE_API_TOKEN` (get from [developer.clashroyale.com](https://developer.clashroyale.com/))\n\n**Optional**: `DEFAULT_PLAYER_TAG`, `DATA_DIR`, `REQUEST_DELAY`, and more. See `.env.example` for all options.\n\n**Priority**: CLI arguments override environment variables, which override defaults.\n\n## Rate Limiting\n\nThe client includes built-in rate limiting to respect the API's limits:\n\n- Default: 1 second between requests\n- Automatic retry with exponential backoff\n- Configurable delay and retry limits\n\n## API Endpoints Used\n\n- `GET /cards` - All available cards\n- `GET /players/{tag}` - Player information\n- `GET /players/{tag}/upcomingchests` - Upcoming chests\n- `GET /players/{tag}/chestcycle` - Chest cycle\n\n## Error Handling\n\nThe client includes comprehensive error handling:\n\n- Invalid API tokens\n- Rate limiting\n- Network issues\n- Invalid player tags\n- API downtime\n\n## Testing\n\n```bash\ntask test              # Run unit tests with coverage\ntask test-integration  # Run integration tests (requires API token)\n```\n\nUnit tests run in CI. Integration tests connect to the live API and are excluded from CI due to IP restrictions (see CI/CD section below). See [AGENTS.md](AGENTS.md) for complete testing details.\n\n## CI/CD Limitations\n\nThe Clash Royale API requires static IP whitelisting (max 5 IPs per key). GitHub Actions standard runners use dynamic IPs and cannot access the live API. CI runs unit tests only; integration tests require manual execution (`task test-integration`). Automation options: self-hosted runners or GitHub Enterprise larger runners with static IPs.\n\n## Releases\n\nReleases are automated via GitHub Actions when pushing version tags (`vX.Y.Z`). Binaries are built for Linux, macOS, and Windows. See [Releases](https://github.com/klauern/clash-royale-api/releases) for downloads.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add your improvements\n4. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nThis project is for educational and personal use. Please respect Supercell's Terms of Service when using the Clash Royale API.\n\n## Support\n\n- [Official API Documentation](https://developer.clashroyale.com/#/documentation)\n- [Clash Royale API Discord](https://discord.gg/clashroyale)\n- Issues: Create an issue in this repository\n\n## Troubleshooting\n\n**API token errors**: Copy `.env.example` to `.env` and add your token. Verify your IP is allowlisted at [developer.clashroyale.com](https://developer.clashroyale.com/).\n\n**Rate limiting**: Increase `REQUEST_DELAY` in `.env` or reduce request frequency.\n\n**Build failures**: Run `go mod download \u0026\u0026 go mod tidy`\n\n**Permission denied**: Run `chmod +x bin/cr-api`\n\n## Changelog\n\nSee [GitHub Releases](https://github.com/klauern/clash-royale-api/releases) for version history and release notes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklauern%2Fclash-royale-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklauern%2Fclash-royale-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklauern%2Fclash-royale-api/lists"}