hltv

The unofficial HLTV Node.js API

Usage no npm install needed!

<script type="module">
  import hltv from 'https://cdn.skypack.dev/hltv';
</script>

README

Dependency Status devDependencies Status

HLTV logo
The unofficial HLTV Node.js API

Table of contents

Installation

NPM

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