Stats
API change historyAPI that provides statistical data about Players and Matches.
Halo 5 - Match Events
Retrieves a set of Events related to the Match specified. Events are only available once the Match has completed.
The set of Events may grow over time as data becomes available.
This Endpoint does not have the accuracy guarantees of other Endpoints have, so please use with caution. This endpoint may not return Matches before December 1, 2015.
Changelog
February 21, 2017:
- Renamed Endpoint from "Events for Match" to "Halo 5 - Match Events".
- Removed "{title}" Request Parameter.
May 20, 2016:
- The Endpoint now correctly reports the "Content-Type" Response Header as "application/json".
May 16, 2016:
- Documented HTTP 503 Response Code.
April 20, 2016:
- Added new types of events to the Endpoint: Impulses, Medals, Player Spawns, Round Stats, Round Ends, Weapon Drops, Weapon Pickups, and Weapon Pickup Pads.
- Fixed an issue that caused the API to consistently return HTTP 500's for matches where a player left and rejoined the match.
Request
Request URL
Request parameters
-
string
An ID that uniquely identifies a Match. Match IDs can be retrieved from the "Halo 5 - Player Match History" Endpoint.
Request headers
Request body
Responses
200 OK
The response body will contain the Match Events.
Representations
{
// Events that describe a match from start to completion. Events are reported in
// chronological order.
// Events can come in a variety of types indicated by the "EventName" field. Each event
// is documented in detail below the documentation for this return contract.
// Additional event types may be added in the future.
// When deserializing events, it is suggested to use a union of all of the fields
// across all of the different event types, shown below.
"GameEvents": [
{
"Assistants": [
{
"Gamertag": "string",
"Xuid": null
}
],
"DeathDisposition": "int",
"ImpulseId": "int",
"IsAssassination": "boolean",
"IsGroundPound": "boolean",
"IsHeadshot": "boolean",
"IsMelee": "boolean",
"IsShoulderBash": "boolean",
"IsWeapon": "boolean",
"Killer": {
"Gamertag": "string",
"Xuid": null
},
"KillerAgent": "int",
"KillerWeaponAttachmentIds": [ "int" ],
"KillerWeaponStockId": "int",
"KillerWorldLocation": {
"x": "double",
"y": "double",
"z": "double"
},
"MedalId": "int",
"Player": {
"Gamertag": "string",
"Xuid": null
},
"RoundIndex": "int",
"ShotsFired": "int",
"ShotsLanded": "int",
"TimeWeaponActiveAsPrimary": "string",
"Victim": {
"Gamertag": "string",
"Xuid": null
},
"VictimAgent": "int",
"VictimAttachmentIds": [ "int" ],
"VictimStockId": "int",
"VictimWorldLocation": {
"x": "double",
"y": "double",
"z": "double"
},
"WeaponAttachmentIds": [ "int" ],
"WeaponStockId": "int",
// Descriptor to determine what fields will be filled in for the event. This list
// will grow over time as more events are exposed. Can be one of the following:
// "Death" - An event that is created when a death occurs in the match.
// "Impulse" - An event that is created when an impulse (invisible medal) is
// triggered in the match.
// "Medal" - An event that is created when a medal is awarded in the match.
// "PlayerSpawn" - An event that is created when a player spawns in the match.
// "RoundStart" - An event that is created when a round starts. In regular
// matches, there is typically one round. However, some modes have multiple rounds..
// "RoundEnd" - An event that is created when a round ends. In regular matches,
// there is typically one round. However, some modes have multiple rounds..
// "WeaponDrop" - An event that is created when a player drops a weapon for a new
// weapon. This occurs when a player picks up a new weapon and drops their current
// one, when a player dies and drops their weapon(s), or at the end of the match
// for each player.
// "WeaponPickup" - An event that is created when a player picks up a weapon.
// This can be when a player spawns, or when a player picks up a new weapon.
// "WeaponPickupPad" - An event that is created when a player picks up a weapon
// off a pad. This will not be triggered if the weapon was picked up off the ground
// after another player who had picked it off a pad.
"EventName": "string",
// Time passed since the start of the match when the event occurred. This is
// expressed as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
],
// As this is an experimental API it has no guarantees around its accuracy. However we
// do try our best to ensure all events are valid and accounted for. If they do not
// match up to our expectations this field will return as false indicating this may not
// be the full set of events that occurred in game.
"IsCompleteSetOfEvents": "boolean",
// Internal use only. A set of related resource links.
"Links": null
}
// Death Event
{
// The gamertags of players who contributed to a kill.
"Assistants": [
{
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
}],
// The disposition of the death. Can be one of the following:
// Friendly = 0,
// Hostile = 1,
// Neutral = 2
"DeathDisposition": "int",
// Describes if the death was committed by the killer from behind (Assassination or
// melee to back).
"IsAssassination": "boolean",
// Describes if the kill was committed by the killer with a ground pound.
"IsGroundPound": "boolean",
// Describes if the kill was committed by the killer with a head shot.
"IsHeadshot": "boolean",
// Describes if the kill was committed by the killer using melee.
"IsMelee": "boolean",
// Describes if the kill was committed by the killer with a shoulder bash.
"IsShoulderBash": "boolean",
// Describes if the kill was committed by the killer with a weapon.
"IsWeapon": "boolean",
// Describes the killer's information. Can be null if killer is not a player in the
// game.
"Killer": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
},
// The type of killer that caused the death. Can be one of the following:
// None = 0,
// Player = 1,
// AI = 2
"KillerAgent": "int",
// The IDs of any attachments that were associated with the weapon that was used to
// kill the victim.
"KillerWeaponAttachmentIds": ["int"],
// The ID of the weapon that was used to kill the victim. Depending on the type of the
// kill, this could be the ID of an Enemy, Vehicle, or Weapon, all of which are
// available via the Metadata APIs. Note that most vehicles are duplicated between both
// the Vehicle and Weapon Metadata APIs. If this was a standard kill with an actual
// weapon, then this will be the ID of the weapon that killed the victim. If this was a
// kill with a vehicle, then this will the ID of the vehicle that killed the victim. If
// this was a melee kill, then this will be the ID of the type of the object that
// killed the player (which will be either Spartan or the type of the type of the AI
// enemy that killed the player). Note that if the victim was killed by a weapon held
// by an AI enemy, the type of the AI enemy is unknown.
"KillerWeaponStockId": "int",
// Object describing the position of the killer on the map when they made the kill.
"KillerWorldLocation": {
"x": "double",
"y": "double",
"z": "double"
},
// Describes the victim's information. Can be null if victim is not a player in the
// game.
"Victim": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
},
// The type of victim who was killed. Can be one of the following:
// None = 0,
// Player = 1,
// AI = 2
"VictimAgent": "int",
// Any variants of the AI enemy, empty otherwise.
"VictimAttachmentIds": ["int"],
// The ID of the AI Enemy killed, zero otherwise. Enemy IDs are available via the
// Metadata API.
"VictimStockId": "int",
// Object describing the position of the victim on the map when they were killed.
"VictimWorldLocation": {
"x": "double",
"y": "double",
"z": "double"
},
// Descriptor to determine what fields will be filled in for the event.
"EventName": "string",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// Impulse Event
{
// The ID that uniquely identifies this impulse. Impulses are available via the
// Metadata API.
"ImpulseId" : "int",
// The player who received the impulse.
"Player": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
}
// Descriptor to determine what fields will be filled in for the event.
"EventName": "Impulse",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// Medal Event
{
// The ID that uniquely identifies this medal. Medals are available via the Metadata
// API.
"MedalId" : "int",
// The player who received the medal.
"Player": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
},
// Descriptor to determine what fields will be filled in for the event.
"EventName": "Medal",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// PlayerSpawn Event
{
// The player who spawned.
"Player": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
},
// Descriptor to determine what fields will be filled in for the event.
"EventName": "PlayerSpawn",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// RoundStart Event
{
// The index of the round that started.
"RoundIndex" : "int",
// Descriptor to determine what fields will be filled in for the event.
"EventName": "RoundStart",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// RoundEnd Event
{
// The index of the round that ended.
"RoundIndex" : "int",
// Descriptor to determine what fields will be filled in for the event.
"EventName": "RoundEnd",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// WeaponDrop Event
{
// The player who dropped the weapon.
"Player": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
},
// The number of shots fired with the weapon by the player.
"ShotsFired" : "int",
// The number of shots that hit the target with the weapon by the player.
"ShotsLanded" : "int",
// The amount of time the weapon was in the active slot of the player. This is
// expressed as an ISO 8601 Duration.
"TimeWeaponActiveAsPrimary": "string",
// The IDs of any attachments that were associated with the weapon that was dropped.
"WeaponAttachmentIds": ["int"],
// The ID of the weapon that was dropped. Weapons are available via the Metadata API.
"WeaponStockId": "int",
// Descriptor to determine what fields will be filled in for the event.
"EventName": "WeaponDrop",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// WeaponPickup Event
{
// The player who picked up the weapon.
"Player": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
},
// The IDs of any attachments that were associated with the weapon that was picked up.
"WeaponAttachmentIds": ["int"],
// The ID of the weapon that was picked up. Weapons are available via the Metadata API.
"WeaponStockId": "int",
// Descriptor to determine what fields will be filled in for the event.
"EventName": "WeaponPickup",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
// WeaponPickupPad Event
{
// The player who picked up the weapon.
"Player": {
// The player's gamertag.
"Gamertag": "string",
// Internal use only. This will always be null.
"Xuid": null
},
// The IDs of any attachments that were associated with the weapon that was picked up.
"WeaponAttachmentIds": ["int"],
// The ID of the weapon that was picked up. Weapons are available via the Metadata API.
"WeaponStockId": "int",
// Descriptor to determine what fields will be filled in for the event.
"EventName": "WeaponPickupPad",
// Time passed since the start of the match when the event occurred. This is expressed
// as an ISO 8601 Duration.
"TimeSinceStart": "string"
}
404 Not Found
The specified Match could not be found.
Representations
500 Internal Server Error
Internal Server Error
Representations
503 Service Unavailable
Service Unavailable
Representations
Code samples
@ECHO OFF
curl -v -X GET "https://www.haloapi.com/stats/h5/matches/{matchId}/events"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
--data-ascii "{body}"
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;
namespace CSHttpClientSample
{
static class Program
{
static void Main()
{
MakeRequest();
Console.WriteLine("Hit ENTER to exit...");
Console.ReadLine();
}
static async void MakeRequest()
{
var client = new HttpClient();
var queryString = HttpUtility.ParseQueryString(string.Empty);
// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");
var uri = "https://www.haloapi.com/stats/h5/matches/{matchId}/events?" + queryString;
var response = await client.GetAsync(uri);
}
}
}
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
public class JavaSample
{
public static void main(String[] args)
{
HttpClient httpclient = HttpClients.createDefault();
try
{
URIBuilder builder = new URIBuilder("https://www.haloapi.com/stats/h5/matches/{matchId}/events");
URI uri = builder.build();
HttpGet request = new HttpGet(uri);
request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");
// Request body
StringEntity reqEntity = new StringEntity("{body}");
request.setEntity(reqEntity);
HttpResponse response = httpclient.execute(request);
HttpEntity entity = response.getEntity();
if (entity != null)
{
System.out.println(EntityUtils.toString(entity));
}
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
$(function() {
var params = {
// Request parameters
};
$.ajax({
url: "https://www.haloapi.com/stats/h5/matches/{matchId}/events?" + $.param(params),
beforeSend: function(xhrObj){
// Request headers
xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
},
type: "GET",
// Request body
data: "{body}",
})
.done(function(data) {
alert("success");
})
.fail(function() {
alert("error");
});
});
</script>
</body>
</html>
#import <Foundation/Foundation.h>
int main(int argc, const char * argv[])
{
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
NSString* path = @"https://www.haloapi.com/stats/h5/matches/{matchId}/events";
NSArray* array = @[
// Request parameters
@"entities=true",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"GET"];
// Request headers
[_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
// Request body
[_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
NSURLResponse *response = nil;
NSError *error = nil;
NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
if (nil != error)
{
NSLog(@"Error: %@", error);
}
else
{
NSError* error = nil;
NSMutableDictionary* json = nil;
NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
NSLog(@"%@", dataString);
if (nil != _connectionData)
{
json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
}
if (error || !json)
{
NSLog(@"Could not parse loaded json with error:%@", error);
}
NSLog(@"%@", json);
_connectionData = nil;
}
[pool drain];
return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';
$request = new Http_Request2('https://www.haloapi.com/stats/h5/matches/{matchId}/events');
$url = $request->getUrl();
$headers = array(
// Request headers
'Ocp-Apim-Subscription-Key' => '{subscription key}',
);
$request->setHeader($headers);
$parameters = array(
// Request parameters
);
$url->setQueryVariables($parameters);
$request->setMethod(HTTP_Request2::METHOD_GET);
// Request body
$request->setBody("{body}");
try
{
$response = $request->send();
echo $response->getBody();
}
catch (HttpException $ex)
{
echo $ex;
}
?>
########### Python 2.7 #############
import httplib, urllib, base64
headers = {
# Request headers
'Ocp-Apim-Subscription-Key': '{subscription key}',
}
params = urllib.urlencode({
})
try:
conn = httplib.HTTPSConnection('www.haloapi.com')
conn.request("GET", "/stats/h5/matches/{matchId}/events?%s" % params, "{body}", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64
headers = {
# Request headers
'Ocp-Apim-Subscription-Key': '{subscription key}',
}
params = urllib.parse.urlencode({
})
try:
conn = http.client.HTTPSConnection('www.haloapi.com')
conn.request("GET", "/stats/h5/matches/{matchId}/events?%s" % params, "{body}", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
require 'net/http'
uri = URI('https://www.haloapi.com/stats/h5/matches/{matchId}/events')
request = Net::HTTP::Get.new(uri.request_uri)
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"
response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body