HLTV

[!WARNING]
This library is no longer actively maintained.

<h1 align="center"> <img src="https://www.hltv.org/img/static/TopLogo2x.png" alt="HLTV logo" width="200"> <br> The unofficial HLTV Node.js API <br> </h1>

Table of contents

• Installation
• Usage
• API
  • getMatch
  • getMatches
  • getMatchesStats
  • getMatchStats
  • getMatchMapStats
  • getStreams
  • getRecentThreads
  • getTeamRanking
  • getTeam
  • getTeamByName
  • getTeamStats
  • getPlayer
  • getPlayerByName
  • getPlayerStats
  • getPlayerRanking
  • getEvents
  • getEvent
  • getEventByName
  • getPastEvents
  • getResults
  • getNews
  • connectToScorebot
  • TEAM_PLACEHOLDER_IMAGE
  • PLAYER_PLACEHOLDER_IMAGE

Installation

Usage

:warning: WARNING: Abusing this library will likely result in an IP ban from HLTV simply because of Cloudflare bot protection.

Please use with caution and try to limit the rate and amount of your requests if you value your access to HLTV. Each method has the number of requests it makes to HLTV documented in this README. This is important if you want to implement some kind of throttling yourself.

// In .mjs files and if you're using a bundler
import HLTV from 'hltv'
// Or if you're stuck with CommonJS
const { HLTV } = require('hltv')

Configuration

You can create an instance of HLTV with a custom config if you want to.

| Option | Type | Default value | Description | | :-------: | :--------------------------------: | :----------------------------: | :-----------------------------------------------------------------------------: | | loadPage | (url: string) => Promise<string> | based on the 'got' library | Function that will be called when the library makes a request to HLTV | | httpAgent | HttpAgent | HttpsAgent | Http agent used when sending a request and connecting to the scorebot websocket |

const myHLTV = HLTV.createInstance({ loadPage: (url) => axios.get(url) })
// or
const myHLTV = HLTV.createInstance({ loadPage: (url) => fetch(url) })
// or you can just use the HLTV export directly to use the default settings
import HLTV from 'hltv'

HLTV.getMatch({ ... })

See config schema

API

getMatch

Parses most information from a match page (1 request)

| Option | Type | Default value | Description | | :----: | :----: | :-----------: | :----------: | | id | number | - | The match id |

HLTV.getMatch({ id: 2306295 }).then(res => {
    ...
})

See schema

---

getMatches

Parses all matches from the hltv.org/matches/ page (1 request)

| Option | Type | Default Value | Description | | :-------: | :--------------------------------------------------------------------------------------------: | :-----------: | :------------------------------------------------------------: | | eventIds | number[]? | - | Filter matches by event IDs. | | eventType | MatchEventType? | - | Filter matches by event type. | | filter | MatchFilter? | - | Filter matches by pre-set categories. Overrides other filters. | | teamIds | number[]? | - | - |

HLTV.getMatches().then((res) => {
  ...
})

See schema

getMatchesStats

Parses all matches from the hltv.org/stats/matches page (1 request per page of results)

| Option | Type | Default Value | Description | | :----------------------: | :----------------------------------------------------------------------------------------: | :-----------: | :----------------------------------------: | | startDate | string? | - | - | | endDate | string? | - | - | | matchType | MatchType? | - | - | | maps | GameMap[]? | - | - | | rankingFilter | RankingFilter? | - | - | | delayBetweenPageRequests | number? | 0 | Used to prevent CloudFlare throttling (ms) |

// ! BE CAREFUL, THIS CAN MAKE A LOT OF REQUESTS IF THERE ARE A LOT OF PAGES
HLTV.getMatchesStats({ startDate: '2017-07-10', endDate: '2017-07-18' }).then((res) => {
  ...
})

See schema

---

getMatchStats

Parses info from the hltv.org/stats/matches/*/* all maps stats page (1 request)

| Option | Type | Default Value | Description | | :----: | :----: | :-----------: | :---------: | | id | number | - | - |

HLTV.getMatchStats({ id: 62979 }).then((res) => {
  ...
})

See schema

---

getMatchMapStats

Parses info from the hltv.org/stats/matches/mapstatsid/*/* single map stats page (2 requests)

| Option | Type | Default Value | Description | | :----: | :----: | :-----------: | :---------: | | id | number | - | - |

HLTV.getMatchMapStats({ id: 49968 }).then((res) => {
  ...
})

See schema

---

getStreams

Parses all streams present on the front page of HLTV (1 request + 1 request per stream if loadLinks is true)

| Option | Type | Default Value | Description | | :-------: | :-----: | :-----------: | :-----------------------------------------------------------------------------------: | | loadLinks | boolean | false | Enables parsing of the stream links (every stream is an additional separate request). |

HLTV.getStreams().then((res) => {
  ...
})

See schema

---

getRecentThreads

Parses the latest threads on the front page of HLTV (1 request)

| Option | Type | Default Value | Description | | :----: | :--: | :-----------: | :---------: | | - | - | - | - |

HLTV.getRecentThreads().then((res) => {
  ...
})

See schema

getTeamRanking

Parses the info from the hltv.org/ranking/teams/ page (1 request)

| Option | Type | Default Value | Description | | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------: | :-----------: | :----------------------------------------------: | | year | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | - | - | | month | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | - | - | | day | number? | - | - | | country | string? | -