Reading Sheets

API ReferenceOpenAPI specification for sheet endpoints.

Sheet endpoints retrieve data for one or more rows from a sheet, mapping values to match a schema. These endpoints support schema pins, but always use the latest local data release and ignore version. See Ensuring Stability for more information.

Language

Sheets with user-facing strings are commonly localised into all the languages supported by the game client. For more details on localisations and game editions, refer to Important Concepts.

While XIVAPI defaults to Simplified Chinese text in responses, other languages may be requested with the language parameter.

Supported codes are chs, tc, ja, en, de, fr and ko. Availability depends on the client data included in the release. Examples below use language=en when they show English values; displayed responses are excerpts, and game updates may change their values.

// /api/sheet/Item/42589?fields=Name&language=chs
{ "fields": { "Name": "天使之笔" } }
// /api/sheet/Item/42589?fields=Name&language=ja
{ "fields": { "Name": "天使の筆" } }
// /api/sheet/Item/42589?fields=Name&language=en
{ "fields": { "Name": "Angel Brush" } }
// /api/sheet/Item/42589?fields=Name&language=de
{ "fields": { "Name": "Engelspinsel" } }
// /api/sheet/Item/42589?fields=Name&language=fr
{ "fields": { "Name": "Pinceau angélique" } }
// /api/sheet/Item/42589?fields=Name&language=ko
{ "fields": { "Name": "천사의 붓" } }

Fields

Fields comprise the majority of the response for sheet endpoints. A number of tools are available to filter and tune the way fields are represented in responses.

Types

All fields have a type derived from a combination of the game data and schema in use. Types are used to define the overall structure of the data and how it is read.

Scalar

The most common field type, scalars represent a single value such as a number, string, or boolean.

Struct

Sometimes, sheets contain a collection of related fields. Schemas may represent this as a struct, grouping the fields under a shared parent field in the response.

Array

When consecutive fields represent a repetition of a value, schemas may group them into an array. Arrays always have a fixed length - unused entries are typically set to a null or zero value.

Additionally, scalars may have additional semantics supplied by their type:

Relationship

Field with values that represent a link to another sheet. Refer to field relationships for further information.

Icon

Numeric values representing an icon asset ID. XIVAPI will pre-compute the relevant paths for accessing the asset. A generated path does not guarantee that the image is in the published asset index.

Filtering

Sheets regularly contain more information than is needed for a single use-case. This quickly compounds when field relationships are present that link in additional rows of data. For example, the full response for the “Angel Brush” Item includes many nested relationships; its size depends on the active data and schema.

To reduce the amount of unnecessary data in responses, the fields parameter can be used to specify a subset of fields that should be included:

fields=Name,LevelEquip

// /api/sheet/Item/42589?language=en&fields=Name,LevelEquip
{
  "fields": {
    "Name": "Angel Brush",
    "LevelEquip": 99
  }
}

If a field is nested within a struct or relationship, dot notation is used to specify the path to access it:

fields=ItemUICategory.Name

// /api/sheet/Item/42589?language=en&fields=ItemUICategory.Name
{
  "fields": {
    "ItemUICategory": {
      "fields": {
        "Name": "Pictomancer's Arm"
      }
    }
  }
}

Array fields may be specified to retrieve values from all entries:

fields=BaseParam[].Name

// /api/sheet/Item/42589?language=en&fields=BaseParam[].Name
{
  "fields": {
    "BaseParam": [
      { "fields": { "Name": "Intelligence" } },
      { "fields": { "Name": "Vitality" } }
      // ...
    ]
  }
}

Not sure what field you want?

You can omit the fields parameter on the /api/sheet/{sheet}/{row} endpoint to see every field available for the active data release and selected schema. Fair warning, there may be quite a few!

Decorators

In addition to filtering the fields in the response, the fields parameter can also be used to specify “decorators” that modify how the field is read or presented in responses. To avoid collisions, decorators are included in the response field name.

@lang(<lang>)

While the language parameter can be used to change the default language used in a request, it may be necessary to retrieve two or more languages in the same request.

fields=Name,Name@lang(ja)

// /api/sheet/Item/42589?fields=Name,Name@lang(ja)
{
  "fields": {
    "Name": "天使之笔",
    "Name@lang(ja)": "天使の筆"
  }
}

If specified on a structural field, the provided language will act as the default for any nested fields:

fields=ItemUICategory@lang(de).Name

// /api/sheet/Item/42589?language=en&fields=ItemUICategory@lang(de).Name
{
  "fields": {
    "ItemUICategory@lang(de)": {
      "fields": {
        "Name": "Hauptwaffe der Piktomanten"
      }
    }
  }
}

