ffxiv-datamining is a shared CSV archive of Final Fantasy XIV game data

A repository of extracted tables, kept in version control for a reason

The xivapi ffxiv-datamining repository exists to be a place to share data mining information related to Final Fantasy XIV, with all findings and knowledge that each member discovers provided there for the FFXIV community to read, learn and use.

The core of it is the csv/ folder. The repository keeps a record of CSVs extracted via XIVData Oxidizer, and the stated reason is so they can be easily linked and referenced when datamining, so there is a git history of changes, and to make life easier in some cases.

That third reason is the one that matters most in practice. Because the extracted tables are committed to git, every patch that changes the game's data shows up as a diff. The idea stated in the README is to maintain an easy diffing view of what has changed during a patch. For anyone building a spreadsheet, a parser, or a mod that depends on hardcoded row IDs and column values, that is the difference between discovering that your data broke and finding out from a patch note weeks later.

The repository is not a software project in the usual sense. The primary language is recorded as unknown, there are no releases, and the top-level entries are .gitignore, .gitmodules, README.md, csv/, docs/, ex/, research/ and uld/. There is a .gitmodules file, which is what you would expect from a repository that pulls in one related tool as a submodule.

The audience is people who reverse engineer the game for a living or for fun, and who would otherwise each keep their own copy of extracted tables that drifts out of date.

Two documentation directories split knowledge from raw research

The repository separates what it knows from what it is still working out, and the split is visible in the directory names.

docs/ is the Documents of Knowledge, a set of write-ups on various FFXIV systems, linked from a README.md inside the folder. This is the part that would be useful to a newcomer, because a system explained in prose is worth more than a table of numbers. The research/ directory is the other half, described as research and resource files, also with its own README.md.

The distinction matters because datamining is a process, not a destination. Research files are working notes, possibly wrong, and knowledge documents are the settled version. The README encourages a specific kind of contribution: if you find a connection between files, for example a number in one column matching numbers in another column or in another file, or you identify what a set of values means, for example ClassJob ID or Craft Level, then throw up an issue on the repository.

That contribution model is a wiki pattern rather than a pull request pattern. Issues are the inbox for findings, and the acknowledgement section credits named community members such as Clorifex of GarlandTools, Hezkezl of Gamer Escape, Icarus Twine, Miu of TeamCraft, Ioncannon of FFXIV Explorer, Vekien of xivapi and Raelys of XIVData Oxidizer, with an invitation to add your own credit.

So the value of the repository is partly the data and partly the accumulated map of how the data fits together. The second part is what you cannot regenerate by running an extractor yourself, and it is why the docs/ directory carries most of the weight for a newcomer.

Refreshing the CSVs means running the oxidizer against a game install

The CSV update procedure is documented, and it is a four-step sequence you run locally.

First, download XIVData Oxidizer, the extractor by mattantonelli. Then build and run it against your installed game:

- Build and run: `cargo run -- "C:\Program Files (x86)\Square Enix\FINAL FANTASY XIV - A Realm Reborn"`

That command takes the path to the game installation as an argument and writes its output to a folder. The next step is to copy the contents of the output folder to the /csv folder, and the last step is to push a PR.

Note what this implies about the workflow. Regenerating the archive requires a local copy of the game client, which means a Windows installation at the default path, since the documented command is a Windows path. It also means the update is a manual extract-and-copy rather than an automated job, and the copy of the output folder onto the csv folder is a wholesale replacement, so the diff in the pull request is the diff that matters.

There is also a subtlety the README raises about the regional clients. The Korean and Chinese versions of the game are on different patches than the official live client, and it would be very useful to keep a history of ex.json files from SaintCoinach for each patch. The ex/ folder is the attempt at that.

The ex/ folder holds an archive of the SaintCoinach ex.json file, whose main point was to keep an ex.json file per patch. If you want to extract data from an older patch, for instance a Korean or Chinese client, you can hot-swap the ex.json file and extract the data in the correct format.

The ex hot swap works until the game adds a new structure

The README is honest about the limits of the hot-swap approach, and this is the most useful piece of advice in it.

It states that this kind of hot swap does not always work, because new structures are detected that are implemented into SaintCoinach, or you may have systems that expect data in a specific way, giving the example of the great Tooltip Descriptions Changes of Patch 4.4.

