Common Features

Global Params

These params work on almost every API route.

This will tell the API to handle the request and the response in the specified language. For Chinese, please use Waking Sands

To help with development; you may want to use the simplified field Name. If you can provide the query language=fr and now Name will be the French name. This is also extended to other string fields such as Descriptions.

Search will use the language parameter to decide which field to query the string against, for example: language=fr&string=LeAwsome will search for LeAwesome on the field Name_fr.

This will provide a nice pretty JSON response, this is intended for debugging purposes. Don't use this in production as it adds weight to the response and queries will be longer.

All API responses by default are UpperCase as this is the format the game data is extracted, to maintain consistency all endpoints will return data in UpperCase format, however if you prefer snake case this will convert all UpperCaseFields into lower_snake_case_fields.

This query allows specific columns to be pulled from the data and exclude the rest of the JSON response. This allows you narrow down to specific bits of information and reduce the size of the payload to your application. For nested data you can use dot notation (to a max of 10 nested nodes) to access it, for example:

[
    {
        "ID": 2901,
        "Icon": "\/i\/040000\/040635.png",
        "Name": "Choral Chapeau",
        "ClassJobCategory": {
            "Name": "BRD"
        }
    },
    {
        "ID": 2902,
        "Icon": "\/i\/041000\/041041.png",
        "Name": "Healer's Circlet",
        "ClassJobCategory": {
            "Name": "WHM"
        }
    },
    {
        "ID": 2903,
        "Icon": "\/i\/040000\/040634.png",
        "Name": "Wizard's Petasos",
        "ClassJobCategory": {
            "Name": "BLM"
        }
    }
]

For list content, `columns` will be done on all entries within the list. On non-list content the whole document is treated.

Sometimes a piece of data will have an array of sub data, for example:

{
    "ID": 1,
    "Name": "Example",
    "Items": [
        {
            "Name": "foo"
        },
        {
            "Name": "bar"
        }
    ]
}

To access the data in `Items` individually you could do

However, if you imagine an array having 50 items this could become tedious. You can therefore use a count format, eg:

This will return 50 rows from the column `Items` using the index `Name`, even if there are only 30 legitimate columns, 50 fields will be returned. This is intentional so you can build models knowing at all times X number of columns will return. You can use the FFXIV CSV files to know exactly how many there are exactly.

If you are unsure on the exact number of entries in the array or you do not mind a flexible amount you can ignore the number to get all entries in the array, eg:

Exceptions

When copy/pasting errors to XIVAPI, remember to remove your API Key!!!!

The API provides all errors and exceptions in JSON format, even if it is unrelated to the API itself. This is to ensure your code can always check for an error response and safely manage it. The API will attempt to use the correct HTTP code in all situations, otherwise it will default to a 500.

Here is a typical response structure:

{
    "Error": true,
    "Subject": "XIVAPI Service Error",
    "Message": "The details of the error message",
    "Hash": "A sha1 trackable hash of the error message",
    "Ex": "The name of the exception thrown",
    "Debug": {
        // Data in here can change, it helps the XIVAPI developers understand bugs
        // Please do not code against this structure as it can change at any time.
    }
}