Table of contents
: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')
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({ ... })
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 => {
...
})
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) => {
...
})
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) => {
...
})
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) => {
...
})
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) => {
...
})
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) => {
...
})
Parses the latest threads on the front page of HLTV (1 request)
| Option | Type | Default Value | Description |
|---|---|---|---|
| - | - | - | - |
HLTV.getRecentThreads().then((res) => {
...
})
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) => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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 => {
...
})
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) => {
...
})
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
HLTV.TEAM_PLACEHOLDER_IMAGE
// https://www.hltv.org/img/static/team/placeholder.svg
HLTV.PLAYER_PLACEHOLDER_IMAGE
// https://static.hltv.org/images/playerprofile/bodyshot/unknown.png
FAQs
The unofficial HLTV Node.js API
The npm package hltv receives a total of 102 weekly downloads. As such, hltv popularity was classified as not popular.
We found that hltv demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.