-
Notifications
You must be signed in to change notification settings - Fork 92
Obtaining Destiny Definitions "The Manifest"
The Destiny API can be logically divided into three sections:
- Historical Stats, an archive of what a player has done in the game over time.
- Live Data, the ability to pull a players' current state (including Equipment, Triumphs, progress, what they're playing right now etc)
- Static Definitions, a large set of data that defines the unchanging attributes for every entity in the game for whom the API returns data. Live Data and Historical Stats depend on Static Definitions to interpret the results: without it, live data and most stats are merely a set of meaningless numeric identifiers.
In this article, we are going to talk briefly about what you have to do to get Static Definitions. They are currently exposed in two formats: a very large JSON file and a fairly large zipped SQLite database.
To get at this data, you must:
- Query BNet to find the current location of the static definitions
- Download the static definitions
- (SQLite only) Unzip the SQLite database
- Understanding the data contained within
- Using it!
Call the GetDestinyManifest endpoint to retrieve an object that will include SQLite database and JSON definition file locations for every language. See the results object in the GetDestinyManifest link for details. Note that there is a different file per language.
Once you have obtained the URL for the file format and language(s) you desire, make a GET request to that URL to acquire them.
If you have chosen to use the SQLite databases, you'll receive a *.content file. That file is actually a ZIP file. ("it's a long story") Use a standard unzipping library and/or manually unzip it depending on your workflow to extract the actual SQLite database.
All Destiny Static Data refers to "Entities" which have matching "Definitions", and are referred to by numeric identifiers that we refer to as "hashes". Everything you see in game has an Entity Definition, along with many things not immediately apparent as you are walking around in the world. For instance, every type of item in the game has a matching "DestinyInventoryItemDefinition", and it also has a "hash" property. That hash property is its identifier, guaranteed to be unique for any DestinyInventoryItem but not guaranteed to be unique across different types of entities. For example, a Triumph may coincidentally have the same hash as an Item - this does not mean that they refer to the same entity. But no two Item Definitions can have the same hash.
Throughout the definitions, live data, and historical stats, you will see references to these hashes. You can use them to look up definition info, which will have things like human readable strings, icons, and other interesting and static information.
For the JSON files, all of the definitions are contained in a single JSON file. The outermost object is a dictionary with the key being the names of the Definition objects referred to in our documentation (for instance, this is the definition for "Records", also known as "Triumphs" in game)), and the value being a Dictionary with the key being the Hash of each entity, and the value being an object with all of the related definition information for that entity. Note that the keys are strings, even though in our documentation we refer to hashes as being unsigned integers.
For the SQLite database, you will see a table per type of entity. The "id" field matches the entity's hash, though because SQLite stores integers as signed you will need to convert any hashes you get in live/historical stats data to signed integers before you make the query, or you may not find the entity. The "json" property will be a JSON blob with data that is identical to the object you'd have found in the JSON file.
Look through our documentation for entities, see what fields they return. If you are feeling bold, you can try generating your own client to deserialize them from our swagger specs, but know that there are currently pending bugs in our Swagger Spec that will make using an out-of-the-box Swagger Codegen tool difficult. You may want to perform your own manual deserialization for the data that you need from objects for now given this situation.