The underlying reason is that ex.json is SaintCoinach's own description of the game's data structures, so when Square Enix changes a structure and SaintCoinach updates to understand it, an old ex.json no longer describes the game correctly. And structures that carry meaning can be reshaped in ways that are not backwards compatible, which is why a change to tooltip descriptions can break an extraction pipeline even though nothing about the table structure obviously changed.

There is a fallback offered, and it is the one the author prefers. You can just grab an old version from git history, which the author says they may switch to linking to instead of keeping copies.

So the folder is in a transitional state, and the direction of travel is toward not storing per-patch copies of ex.json at all and instead pointing at the git history. That is a better design for a repository that has to track patch after patch, but it means the per-patch files currently in ex/ are useful for now and the history is the more reliable source in the long run.

The uld/ folder is simpler. It is an extract of FFXIV UI Elements, the images, extracted from SaintCoinach. Those are referenced by the game for its interface, and having them extracted means a tool can render or inspect interface pieces without the game running.

Becoming a dataminer is three steps and a text editor

The getting-started path is deliberately low-friction.

The README says getting started in FFXIV data mining is quite easy, and that if you enjoy digging around CSV database files then you have come to the right place. The recommended start is to download this repository and look at the files in the /csv folder, then to download SaintCoinach and use either the SaintCoinach.Cmd or Godbert tools. Saint provides releases at the xivapi SaintCoinach releases page.

The three-step summary is blunt about what the payoff is. Step 1, extract CSV data. Step 2, find where bluemage is. Step 3, profit.

The bluemage reference is a joke about the fact that the FFXIV datamining community has historically been dominated by people hunting the blue mage mask, and it is also an accurate description of the shape of the data. The game ships a large number of tables with numeric identifiers as foreign keys, and finding the connection between them is the work.

The two tools mentioned serve different needs. SaintCoinach is the extraction engine that reads the game's data files, and it is what produces the tables. Godbert is a separate project for exploring and querying the extracted data, and it is what you would use once you have the CSVs to look at them in a structured way.

The division of labour across the wider community projects named in the acknowledgements is worth noting too. GarlandTools, Gamer Escape, TeamCraft and FFXIV Explorer are all downstream consumers of exactly this kind of extracted data, so the tables in csv/ are the raw layer that several public tools are built on. That is a good reason to treat this repository as a shared dependency rather than a personal scratchpad, and also a reason to be careful about pulling it into a build pipeline given the licence situation.

No licence, no releases, and a fast-moving upstream

Two facts about the project state deserve to be stated plainly for anyone considering depending on it.

First, there is no licence. The licence field is recorded as unknown, and unlike every other project in this series the README does not contain a licence section at all. That is not a formality. Without a licence grant, the default copyright rules apply, and the legal position on reuse and redistribution is therefore unclear. For a personal reference copy of game tables that is a nuisance. For a tool you publish, or a dataset you redistribute, it is a blocker that needs resolving with the maintainers rather than assuming.

Second, there is no release series. The repository has no GitHub releases, so there is no versioned artifact to depend on. What you consume is whatever is in the master branch at the time you clone it, and the last push was on 2026-10-20. The stability of the contents therefore depends entirely on how actively the extraction is being refreshed, which the README does not commit to in a schedule.

The upstream dependency is also moving. Square Enix ships the game, XIVData Oxidizer reads it, SaintCoinach interprets it, and this repository stores the result. A patch to the game can change the extracted tables, can change the structures SaintCoinach understands, and can therefore change both the csv/ contents and the tools you use to read them. The per-patch ex.json archive and the ex/ folder exist precisely because of that churn.

The pragmatic approach is to treat csv/ as a snapshot with a patch number attached, record which patch your tooling was built against, and pull a fresh copy when a patch lands rather than assuming the master branch is stable.

Editorial conclusion

ffxiv-datamining suits a FFXIV modder, theorycrafter or spreadsheet author who needs a reference for the game's data tables and wants to see what a patch changed. It does not suit someone who needs a supported library or a tool with a licence they can rely on, since the repository records no licence and the primary language is unknown. Before depending on it, check whether the csv/ directory has been regenerated for the patch you are on, and read the ex/ folder notes before hot-swapping an ex.json against a different regional client.

Frequently asked questions

Official sources

1. Issues
2. README
3. xivapi/ffxiv-datamining on GitHub