SC2 Pulse is the fastest and most reliable ranked ladder tracker for StarCraft®2. It is a Spring Boot web application. The reference website (runs the latest release) is available 24/7. The public discord bot is also available.

This application uses Battle.net® API. This is not an official Blizzard Entertainment® application.

Please do not use this project as a reference if you are new to programming.

This is my first Spring Boot project, and it's old, there is a lot of legacy code that is poorly though out.

I use this project to learn new stuff, so it's just a bunch of helloworlds of different technologies that evolve over time. Furthermore, I'm only interested in backend stack, so the frontend part of the project is a mess. I focus on new features and I don't have time to rewrite the old code. The project will remain as it is until I implement all the planned features.

• Java 17
• PostgreSQL 15 with btree_gist extension
• Maven 3
• BattleNet API access keys(you must use your own keys)
• Twitch API keys(you must use your own keys)
• Aligulac API key(you must use your own key)

Run the tests to ensure that you have a valid environment set up. You must also pass the tests before creating a PR.

A real PostgreSQL database with btree_gist extension is required for some integration tests. This should be only a testing db, as tests will drop/create the schema. Do not use your real DB.

You can use the src/test/resources/application-private.properties file (ignored by git, used by a test config) to create a simple test config:

spring.datasource.username={name}
spring.datasource.password={pasword}
spring.datasource.url=jdbc:postgresql://localhost:5432/{test_db_name}
spring.security.oauth2.client.registration.sc2-sys-us.client-id={client_id}
spring.security.oauth2.client.registration.sc2-sys-us.client-secret={client_secret}
spring.security.oauth2.client.registration.sc2-sys-eu.client-id={client_id}
spring.security.oauth2.client.registration.sc2-sys-eu.client-secret={client_secret}
spring.security.oauth2.client.registration.sc2-sys-kr.client-id={client_id}
spring.security.oauth2.client.registration.sc2-sys-kr.client-secret={client_secret}
discord.token={token}
spring.security.oauth2.client.registration.discord-lg.client-id={client_id}
spring.security.oauth2.client.registration.discord-lg.client-secret={client_secret}
twitch.client-id={client_id}
twitch.client-secret={client_secret}
com.nephest.battlenet.sc2.aligulac.api.key={api_key}

To run all the tests execute the following command in a terminal

mvn verify

The Firefox is used in selenium tests because it is one of the major browsers that is available on all platforms and has an ESR version, which makes it easier to find a correct selenium driver for it.

You can change the browser by modifying the selenium.driver application property.

The dev profile will help you to start the local server. Reload a browser tab to instantly see resource modifications. Build project to hotswap(if possible) the new classes.

You must set the following application properties:

server.port={port}
spring.datasource.username={name}
spring.datasource.password={pasword}
spring.datasource.url=jdbc:postgresql://localhost:5432/{db_name}
spring.security.oauth2.client.registration.sc2-sys-us.client-id={client_id}
spring.security.oauth2.client.registration.sc2-sys-us.client-secret={client_secret}
spring.security.oauth2.client.registration.sc2-sys-eu.client-id={client_id}
spring.security.oauth2.client.registration.sc2-sys-eu.client-secret={client_secret}
spring.security.oauth2.client.registration.sc2-sys-kr.client-id={client_id}
spring.security.oauth2.client.registration.sc2-sys-kr.client-secret={client_secret}
spring.security.oauth2.client.registration.sc2-lg-eu.client-id = {client_id}
spring.security.oauth2.client.registration.sc2-lg-eu.client-secret = {client_secret}
spring.security.oauth2.client.registration.sc2-lg-us.client-id = {client_id}
spring.security.oauth2.client.registration.sc2-lg-us.client-secret = {client_secret}
spring.security.oauth2.client.registration.sc2-lg-kr.client-id = {client_id}
spring.security.oauth2.client.registration.sc2-lg-kr.client-secret = {client_secret}
discord.token={token}
discord.bot.invite.url={discord_bot_invite_url}
spring.security.oauth2.client.registration.discord-lg.client-id={client_id}
spring.security.oauth2.client.registration.discord-lg.client-secret={client_secret}
twitch.client-id={client_id}
twitch.client-secret={client_secret}
com.nephest.battlenet.sc2.aligulac.api.key={api_key}

