Skip to content

Latest commit

 

History

History
106 lines (59 loc) · 5.35 KB

api.md

File metadata and controls

106 lines (59 loc) · 5.35 KB

Enka.Network - API

Game API Docs

Getting Started

You can utilize some wrappers made by other people, or use the API directly. It's very simple, so it is not hard at all to hand-roll your own data logic based on the responses. The biggest challenge is navigating the datamined game data and attaching it to the data returned in the right way.

See Wrappers for the language of your choice.

Before You Request

A couple of rules on using the API:

  1. Please don't try to enumerate UIDs or try to do massive query jobs in an effort to fill a database. There are hundreds of millions of UIDs and you simply won't be able to do this through this API. I may provide batch data at a later point.

  2. Please set a custom User-Agent header with your requests so I can track them better and help you if needed.

  3. There are dynamic ratelimits on UID endpoints - if you're requesting too fast, you'll run into slower response times and eventually a 429 return code. This mean you either need to slow down or contact me to see if it's possible to increase the ratelimits for you. In most cases it's not needed and is a result of unoptimized code.

  4. On this note, all UID requests return a ttl field - this field is "seconds until the next Showcase request will be made for this UID". Until it runs out, the endpoint will return cached data, but you will still consume your ratelimit if you repeatedly hit it. Try to either cache the data with a timeout of ttl upon request, or prevent requests to the UID until its ttl runs out. I recommend Redis for this.

If you have difficulties working with the data, hop on the Discord server for help.

List of APIs

UID endpoints

Get Showcase data with full player info

https://enka.network/api/uid/618285856/

The response will contain playerInfo and avatarInfoList. playerInfo is the basic data about the game account. If avatarInfoList is missing, that means the Showcase of this account is either closed or not populated with characters.

Get only player info

https://enka.network/api/uid/618285856/?info

By attaching ?info to the request, you are requesting only playerInfo. The main request always tries to get avatarInfoList as well; if you only need playerInfo, please use this endpoint - it will be much faster than getting the full data.

In addition, both responses will contain an owner object if:

  1. The user has an account on the site
  2. The user added their UID to the profile
  3. The user verified it
  4. The user set its visibility to "public"

More info on user accounts below.

HTTP response codes

Please make sure to handle these in your app appropriately.

400 = Wrong UID format
404 = Player does not exist (MHY server said that)
424 = Game maintenance / everything is broken after the game update
429 = Rate-limited (either by my server or by MHY server)
500 = General server error
503 = I screwed up massively

Profile endpoints

It is possible to create an account (profile) on the website and attach several game accounts to it. The users are then required to verify that the account belongs to them via a verification code placed in their signature - this way we can ensure the account belongs to them.

Users can "snapshot" builds under custom names, referred as "saved builds".

https://enka.network/api/profile/Algoinde/

Gets the user info.

https://enka.network/api/profile/Algoinde/hoyos/

Gets a list of "hoyos" - Genshin accounts and their metadata. This only returns accounts that are verified and public (users can hide accounts; unverified accounts are hidden by default). Each key in the response is a unique identifier of a hoyo which you need to use for the subsequent requests to actually get the characters/builds information.

https://enka.network/api/profile/Algoinde/hoyos/4Wjv2e/

Returns metadata for a single hoyo.

https://enka.network/api/profile/Algoinde/hoyos/4Wjv2e/builds/

Returns saved builds for a given hoyo. This is an object of arrays, where the key is avatarId of the character, and objects in arrays are different builds for a given character, in no particular order (but they do have an order field you need to order by for display).

If a build has a live: true field, that means it's not a "saved" build, but simply what was fetched from their showcase when they clicked "refresh". When refreshed, all old live builds are gone and new ones are created. Only the user decides when to perform this refresh - this data will NOT be up-to-date.

As outlined in UID endpoints, when you make a UID request, you could get an owner object. You can construct the URL using these fields in the object:

https://enka.network/api/profile/{owner.username}/hoyos/{owner.hash}/builds/

Wrappers

TS/JS - https://www.npmjs.com/package/enkanetwork.js - Jelosus1

TS/JS - https://github.com/yuko1101/enka-network-api - yuko1101

Rust - https://github.com/eratou/enkanetwork-rs - eratou

Python - https://github.com/mrwan200/enkanetwork.py - mrwan200

Python - https://github.com/seriaati/enka-py - seriaati

Java - https://github.com/kazuryyx/EnkaNetworkAPI - kazury