New SC2 endpoints (What I've found)

API Discussion
First off thanks so much for releasing the new endpoints, and a big THANK YOU for fixing the match history bug if you have played a co-op game in recent history. That has been a thorn in my side for a very long time. After looking these endpoints over I have found a lot of data is no longer accessible via the latest endpoints. I'll list them below. I am really hoping this was just a first pass and there is more coming soon.

Bugs/Technical Issues:

  • (FIXED) GET - /sc2/player/:account simply times out (504 Gateway timeout)
  • The api feels sluggish the first time you hit an endpoint. i.e. the first time i tried to get my ladder summary i got a 504, the second time it loaded

Payload Issues, Concerns

  • Match History: it would be nice to have a way to query games played in a date range
  • Match History: It would be nice to add teamMember info into the payload (playerName, race, mmr, mmr change realm, region)
  • (FIXED)Season: The season endpoint needs the startDate and endDate added back in
  • (FIXED)Season: The season endpoint needs the seasonId added back in we need this for the league api that was just added back in. (as of the date this was added the season api does not include this)
  • Season: It would be nice to have the maps in the rotation in the payload as well (name, map, thumbnail, game_type, etc)
  • Player Profile (GET - /sc2/profile/:region/:realm/:id): it would be nice to remove or make optional achievements and rewards. The payload does not need to be that large
  • (FIXED)Ladder Summary: it would be nice to have the members realm as part of the payload. Since that is necessary to get player profiles now
  • (added on 11/28/2018) please fix or remove the highest rank finish from the profile payload, it has been out of date for a long time and if it is no longer being updated then it should be removed.

New endpoint Requests:

  • (ADDED) League Info: this endpoint is completely missing in the new api: it is absolutely necessary for building a league continum for the season
  • (new)Race Report: it would be nice to have a race report payload that mirrors what you see in game
  • (new)Season: It would be nice to get historical data for seasons
  • (new)General Game data: units/structures/stats it would be really cool to build an almanac about the units since this no longer exists on the main starcraft 2 site
  • (added to list on 11/28/2018) implementation of the looking forward section from this post: I would be very happy with the first two items on the list being implemented.
I completely agree with every point MooCow has stated. I want to emphasize that adding the missing league endpoint is crucial to many community projects relying on the SC2-API, including the bigger ones, such as rankedftw or sc2unmasked.

Moreover, I want to add a few thoughts on the Match History endpoint as I would highly welcome improvements on it - as of now it's of limited value due to missing data, but could be very valuable:

  • Give us more information on the game type - namely ranked/unranked and the players race. Just "1vs1" is insufficient to assign a match to a league, because we don't know if it was played in Ranked or Unranked and what race was played (1vs1 Ranked and Unranked is split with respect to the race).
  • Include the game length of the matches in addition to MMR related data mentioned by MooCow
  • Let us query a match history for specific game modes only - most endpoint users don't care for Arcade/Custom games and are only interested in Ranked.
  • Increase the number of games in the match history, especially if you don't let us query for certain game modes only - currently there might not be a single game in the match history of the game mode we are interested in.
11/09/2018 07:41 PMPosted by MooCow
GET - /sc2/player/:account simply times out (504 Gateway timeout)

Additionally, I'd like to ask a question: is 'account' parameter the same thing as 'id' in Profile API or Legacy API?

If not, how can I check my own account ID?
I believe it is
Any updates on any of this?

We've made a change to the account parameter in the API on the new tech stack. The accountId is a player's account ID and is returned from the GET /oauth/userinfo call. It is different from their profileId. We have updated the StarCraft II Community APIs documentation to clarify this point.

To acquire an account ID for any API call that requires it, see the "Getting a User's Account ID and BattleTag" section in the Authorization Code Flow.

Thanks for the feedback! Keep it coming so we can keep improving.
The endpoint Missing makes finding ladder ids extremely difficult. Hopefully this is just a slip up and it will be added.

I rely heavily on it on sc2replaystats, and I know that rankedftw and sc2unmasked also use it.
Mag, thanks for the update, i'd been trying this but it was always timing out, seems better as of tonight. thanks to whoever fixed it!
I vote for team members and (what's more important in 1v1) the opponent name or some string that would help identify the opponent.

btw I'm kind of scared of using the "legacy" endpoints. You know - the name indicates that they may be not supported in near future.
Okay, I found something else.

Test case:

The player has been playing ranked archon a lot. He's placed on a ladder called 'Goliath Phi', id 208998.

Ladders endpoint in Legacy API correctly labels that ladder as Archon ("matchMakingQueue": "LOTV_TWOS_COMP",).

However, new Ladder Summary endpoint in Profile API labels the same ladder as '2v2' ("localizedGameMode": "2v2") and there's no other option to differentiate between archon and actual 2v2 based on data itself. Using Legacy API endpoint is something I'd like to avoid.

The same problem applies to SC2 profile pages. The ladder mentioned above is incorrectly referred to as '2v2'.

Pretty please with a cherry on top. :)
And one more thing.

What's the rationale behind the Ladder endpoint in Profile API requiring player credentials (region id, realm id, player id) in order to access whole ladder object?

In legacy API it used to be simple: just provide region name and ladder id to receive whole JSON tree of 100 player profiles from a selected ladder. Simple enough.

Now, not only is it more complicated, but also player credentials don't seem to serve any purpose. It would be cool if providing those would have resulted in getting this player's stats from a selected ladder without having to filter out 99 other players' objects. For now it feels redundant.

Any chance for improvements upon the above?


Just noticed 'ranksAndPools' property which seems to be the answer why player data is required. But it contains only rank, MMR and bonus pool. Is there any chance to cast whole player object from 'teamMembers' subtree, or at least add wins and losses?
And something else.

Ladder endpoint doesn't expose number of ties any more. I do remember it being very unreliable in Mashery APIs. Lots of confirmed ties weren't showing up.

Are there plans of bringing this data back any time soon?
(missing) League Info: this endpoint is completely missing in the new api: it is absolutely necessary for building a league continum for the season

Seems to be working for me.



"_links": {
"self": {
"href": ""
"key": {
"league_id": 6,
"season_id": 37,
"queue_id": 201,
"team_type": 0
"tier": [
"id": 0,
"division": [
"id": 1,
"ladder_id": 271386,
"member_count": 188

What results have you seen MooCow? Also, I can't seem to find the docs in the old portal for this service. Can you point me to them?
League endpoints were never documented in Mashery portal, but there was a forum post announcing them:
Jack thanks for the reply, and great sleuthing to find that endpoint. The endpoint you listed isnt in the new api docs so its probably still a work in progress since some of these new endpoints have been simplified or streamlined. I'd expect that endpoint to change slightly.

The data that seems to be missing from the payload you posted is the max/min rating for each tier. On top of that its currently impossible to get all the info to build that url because the season endpoint doesn't return the season id anymore. I would expect the url to look like this once it is released:{regionId}/{queueType}

this would return the current season's league info for all ladder tiers and divisions.
Hey guys,

FYI: Updates about the SC2 API are posted here:
Thanks for the updates, I'm always glad to mark items as fixed on my list. Keep up the good work. Will we get the leagues endpoint any time soon? It would be nice to have that back.
Thanks to everyone in this thread who's been giving feedback and investigating the new APIs. I finished my own migration today and I'm sure I would have hit some of these issues had you guys not voiced feedback earlier. And thanks to Blizz devs for regular updates.

After migrating, my main feedback is performance - every API call takes between 10-15 seconds to run, including player profiles, match history, ladders summary, and ladder details. This is both the "legacy" APIs and the new APIs. Previously all of these calls were <1s. Is this a known issue?
What do you mean by "Note: Legacy endpoints are not being deprecated. However, legacy endpoints will no longer be updated. "?

Do you mean that the data retrieved in the api calls will not be updated?
12/05/2018 05:13 PMPosted by Velaarynne
Hey guys,

FYI: Updates about the SC2 API are posted here:

Glad to see those updates. Thank you very much!

Join the Conversation

Return to Forum