\r\n \r\n \r\n The unofficial HLTV Node.js API\r\n \r\n
\r\n\r\n> **IMPORTANT** \\\r\n> This project is a fork of [gigobyte/HLTV](https://github.com/gigobyte/HLTV), originally created by [gigobyte](https://github.com/gigobyte).\r\n> The original package is no longer maintained. This fork uses **Playwright** driving a real Google Chrome instead of `got-scraping` to get past Cloudflare bot protection. Only a subset of the original API is currently exposed. These are the endpoints that were required for my use case, but I'm open to adding more endpoints if there is interest or a need for them.\r\n\r\n## Table of contents\r\n\r\n- [Installation](#installation)\r\n- [Usage](#usage)\r\n- [API](#api)\r\n - [getEvent](#getevent)\r\n - [getMatches](#getmatches)\r\n - [getResults](#getresults)\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @bogdanpet/hltv\r\nnpx playwright install chrome # Google Chrome stable; the most reliable against Cloudflare\r\n```\r\n\r\nIf Google Chrome can't be installed (no root on the machine), install Playwright's bundled Chromium instead — the library falls back to it automatically:\r\n\r\n```bash\r\nnpx playwright install --with-deps chromium\r\n```\r\n\r\n> **WARNING** \\\r\n> Abusing this library will likely result in an IP ban from HLTV due to Cloudflare bot protection. Use with caution and limit the rate of your requests.\r\n\r\n## Usage\r\n\r\n```javascript\r\n// ESM\r\nimport HLTV from '@bogdanpet/hltv'\r\n\r\n// CommonJS\r\nconst { HLTV } = require('@bogdanpet/hltv')\r\n```\r\n\r\n### Custom configuration\r\n\r\nYou can create a custom instance if you want to provide your own page loader:\r\n\r\n```javascript\r\nconst myHLTV = HLTV.createInstance({\r\n loadPage: async (url) => {\r\n // your custom fetch logic\r\n }\r\n})\r\n```\r\n\r\nBy default, the library uses **Playwright** with the system Google Chrome (falling back to Playwright's bundled Chromium) to load pages. Cookies — including Cloudflare's `cf_clearance` — are persisted to disk and reused across requests and restarts, and a Cloudflare challenge is given up to 30s (`challengeTimeout`) to resolve on its own.\r\n\r\nRequests are **not retried**: if a page is still blocked after that, the error is thrown to the caller immediately. Retrying from the same IP rarely helps and only adds to the IP's bad reputation, so retry policy (if any) is left to your application.\r\n\r\nThe browser can be tuned through `createLoadPage` or through environment variables (useful when the app itself can't be changed):\r\n\r\n```javascript\r\nimport HLTV, { createLoadPage } from '@bogdanpet/hltv'\r\n\r\nconst myHLTV = HLTV.createInstance({\r\n loadPage: createLoadPage({\r\n channel: 'chrome', // 'chrome' | 'chromium' | 'msedge'\r\n headless: false, // run headed\r\n proxy: 'http://user:pass@host:port', // or socks5://host:port\r\n locale: 'de-DE',\r\n timezoneId: 'Europe/Berlin',\r\n stateFile: '/var/lib/myapp/hltv-state.json', // false to disable cookie persistence\r\n challengeTimeout: 30000\r\n })\r\n})\r\n```\r\n\r\n| Option | Env variable | Default |\r\n| ------------------ | ---------------------- | -------------------------------------------- |\r\n| `channel` | `HLTV_BROWSER_CHANNEL` | `chrome` → `chromium` → headless shell |\r\n| `headless` | `HLTV_HEADLESS` | `true` (`false` to run headed) |\r\n| `proxy` | `HLTV_PROXY` | none |\r\n| `locale` | `HLTV_LOCALE` | `de-DE` |\r\n| `timezoneId` | `HLTV_TIMEZONE` | system timezone |\r\n| `stateFile` | `HLTV_STATE_FILE` | `/hltv-scraper/storage-state.json` |\r\n| `challengeTimeout` | – | `30000` |\r\n\r\nWhen a request is blocked the library throws a `CloudflareBlockedError` (message `CF_BLOCKED`) whose `details` carry the HTTP status, the `cf-mitigated` / `cf-ray` headers and the text that was matched, so you can tell a challenge (`cf-mitigated=challenge`) from a hard WAF block. After a block (or a navigation timeout) the saved cookies are discarded and the browser is relaunched, so the next call starts with a clean session.\r\n\r\n```javascript\r\nimport HLTV, { CloudflareBlockedError } from '@bogdanpet/hltv'\r\n\r\ntry {\r\n const event = await HLTV.getEvent({ id: 7033 })\r\n} catch (err) {\r\n if (err instanceof CloudflareBlockedError) {\r\n console.error('Blocked by Cloudflare', err.details)\r\n } else {\r\n throw err\r\n }\r\n}\r\n```\r\n\r\n## API\r\n\r\n---\r\n\r\n### getEvent\r\n\r\nParses info from the `hltv.org/events/*` page. (1 request)\r\n\r\n| Option | Type | Description |\r\n| ------ | ------ | ------------ |\r\n| id | number | The event ID |\r\n\r\n```javascript\r\nconst event = await HLTV.getEvent({ id: 7033 })\r\n```\r\n\r\n**Returns:**\r\n\r\n```typescript\r\n{\r\n id: number\r\n name: string\r\n logo: string\r\n dateStart?: number // unix timestamp\r\n dateEnd?: number // unix timestamp\r\n}\r\n```\r\n\r\n---\r\n\r\n### getMatches\r\n\r\nParses all upcoming and live matches for a given event from `hltv.org/events/:id/matches`. (1 request)\r\n\r\n| Option | Type | Description |\r\n| ------- | ------ | ------------ |\r\n| eventId | number | The event ID |\r\n\r\n```javascript\r\nconst matches = await HLTV.getMatches(7033)\r\n```\r\n\r\n**Returns** an array of:\r\n\r\n```typescript\r\n{\r\n id: number\r\n date?: number // unix timestamp, undefined for live matches\r\n team1?: {\r\n id?: number\r\n name: string\r\n logo?: string\r\n }\r\n team2?: {\r\n id?: number\r\n name: string\r\n logo?: string\r\n }\r\n format?: string // e.g. \"Bo3\"\r\n event?: {\r\n id: number\r\n }\r\n live: boolean\r\n}\r\n```\r\n\r\n---\r\n\r\n### getResults\r\n\r\nParses match results for a given event from `hltv.org/results?event=:id`. (1 request per page)\r\n\r\n| Option | Type | Description |\r\n| ------- | ------ | ------------ |\r\n| eventId | number | The event ID |\r\n\r\n```javascript\r\nconst results = await HLTV.getResults(7033)\r\n```\r\n\r\n**Returns** an array of:\r\n\r\n```typescript\r\n{\r\n id: number\r\n result: {\r\n team1: number // maps won\r\n team2: number // maps won\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## Credits\r\n\r\nOriginal package by [gigobyte](https://github.com/gigobyte/HLTV). This fork adds Playwright-based scraping to work around Cloudflare restrictions that broke the original implementation.\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}
![\"HLTV](\"https://www.hltv.org/img/static/TopLogo2x.png\")
\r\n