npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@jawnwee/hltv

v3.5.4

Published

The unofficial HLTV Node.js API

Downloads

76

Readme

Dependency Status devDependencies Status

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.

// In .mjs files and if you're using a bundler
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 'got' 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 | | :-------: | :--------------------------------------------------------------------------------------------: | :-----------: | :------------------------------------------------------------: | | eventIds | number[]? | - | Filter matches by event IDs. | | eventType | MatchEventType? | - | Filter matches by event type. | | filter | MatchFilter? | - | Filter matches by pre-set categories. Overrides other filters. | | teamIds | number[]? | - | - |

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 | 2022 | - | - | | 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? | - | - | | eventIds | number[]? | - | - |

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? | - | - | | stars | 1 | 2 | 3 | 4 | 5 | - | - | | 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 | 2022 | - | 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