The server will run without errors if these properties are missing, but the corresponding features will be disabled.

com.nephest.battlenet.sc2.replaystats.api.key

You can use the src/main/resources/application-private.properties file (ignored by git, used by config) for private/local application properties

Use DB init script to create a fresh DB.

To run the local server execute the following command in a terminal

mvn spring-boot:run

Scheduled tasks are disabled in the dev mode. You can remove the @Profile annotation from the Cron class if you want to run the tasks(like ladder scans) in the dev mode.

The Blizzard API can sometimes break and return stale data. The app checks the API state before every update and will switch the endpoint route if any problems are found. This happens automatically and individually for each region, so you can have a situation when KR region uses the alternative route, while other regions use the usual route.

Alternative update limitations:

• no league tiers
• no BattleTags
• partial racial info
• slower update

The missing info can be fetched from the main endpoint when it's back up(it happens automatically).

Original idea by Keiras

You can manually remap some endpoints to use another API host. This is useful when one region is broken but others are not. See addForceAPIRegion method of the AdminController. Set application property com.nephest.battlenet.sc2.api.force.region.auto to true to enable auto remap algorithm.

The Blizzard web API can be used as a last resort when everything else breaks. It is disabled by default. Some endpoints can be manually redirected to web API via AdminController. You can enable auto web API by setting the com.nephest.battlenet.sc2.ladder.alternative.web.auto application property to true.

Even though the API is not forbidden via robots.txt, the Blizzard Developer API Terms Of Use clause directly forbids it

You May Not Data Mine Blizzard Products Or Services. Except as permitted through authorized use of the 
Blizzard Developer APIs, You will not perform any data-mining, scraping, crawling, or use any processes that sends 
automated queries to Blizzard or any Blizzard game, service, or website, or use any other similar methods or tools 
to gather or extract data other information from Blizzard or any Blizzard game or service.

To ensure that the potential violation is a minor one, the following rules are applied:

• a very low request rate is used
• the data is considered as if it came from the regular dev API and the relevant ToS and Privacy Policy are applied.

Use it at your own risk.

Cron class contains all scheduled tasks.

• com.nephest.battlenet.sc2.url.public public URL of your service
• com.nephest.battlenet.sc2.mmr.history.main.length 1v1 mmr history length in days, 180 by default.
• com.nephest.battlenet.sc2.mmr.history.secondary.length team mmr history length in days, 180 by default.
• com.nephest.battlenet.sc2.ladder.regions set of regions that will be updated, currently active regions by default.
• com.nephest.battlenet.sc2.db-dump-file path to the database dump.
• com.nephest.battlenet.sc2.api.request.limit.separate Activates legacy mode where each region uses a separate request limiter. False by default.
• com.nephest.battlenet.sc2.privacy.character.profile.update update characters directly from their bnet profiles. True by default.
• contacts.email
• contacts.discord.server
• contacts.discord.server.name
• contacts.twitter
• contacts.github
• security.remember-me.token.key key for signing remember-me tokens
• security.remember-me.token.max-age Max age(duration) of the cookie, P3650D(~10 years) by default

Want to make a bug report/feature request? Any contributions are welcome, see CONTRIBUTING for more information.

• Main license
• 3rd party licenses

SC2 Pulse is fully compliant with the Blizzard ToS.

• Requests per hour cap is guaranteed if your clock desync is within 5 seconds.
• Requests per second cap is guaranteed.
• BattleTags, player names, and matches are removed after 30 days from the moment they were deleted from the API

Battle.net, Blizzard Entertainment and StarCraft are trademarks or registered trademarks of Blizzard Entertainment, Inc. in the U.S. and/or other countries.