Proposal: /v2/spvp/matches

[ghost]

Hello everyone!,

First of all: I am a bit new to github so excuse me if I forgot to do something or did do something wrong.

Currently there is no way to retrieve information about matches of sPvP. This API would enable us to look into the matches played by players and against who.

A small example:
// GET /v2/spvp/matches?character=Charizard

[
    {
        matchid: 1234,
        match_start: datetime,
        match_end: datetime,
        ranked: true,
        blue_score: 500,
        red_score: 350,
        blue:
        {
            Charactername,
            Charactername,
            Charactername,
            Charactername,
            Charactername
         },
        red:
        {
                "Charizard",
                Charactername,
                Charactername,
                Charactername,
                Charactername
        }   
    },
    {
        matchid: 4321,
        ...
    }
]

Personally I'd rather have this to be an open API, so that you can also track the matches played by friends or opponents. So a list of a few issues we need to think about:

Issue's:

• Should we change that Character parameter to a Account parameter, so you can see all matches on the whole account? If not: What do we do with players swapping during the match?
• Should we somehow be able to store the internal matchmaking score or leader board rank in a character or account so more information can be provided?
• Maybe include information such as if a player left a game?
• Include information about the players score at the end of the game?

It would be nice if something like http://www.lolking.net/ could be created, where you can enter a players name, see the matches and ranking and view statistics about opponents too.

[lye]

We're waffling on this one internally w.r.t how much data and under what situations it should be exposed publicly. It might be just Ranked matches exposed, or it might be some kind of in-game checkbox to opt into public data. Or it might just be API-key restricted see-your-data-only. Not yet sure. Dotabuff is roughly what we're using as a measuring stick.

While we figure out what/how to make stuff public, I'm working on exposing your personal data via API key stuff. Figure I'll tuck it behind the pvp permission (not yet sold on that). The /v2/pvp/games endpoint, as it currently functions, returns objects that look like --

{
    "id": "0CCC6919-B871-4198-957B-6EBFE8C34114",
    "map_id": 52,
    "date": "2015-06-06T07:40:09.000Z",
    "duration": 374.4,
    "result": "victory",
    "team": "red",
    "profession": "mesmer",
    "scores": {
        "red": 0,
        "blue": 501
    }
}

I think I'm probably going to swap out date/duration for start/end as you've got (seems a bit easier to manipulate).

The way the data's currently structured it's hypothetically possible for a match to have more than two teams, so however unlikely that is to change, I put the scores into an object rather than individual keys (which should make it a bit more forward-compatible).

Additionally, it may be better instead of ranked : true to have ladder : "Ranked" since presumably there could be additional ladders (e.g., the old SoloQueue/TeamQueue are technically also ladders; you can't play on them but their aggregate data is stored and displayed separately).

In response to your questions:

Should we change that Character parameter to a Account parameter, so you can see all matches on the whole account? If not: What do we do with players swapping during the match?

I think it makes the most sense to put the character name (rather than account name) in there, despite the switching issue. It might make sense to put both. Rosters aren't currently exposed to the API layer by the backend, so will need to look into how that's gonna be hooked up w.r.t character switching.

When rosters are exported, ideally I'd like to expose each player's character name, profession and build.

Should we somehow be able to store the internal matchmaking score or leader board rank in a character or account so more information can be provided?

The current word is that we can't expose the internal matchmaking numbers (e.g., match predictions and account MMRs). Leaderboard ranks will likely be exposed at some point via a separate endpoint so you can query for them meaningfully.

Maybe include information such as if a player left a game?
Include information about the players score at the end of the game?

Seems reasonable to me. The tough part is threading that data through all the bits and pieces, but I think we'll be able to have those bits in eventually.

[ghost]

The things you propose look good! I didn't knew there already was a /v2/pvp/games API in development/released. I think the key point that will determine the API's usability is if Rosters will be exported with data on builds of the participants.

The Ladder: "Ranked" is indeed a very good idea, I should have thought about that before.
I also see that I missed the Map_ID which is also good to have. Same about the scores!, if Hall of Heroes if ever implemented it would be necessary to add a yellow team. I also vote for the Character name instead of the Account name, I think that is a more direct approach, however listing them both might also not be a bad idea.

About Character Swapping: I wonder what would be the best approach for this. Normally players would only swap at the start of the game, so it might be an option of taking the character that was there when the game finished. But I guess that this is not waterproof. (Players could potentially abuse this and swap before the end of the game, to make people believe they won with a half-baked build)

I really hope that the Rosters can become public, but I can understand that this is still in discussion.
I am looking forward for more to come! Good luck developing!

[darthmaim]

I think it makes the most sense to put the character name (rather than account name) in there.

Lets hope you can figure #32 out and we get the a character id in there.

[lye]

I didn't knew there already was a /v2/pvp/games API in development/released.

I have the mind of a goldfish; I just started plumbing the data through last week and neglected to write up the details. I also have /v2/specializations and /v2/traits to write up at some point...

I think the key point that will determine the API's usability is if Rosters will be exported with data on builds of the participants.

Ultimately, yeah. I'm pretty sure the initial release of this endpoint will be without roster/builds though; the match history this pulls from is fairly ephemeral (not sure what the current/planned configuration is -- IIRC it's just the 10 most recent matches stored), so I'd rather have a partial implementation sooner. The full implementation (with all the goodies) will arrive at a later date.

Players could potentially abuse this and swap before the end of the game, to make people believe they won with a half-baked build

My understanding was that, once dishonor was enabled this would cause a match loss for the team (maybe that's the "forfeit" state?), but only in the ranked queue. Don't quote me on that though, might be mis-remembering. It's still a problem, but I'm not sure there's going to be a clean solution. We almost need play-by-play recountings of the entire match (e.g., skill usage log with locations + time indexes) in order to correlate it better.

I have a feeling that might be a bit infeasible though, not sure.

Lets hope you can figure #32 out and we get the a character id in there.

#32 doesn't help you if /v2/characters requires an API token to resolve the ID to a name though.

[jstraw]

So, I kinda feel that this is a minimal version of https://forum-en.guildwars2.com/forum/community/api/Proposal-Structured-PvP-API/first

I don't have time to post it here, but hopefully linking this will help flesh this out with events and data.

[lye]

Yeah, the first release is going to be very minimalistic. It's just a limitation of what data we're currently piping through the system; it'll take some time and coordination to pull the rest through. Figured we'd put out what we've got now then continue to improve it.