@as(<transform>)

The as decorator performs transformations on fields to tailor the resulting values for particular use cases.

@as(raw) will prevent processing of field types such as relationships and icons, useful if the rich data is not going to be utilised.

fields=ItemUICategory,ItemUICategory@as(raw)

// /api/sheet/Item/42589?language=en&fields=ItemUICategory,ItemUICategory@as(raw)
{
  "fields": {
    "ItemUICategory": {
      "value": 111,
      // ...
      "fields": {
        // ...
      }
    },
    "ItemUICategory@as(raw)": 111
  }
}

@as(html) formats string values into HTML fragments, with support for most text and formatting features in the game’s rich text format.

fields=Description,Description@as(html)

// /api/sheet/Item/44104?language=en&fields=Description,Description@as(html)
{
  "fields": {
    "Description": "Warm flour tortillas filled with slices of marinated rroneek chuck that has been grilled to a smoky char.\n\nEXP Bonus: +3% Duration: 30m\n(Duration can be extended to 60m by consuming multiple servings)",
    "Description@as(html)": "Warm flour tortillas filled with slices of marinated rroneek chuck that has been grilled to a smoky char.<br><br><span style=\"color:rgba(0,204,34,1);\">EXP Bonus:</span> +3% <span style=\"color:rgba(0,204,34,1);\">Duration:</span> 30m<br>(Duration can be extended to 60m by consuming multiple servings)"
  }
}

Transient Sheets

As outlined prior, related data may be split into two or more sheets as an implementation detail. To reduce the number of requests needed to retrieve data, the API attempts to find transient sheets. The single-row endpoint includes their content in a top-level transient key by default when available. Row-list and search endpoints omit it unless requested.

To control these fields, the transient parameter can be provided. It accepts identical syntax to the fields parameter outlined above. Use transient= to omit transient fields, or transient=* to request them all.

transient=Description@as(html)

// /api/sheet/Action/34684?language=en&transient=Description@as(html)
{
  "fields": {
    // ...
  },
  "transient": {
    "Description@as(html)": "Quickly dash 15 yalms forward.<br><span style=\"color:rgba(0,204,34,1);\">Additional Effect: </span>Increases movement speed<br><span style=\"color:rgba(0,204,34,1);\">Duration: </span>5s<br>Cannot be executed while bound."
  }
}

Note

The check for transient sheets is naive - a request for the sheet Example will blindly return data for matching rows in the ExampleTransient sheet, if it exists.

While this approach works well for the majority of instances, always verify that the data looks appropriate before committing to using transient values.

Multiple Rows

All of the examples above have used the single-row endpoint, /api/sheet/{sheet}/{row}. If more than one row from the same sheet is desired, the row list endpoint is available.

All parameters outlined above are also available for the row list. Unlike the single-row endpoint, its default field filter is Name,Singular,Icon; request fields=* for all fields. Transient fields must also be requested explicitly.

By default, it will list all rows in ID order, starting from the first.

// /api/sheet/Item?language=en&fields=Name
{
  "rows": [
    { "row_id": 0, "fields": { "Name": "" } },
    { "row_id": 1, "fields": { "Name": "Gil" } },
    { "row_id": 2, "fields": { "Name": "Fire Shard" } },
    // ...
  ]
}

If provided, the after parameter will skip any rows less than or equal to the specified row ID. Additionally, the limit parameter can be used to adjust the maximum number of results returned in one response. Excessively large limits will be clamped to a server-defined maximum.

For sheets with subrows, use row_id:subrow_id in the row path, rows and after, for example after=10:2. Continue pagination after the last returned row and subrow. Do not combine rows with after; their joint behavior is undefined.

after=1&limit=2

// /api/sheet/Item?language=en&fields=Name&after=1&limit=2
{
  "rows": [
    { "row_id": 2, "fields": { "Name": "Fire Shard" } },
    { "row_id": 3, "fields": { "Name": "Ice Shard" } }
  ]
}

Alternatively, a list of row IDs can be provided if already known - useful for retrieving a batch of rows from a sheet.

rows=1,29,46

// /api/sheet/Item?language=en&fields=Name&rows=1,29,46
{
  "rows": [
    { "row_id": 1, "fields": { "Name": "Gil" } },
    { "row_id": 29, "fields": { "Name": "MGP" } },
    { "row_id": 46, "fields": { "Name": "Allagan Tomestone of Aesthetics" } }
  ]
}

Caution

Row IDs are not guaranteed to be contiguous. Listing rows iterates over existing records, but explicitly requesting a missing row through the single-row endpoint or rows returns 404; it is not silently omitted from a batch.