Heatmaps.tf — API Documentation


Heatmaps are just the beginning. We'd like to see what you can do with our datasets, to that end all of our data is free to use within your own services.


All of our data is licensed under the Creative Commons Attribution 4.0 license. All we ask is that you include the logos and links to our data providers prominently alongside (or within a dialog/modal) any graphics or charts produced with our data.

Rate Limiting

The API is rate limited to a maximum of 20 requests per second per client. We ask that you respect this limit and do not attempt to circumvent it.

GET /data/maps.json

Returns a list of all maps with valid overviews - it is possible for a map to be in our system and not have a valid overview.


None available


Array of map objects.

Each map object contains:

  • name - The map's file name
  • kill_count - The total number of kills associated with the map




GET /data/kills/<map>.json

Returns a list of kills (consisting of the fields specified) from <map> with respect to the filters given.



Comma separated values of the kill fields to be returned. Valid fields are:

  • id - The internal identifier for this kill
  • timestamp - The UNIX timestamp at which this kill occured
  • killer_class - The class of the killer (see Class Indexes)
  • killer_weapon - The weapon of the killer (see Item Indexes)
  • killer_x
  • killer_y
  • killer_z
  • victim_class - The class of the killer (see Class Indexes)
  • victim_x
  • victim_y
  • victim_z
  • customkill - The custom kill bits for this kill (see Custom Kill)
  • damagebits - The damage bits for this kill (see Damage Bits)
  • death_flags - The death flags for this kill (see Death Flags)
  • team - The team of the killer


Number indicating how many results, at maximum, should be returned.


Comma separated values of classes that filters the result set to include only kills where the victim is one of the classes. Valid classes are:

  • unknown
  • scout
  • sniper
  • soldier
  • demoman
  • medic
  • heavy
  • pyro
  • spy
  • engineer


Comma separated values of classes that filters the result set to include only kills where the killer is one of the classes. Valid classes are:

  • unknown
  • scout
  • sniper
  • soldier
  • demoman
  • medic
  • heavy
  • pyro
  • spy
  • engineer


String that filters the result set to only include kills where the killer is on the specified team. Valid teams are:

  • teamless
  • spectator
  • red
  • blu


Object containing a map_data object, an array of fields, and an array of kills

The map_data object contains:

  • name - The file name of the map
  • offset_x - The x offset of the map's overview
  • offset_y - The y offset of the map's overview
  • scale - The scale of the map's overview

The fields array contains the order of the keys within the kills array

The kills array contains sub arrays of the data requested. The order of the sub arrays is determined by the fields array.







Class Indexes

Any class indexes returned by our API will use the TF2 Engine's class indexing system. This is defined as follows:

  • 0 → Unknown
  • 1 → Scout
  • 2 → Sniper
  • 3 → Soldier
  • 4 → Demoman
  • 5 → Medic
  • 6 → Heavy
  • 7 → Pyro
  • 8 → Spy
  • 9 → Engineer

Item Indexes

Any positive integer is a standard TF2 Item Definiton Index, any negative number is a custom extension:

  • -1 → Sentry
  • -2 → Mini-Sentry

Custom Kill

customkill is an integer specifying one of the following kill types:

# Custom Kill Type
4Wrench Fix
7Hadouken Taunt (Pyro)
8Burning Flare
9High Noon Taunt (Heavy)
10Grand Slam Taunt (Scout)
11Penetrate My Team
12Penetrate All Players
13Fencing Taunt (Spy)
14Penetrate Headshot
15Arrow Stab Taunt (Sniper)
17Burning Arrow
19Pumpkin Bomb
21Grenade Taunt (Soldier)
23Charge Impact
24Barbarian Swing Taunt (Demoman)
25Air Sticky Burst
26Defensive Sticky (Scottish Resistance?)
28Direct Hit Rocket
29Decapitation Boss
30Stickbomb Explosion
31Aegis Round
32Flare Explosion
33Boots Stomp
35Plasma Charged
36Plasma Gib
37Practice Sticky
38Eyeball Rocket
39Headshot Decapitation
40Armageddon Taunt (Pyro)
41Flare Pellet
43Cleaver Crit
44Sapper Recorder Death
45Merasmus Player Bomb
46Merasmus Grenade
47Merasmus Zap
48Merasmus Decapitation
49Cannonball Push
50Guitar Riff Taunt (UNUSED)

Death Flags

Death flags is a bitfield containing the following flags:

# Death Flag
1Killer Domination
2Assister Domination
4Killer Revenge
8Assister Revenge
16First Blood
32Dead Ringer