The unofficial HLTV Node.js API

Table of contents

• Installation
• Usage
• API
  • getMatch
  • getMatches
  • getMatchesStats
  • getMatchStats
  • getMatchMapStats
  • getResults
  • getStreams
  • getRecentThreads
  • getTeamRanking
  • getTeam
  • getTeamStats
  • getPlayer
  • getPlayerByName
  • getPlayerStats
  • getPlayerRanking
  • getEvents
  • getEvent
  • connectToScorebot

Installation

Usage

⚠️ 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.

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
hltvUrl	string	https://www.hltv.org	Url that will be used to construct requests to HLTV
hltvStaticUrl	string	https://static.hltv.org	Url that will be used to construct links to images
loadPage	function	based on the 'request' 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 scoreboard websocket

const myHLTV = HLTV.createInstance({ loadPage: (url) => axios.get(url) })
//or
const myHLTV = HLTV.createInstance({ loadPage: (url) => fetch(url) })

See config schema

API

getMatch

Parses most information from a match page

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

Option	Type	Default Value	Description
-	-	-	-

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

See schema for Live Matches

See schema for Upcoming Matches

---

getMatchesStats

Parses all matches from the hltv.org/stats/matches page

Option	Type	Default Value	Description
startDate	string?	-	-
endDate	string?	-	-
matchType	MatchType?	-	-
maps	Map[]?	-	-

HLTV.getMatchesStats({startDate: '2017-07-10', endDate: '2017-07-18'}).then((res) => {
  ...
})

See schema

---

getMatchStats

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

Option	Type	Default Value	Description
id	number	-	-

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

See schema

---

getMatchMapStats

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

Option	Type	Default Value	Description
id	number	-	-

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

See schema

---

getResults

Parses all matches from the hltv.org/results/ page

Option	Type	Default Value	Description
pages	number	1	Number of pages with results to be parsed
teamID	number?	-	ID of specific team
eventID	number?	-	ID of specific event
contentFilters	ContentFilter[]?	[]	Add filter of the content

// Note: if you pass `eventID` to getResults you cannot pass a `pages` parameter
// since HLTV doesn't have pages for the event filter.
HLTV.getResults({pages: 2}).then((res) => {
  ...
})

See schema

---

getStreams

Parses all streams present on the front page of HLTV

Option	Type	Default Value	Description
loadLinks	boolean	false	Enables parsing of the stream links. Its an option since it can slow down the response (every stream is a separate request).

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

See schema

---

getRecentThreads

Parses the latest threads on the front page of HLTV

Option	Type	Default Value	Description
-	-	-	-

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

See schema

getTeamRanking

Parses the info from the hltv.org/ranking/teams/ page

Option	Type	Default Value	Description
year	string?	-	-
month	string?	-	Must be lowercase and in MMMM format
day	string?	-	-
country	string?	-	Must be capitalized ('Brazil', 'France' etc)

// If you don't provide a filter the latest ranking will be parsed
HLTV.getTeamRanking()
HLTV.getTeamRanking({country: 'Thailand'})
HLTV.getTeamRanking({year: '2017', month: 'may', day: '29'}).then((res) => {
  ...
})

See schema

---

getTeam

Parses the info from the hltv.org/team/ page

Option	Type	Default value	Description
id	number	-	The team id

HLTV.getTeam({id: 6137}).then(res => {
    ...
})

See schema

---

getTeamStats

Parses the info from the hltv.org/stats/teams/ page

Option	Type	Default value	Description
id	number	-	The team id

HLTV.getTeamStats({id: 6137}).then(res => {
    ...
})

See schema

---

getPlayer

Parses the info from the hltv.org/player/ page

Option	Type	Default value	Description
id	number	-	The player id

HLTV.getPlayer({id: 6137}).then(res => {
    ...
})

See schema

---

getPlayerByName

Same as getPlayer but accepts a player name instead of ID.

Option	Type	Default value	Description
name	string	-	The player name

HLTV.getPlayerByName({name: "chrisJ"}).then(res => {
    ...
})

See getPlayer schema

getPlayerStats

Parses the info from hltv.org/stats/players/*

Option	Type	Default value	Description
id	number	-	-
startDate	string	-	-
endDate	string	-	-
matchType	MatchType?	-	-
rankingFilter	RankingFilter?	-	-

HLTV.getPlayerStats({id: 7998}).then(res => {
    ...
})

See schema

---

getPlayerRanking

Parses the info from hltv.org/stats/players page

Option	Type	Default value	Description
startDate	string?	-	-
endDate	string?	-	-
matchType	MatchType?	-	-
rankingFilter	RankingFilter?	-	-

// If you don't provide a filter the latest ranking will be parsed
HLTV.getPlayerRanking({startDate: '2018-07-01', endDate: '2018-10-01'}).then(res => {
    ...
})

See schema

---

getEvents

Parses the info from the hltv.org/events page

Option	Type	Default value	Description
size	EventSize?	-	Event size type. (EventSize.Small, EventSize.Big). Default (empty) combines both.

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

See schema

---

getEvent

Parses the info from the hltv.org/event/ page

Option	Type	Default value	Description
id	number	-	The event id

HLTV.getEvent({id: 3389}).then(res => {
    ...
})

See schema

---

connectToScorebot

Presents an interface to receive data when the HLTV scorebot updates

Option	Type	Default Value	Description
id	number	-	The match ID
onScoreboardUpdate	function?	-	Callback that is called when there is new scoreboard data
onLogUpdate	function?	-	Callback that is called when there is new game log data
onFullLogUpdate	function?	-	It's still unclear when this is called and with what data, if you find out please let me know!
onConnect	function?	-	Callback that is called when a connection with the scorebot is established
onDisconnect	function?	-	Callback that is called when the scorebot disconnects

HLTV.connectToScorebot({id: 2311609, onScoreboardUpdate: (data, done) => {
    // if you call done() the socket connection will close.
}, onLogUpdate: (data, done) => {
    ...
}})

The onLogUpdate callback is passed an LogUpdate object

The onScoreboardUpdate callback is passed an ScoreboardUpdate object