Skip to content

How to use the API

Jump to bottom
zvyap edited this page Mar 4, 2024 · 4 revisions

Note

Most of the request make by this libray is synchronize. May apply async method in the future.
If anything break (api call error / bug), feel free to open a Issue.

HoyoverseHttpRequestException is thrown on the line that call request to Hoyoverse official API.
Example below just show some example usage of the API, more usage feel free to refer to source code or auto completion of the IDE.
Exspecially those response object after calling the API.

Beware of each Game may provide different response after calling the API, feel free to open a Issue if you found something wrong.

The basic usage of the API library

public class HoyoAPIExample {
    private static final HoyoverseAPI api = new HoyoverseAPI(APIEnvironment.OVERSEA);
    //private static final HoyoverseAPI api = new HoyoverseAPI(APIEnvironment.OVERSEA, APILocale.ZH_CN); //Custom language

    public static void main(String[] args) {
        HoyoToken token = HoyoToken.of("your_ltuid", "your_ltoken"); //HoyoToken#of which support V1 & V2 token, RECOMMANDED

        HoyoverseAPI.buildGlobalInstance(APIEnvironment.OVERSEA, APILocale.JP); //Build global instance with custom language
        HoyoverseAPI.getGlobalInstance(); //Get global instance

        HoyoGetForumFullUserResponse response = api.getForumUser(token); //Get self forum user data
        //3 method below included in all response
        response.isSuccess(); //All response included this method to check whether the request is executed by Hoyoverse successfully
        response.getRetcode(); //All response included this method which return 'ERROR CODE' defined by Hoyoverse official API, positive mean healthy, negative number mean unhealthy
        response.getMessage(); //All response included this method which return message from Hoyoverse official API

        String accountId = "99999999"; //Forum user account id is same as TOKEN ID which you can get from URL when you visiting others profile page
        //https://www.hoyolab.com/accountCenter/postList?id=99999999 <- 99999999 is the account id
        System.out.println(api.getForumUser(accountId)); //Get others forum user data

        //Get basic account info with sensitive data being blurred
        System.out.println(api.getAccountInfo(token));

        //Get basic ingame data, such as: nickname, level, in game uid
        //Self game roles only
        System.out.println(api.getGameRoles(token, GameType.GENSHIN_IMPACT));
        System.out.println(api.getGameRoles(token, GameType.GENSHIN_IMPACT, ServerRegion.ASIA));
        System.out.println(api.getGameRoles(token, GameType.GENSHIN_IMPACT, ServerRegion.BILIBILI)); //Some region for China Mainland's server
        System.out.println(api.getGameRoles(token, GameType.GENSHIN_IMPACT, "InGameUID"));

        //Get forum user profile data
        System.out.println(api.getForumUser(token));
        System.out.println(api.getForumUser("otherUserAccountId"));
    }
}

Assume example below start with these variable

HoyoverseAPI api = new HoyoverseAPI(APIEnvironment.OVERSEA, APILocale.EN_US);
DailyCheckInFeature feature = new DailyCheckInFeature(api); //Create feature instance
HoyoToken token = HoyoToken.of("your_ltuid", "your_ltoken");

Features

Daily Check In Feature

//Get all reward
HoyoDailyCheckInRewardResponse response = feature.getAllReward(GameType.GENSHIN_IMPACT);
List<AwardsItem> rewards = response.getData().getAwards(); //Reward of this month, index 0 mean Day 1.
AwardsItem itemDayOne = rewards.get(0); //Unsafe, although it will exist in any circumstance, validate before getting the element in the List is still a good practice
String iconUrl = itemDayOne.getIcon(); //Icon URL of reward
String name = itemDayOne.getName(); //Beware of your reward item name given is according the locale you request to the API (locale is set when creating HoyoverseAPI instance)
int count = itemDayOne.getCount(); //Amount of the reward/item

//BEWARE OF REPEATED VARIABLE SINCE THIS IS JUST A EXAMPLE

//Get 'TODAY & CURRENT STATUS' info for daily check in
HoyoDailyCheckInInfoResponse response = feature.getDailyInfo(GameType.GENSHIN_IMPACT, token);
//Return date today with YYYY-MM-DD, 2024-03-04 
response.getData().getToday();
response.getData().isMonthLastDay(); //Is this check in last day of the month
response.getData().getShortSignDay(); //Get today checked in "DAY"
response.getData().getSignCntMissed(); //Get days missed
response.getData().isSign(); //Is today checked in?
response.getData().getTotalSignDay(); //Total "DAY" checked in
response.getData().getRegion(); //Region id given by the API
ServerRegion region = ServerRegion.getRegionFromId(GameType.HONKAI_IMPACT_3RD, response.getData().getRegion()); //To library ServerRegion enum, report to me if the getRegionFromId() return null in this case.

HoyoDailyCheckInInfoResponse response = feature.signDaily(GameType.GENSHIN_IMPACT, token); //Check in your daily check in
response.isCaptcha(); //If true mean you got captcha, # manually for few day and it will become normal

Advanced

All functions of this library is test in unit test, more advanced/details usage can be found inside.
https://github.com/zvyap/Hoyoverse-API/tree/master/src/test/java/com/zvyap/hoyoapi/test

Clone this wiki locally