Home

Initialization

const XIVAPI = require('xivapi-js')

const xiv = new XIVAPI()

It's just that easy!

Global Parameters

An optional object that can be provided during initialization. These parameters are passed on pretty much all requests if set, but you can override them (except for staging) on requests that take a param object.

For example, if you define language: 'ja' in the global parameters, using xiv.search("Ifrit") will return results in Japanese but doing xiv.search("Ifrit", {language: 'fr'}) will give results in French, ignoring the global setting.

Name	Type	Default	Description
private_key	string	undefined	The API key for your account. You can get this from your XIVAPI account page.
staging	bool	false	Use the XIVAPI staging server (https://staging.xivapi.com), like the rebel you are.
language	string	'en'	Language to fetch results in, out of these.
snake_case	bool	false	Returns all result fields in lower_snake_case rather than UpperCase.

const xiv = new XIVAPI({
  private_key: 'someKey',
  language: 'ja',
  snake_case: true
})

General Structures

Status

All responses from get() requests contain a status object with some information about the given result.

Name	Type	Description
ok	bool	Returns true for a successful request, or false when something went wrong.
id	int	The state ID retrieved from the Info structure. See Info.
state	string	The name of the state retrieved from the Info structure. See Info.
updated	Date	The time this resource was last updated.

Example:

{
  ...
  status: {
    ok: false,
    id: 3,
    state: 'STATE_NOT_FOUND',
    updated: 2019-01-08T10:46:06.000Z
  }
}

Info

Status is derived from the Info field, which holds information about the resource that was accessed given by XIVAPI. ((more about the structure and holding related types))

State	Value	Information
STATE_NONE	0	Content is not on XIVAPI and will not be added via this request.
STATE_ADDING	1	Content does not exist on the API and needs adding. The Payload should be empty if this state is provided. It should take 2 minutes or less to add the content.
STATE_CACHED	2	Content exists in the system and you're being provided a cached response.
STATE_NOT_FOUND	3	Content does not exist on The Lodestone.
STATE_BLACKLIST	4	Content has been Blacklisted. No data can be obtained via the API for any application.
STATE_PRIVATE	5	Content is private on lodestone, ask the owner to make the content public and then try again!

{
  ...
  Info: {
    Achievements: null,
    Character: {
      State: 2,
      Updated: 1546877725
    }
  }
}

Pagination

For calls that support pages (like search, etc) the returned object contains a Pagination element that looks like this:

{
  ...
  Pagination: {
    Page: 1,             //current page
    PageNext: 2,         //next page, if applicable
    PagePrevious: null,  //previous page, if applicable
    PageTotal: 12,       //total number of pages
    Results: 100,        //number of results in this page
    ResultsPerPage: 100, //number of results per page
    ResultsTotal: 1168   //total number of results
  }
}

You can use this and the page request parameter to effectively navigate through content.

Usage

All API methods return Promises, so you can handle their output in one of two ways:

then/catch methods:

xiv.search("Shroud Cherry Sapling").then((response) => {
  // do something with the response
}).catch((error) => {
  // do something with the error
})

using await with try/catch blocks in an async function:

try {
  let response = await xiv.search("Shroud Cherry Sapling")
  // do something with the response
} catch(error) {
  // do something with the error
}