hltv

The unofficial HLTV Node.js API

Table of contents

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

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.

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 (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
-	-	-	-

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 (1 request per page of results)

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

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

---

getResults

Parses all matches from the hltv.org/results/ page (1 reuest per result page)

Option	Type	Default Value	Description
startPage	number	0	Set start page
endPage	number	1	Set end page
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 the `startpage` and `endPage` parameter
// since HLTV doesn't have pages for the event filter.
HLTV.getResults({startPage:0,endPage:2}).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	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 (2 requests)

Option	Type	Default value	Description
id	number	-	The team id

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

See schema

---

getTeamByName

Same as getTeam but accepts a team name instead of ID. (2 requests)

Option	Type	Default value	Description
name	string	-	The team name

HLTV.getTeamByName({name: "BIG"}).then(res => {
    ...
})

See getTeam schema

---

getTeamStats

Parses the info from the hltv.org/stats/teams/* page (4 requests + 1 more if currentRosterOnly is true)

Option	Type	Default value	Description
id	number	-	The team id
currentRosterOnly	boolean?	false	Return stats about the current roster only
startDate	string?	-	-
endDate	string?	-	-

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

See schema

---

getPlayer

Parses the info from the hltv.org/player/* page (1 request)

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. (2 requests)

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/* (1 request)

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 (1 request)

Option	Type	Default value	Description
startDate	string?	-	-
endDate	string?	-	-
matchType	MatchType?	-	-
rankingFilter	RankingFilter?	-	-
maps	Map[]?	-	-
minMapCount	number?	-	-
country	string[]	-	-
bestOfX	BestOfFilter?	-	-

// 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 (1 request)

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

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

See schema

---

getOngoingEvents

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

Option	Type	Default value	Description
-	-	-	-

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

See schema

---

getEvent

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

Option	Type	Default value	Description
id	number	-	The event id

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

See schema

---

getEventByName

Same as getEvent but accepts a event name instead of ID. (2 requests)

Option	Type	Default value	Description
name	string	-	The event name

HLTV.getEventByName({name: "IEM Katowice 2019"}).then(res => {
    ...
})

See getEvent 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