universalis.js

universalis.js is a promise-driven wrapper for the Universalis API, written in Node.js.

Universalis is a crowd-sourced aggregator of market board data for FFXIV. This package is unofficial and is not supported by the Universalis developers.

Installation

npm i universalis.js --save

Usage & Examples

Import and initialize the module:

import Universalis from 'universalis.js'
const uni = new Universalis()

.getListings(worldDcRegion, itemIds, options)

Retrieves the current listings for an item. This data includes the quality, price, quantity and the time that the listing was created.

Parameters

worldDcRegion [string]

A specific world (e.g. Cerberus) or data center (e.g. Chaos) that you wish to retrieve the data for. Providing a data center will return data for all worlds within it.

itemIds [string][array]

An ID that corresponds to an item. IDs can be found via the Universalis app or via the marketableItems method.

By providing an array of IDs, you can retrieve data for multiple items at once. Make sure to do this to prevent hitting rate limits and to maximize performance.

options [object]

An object that contains the optional parameters that can be used to refine your results. These options include: listingLimit, tax, hq listingLimit [number]: The amount of listings that should be returned. The listings will be ordered by price from lowest to highest. tax [boolean]: If city-state tax should be included in the total price for each listing. hq [boolean]: If listings should be limited to HQ items only.

Example

Retrieve 10 HQ listings on the world 'Cerberus' for the item 'Fat Cat' (9347)

const getFatCatListings = async () => {
	const listings = await uni.getListings('cerberus', '9347', { hq: true, listingLimit: 10 })
}

.sortListingsByWorld(listings)

Sorts listings into an associative array with data grouped by world name.

Parameters

listings [array]

Data returned from the getListings method.

Example

Retrieve listings on the data center 'Chaos' for the item 'Fat Cat' (9347) and sort them by world.

const getFatCatListings = async () => {
	const listings = await uni.getListings('chaos', '9347')
	const sorted = uni.sortListingsByWorld(listings)
	// access listings on Spriggan:
	sorted['Spriggan']
}

.getSales(worldDcRegion, itemIds)

Retrieves the previous sales for an item. This includes the quality, price, quantity and time of the sale.

Parameters

worldDcRegion [string]

A specific world (e.g. Cerberus) or data center (e.g. Chaos) that you wish to retrieve the data for. Providing a data center will return data for all worlds within it.

itemIds [string][array]

An ID that corresponds to an item. IDs can be found via the Universalis app or via the marketableItems method.

By providing an array of IDs, you can retrieve data for multiple items at once. Make sure to do this to prevent hitting rate limits and to maximize performance.

Example

Retrieve previous sales on the world 'Cerberus' for the item 'Fat Cat' (9347)

const getFatCatSales = async () => {
	const sales = await uni.getSales('cerberus', '9347')
}

.sortSalesByDay(sales)

Sorts sales into an associative array with data grouped by the date of sale. Dates are in the YYYY-MM-DD format.

Parameters

sales [array]

Data returned from the getSales method.

Example

Retrieve sales on the world 'Cerberus' for the item 'Fat Cat' (9347) and sort them by the date of sale. Dates are in the YYYY-MM-DD format.

const getFatCatSales = async () => {
	const sales = await uni.getSales('cerberus', '9347')
	const sorted = uni.sortSalesByDay(sales)
	// access all sales on 2019-04-22:
	sorted['2019-04-22']
}

.validateMarketableItem(itemId)

Checks if a provided item ID can be sold on the market board. Returns either true or false.

Parameters

itemId [string]

The item ID that you wish to validate.

.getTaxRates(world)

Retrieves the tax rates for each city in which your retainers can list items on the market board.

Parameters

world [string]

The world (e.g. Cerberus) that you wish to retrieve data for.

.getMarketableItems()

Retrieves an array of every ID of items that can be listed on the market board.

.getMostRecentlyUpdatedItems(worldDc, options)

Retrieves an array of recently updated items on a specific world.

In this context, recently updated means that a player who is contributing to Universalis' data has searched for the item via the market board in-game.

Parameters

worldDc [string]

The world (e.g. Cerberus) or data center (e.g. Chaos) that you wish to retrieve data for.

options [object]

An object that contains the optional parameters that can be used to refine your results. Currently, these options only include: entries [int]: The amount of results to return. Valid values range from 1-200. Defaults to 50.

.getLeastRecentlyUpdatedItems(worldDc, options)

Retrieves an array of recently updated items on a specific world.

In this context, recently updated means that a player who is contributing to Universalis' data has searched for the item via the market board in-game.

Parameters

worldDc [string]

The world (e.g. Cerberus) or data center (e.g. Chaos) that you wish to retrieve data for.

options [object]

An object that contains the optional parameters that can be used to refine your results. Currently, these options only include: entries [int]: The amount of results to return. Valid values range from 1-200. Defaults to 50.

.getRecentlyUpdatedItemsLegacy()

Retrieves an array of recently updated items. This method provides no context to the data and is across every server and region.

.getUploadCounts()

Retrieves data regarding the contributions from users.

This method returns the following:

World Upload Counts

The total upload count per world and the percentage of the total data that it represents.

Upload Application Counts

The total upload count and name of each application that contributes data to Universalis.

Upload History

The number of uploads per day over the past 30 days.

Example

const getUploadData = async () => {
	const data = await uni.getUploadCounts()
	const worldCounts = data[0]
	const applicationCounts = data[1]
	const uploadHistory = data[2]
}