Stats

API change history

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

Try it

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

  • string
    Subscription key which provides access to this API. Found in your Profile.

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