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

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)

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

See schema

getMatches

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

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)

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)

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

See schema

getMatchMapStats

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

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

See schema

getResults

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

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

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

See schema

getRecentThreads

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

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

See schema

getTeamRanking

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

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

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

See schema

getTeamByName

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

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)

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

See schema

getPlayer

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

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

See schema

getPlayerByName

Same as getPlayer but accepts a player name instead of ID. (2 requests)

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

See getPlayer schema

getPlayerStats

Parses the info from hltv.org/stats/players/* (1 request)

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

See schema

getPlayerRanking

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

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

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

See schema

getOngoingEvents

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

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

See schema

getEvent

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

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

See schema

getEventByName

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

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

See getEvent schema

connectToScorebot

Presents an interface to receive data when the HLTV scorebot updates

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