The unofficial HLTV Node.js API

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: 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
loadPage	(url: string) => Promise<string>	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 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
eventId	number?	-	Filter matches by event ID.
eventType	MatchEventType?	-	Filter matches by event type.
filter	MatchFilter?	-	Filter matches by pre-set categories. Overrides other filters.

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	-	-
month	'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december'	-	-
day	number?	-	-
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 (1 request)

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?	-	-
matchType	MatchType?	-	-
rankingFilter	RankingFilter?	-	-
maps	GameMap[]?	-	-
bestOfX	BestOfFilter?	-	-

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/* (3 requests)

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

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	GameMap[]?	-	-
minMapCount	number?	-	-
countries	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
eventType	EventType?	-	Event type e.g. EventSize.Major, EventSize.LocalLAN
prizePoolMin	number?	-	Minimum prize pool (USD$)
prizePoolMax	number?	-	Maximum prize pool (USD$)
attendingTeamIds	number[]?	-	-
attendingPlayerIds	number[]?	-	-

HLTV.getEvents().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

---

getPastEvents

Parses the info from the hltv.org/events/archive page (1 request per page of results)

Option	Type	Default value	Description
eventType	EventType?	-	Event type e.g. EventSize.Major, EventSize.LocalLAN
startDate	string?	-	-
endDate	string?	-	-
prizePoolMin	number?	-	Minimum prize pool (USD$)
prizePoolMax	number?	-	Maximum prize pool (USD$)
attendingTeamIds	number[]?	-	-
attendingPlayerIds	number[]?	-	-
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.getPastEvents({ startDate: '2019-01-01', endDate: '2019-01-10' }).then(res => {
    ...
})

See schema

---

getResults

Parses the info from the hltv.org/results page (1 request per page of results)

Option	Type	Default value	Description
startDate	string?	-	-
endDate	string?	-	-
matchType	ResultMatchType?	-	-
rankingFilter	RankingFilter?	-	-
maps	GameMap[]?	-	-
countries	string[]	-	-
bestOfX	BestOfFilter?	-	-
contentFilters	ContentFilter?	-	-
eventIds	number[]?	-	-
playerIds	number[]?	-	-
teamIds	number[]?	-	-
game	GameType?	-	-
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.getResults({ eventIds: [1617], bestOfX: [BestOfFilter.BO3] }).then(res => {
    ...
})

See schema

getNews

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

Option	Type	Default Value	Description
year	2005 | 2006 | 2007 | 2008 | 2009 | 2010 | 2011 | 2012 | 2013 | 2014 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021	-	If you specify a year you must specify a month as well
month	'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december'	-	If you specify a month you must specify a year as well
eventIds	number[]?	-	-

// If you don't provide a filter the latest news will be parsed
HLTV.getNews()
HLTV.getNews({ eventIds: [3491] })
HLTV.getNews({ year: 2020, month: 'may' }).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

---

TEAM_PLACEHOLDER_IMAGE

HLTV.TEAM_PLACEHOLDER_IMAGE
// https://www.hltv.org/img/static/team/placeholder.svg

---

PLAYER_PLACEHOLDER_IMAGE

HLTV.PLAYER_PLACEHOLDER_IMAGE
// https://static.hltv.org/images/playerprofile/bodyshot/unknown.png