Character

Search and retrieve character data from The Lodestone. Providing useful information such as character profile data, minions and mounts obtained, achievements obtained and their relative dates. Character friends, their free company, pvp team and much more!



Search for a character on **The Lodestone**. This does not search XIVAPI but instead it goes directly to lodestone so the response will be "real-time". Responses are cached for 1 hour, it is important to know that Lodestone has a ~6 hour varnish and CDN cache.

Params

Param Description
name

The name to search for, you can use `+` for spaces or let the API handle it for you.

Searching name will automatically add quotations, this is to ensure better matching against short/common named characters.

server

*(optional)* The server to search against, this is case sensitive - You can obtain a list of valid servers via: Server List

You can provide a data center here, eg: server=_dc_Chaos

page

*(optional)* Search or move to a specific page.

There is currently no way to change the amount of results back returned. It will always be 50 per page with a maximum of 20 pages. This is due to how Lodestone works.

/character/[lodestone_id] #

https://xivapi.com/character/730968
Restricted Usage

A single source (User or Developer) can add a maximum of 100 characters within a 2 hour period, if you spam add thousands of characters then expect them all to be deleted, if you need thousands then please message Vekien in discord as a pre-warning.

Once a character is on XIVAPI this limit is not checked, it is only for the very 1st request, which can be done anyone (your character may already exist on the service!)

Get Character data, due to the nature of availability on the service this endpoint will return either populated data or nothing, you will have to check the Info response to see the current state. If the character does not exist on XIVAPI then this first request will return the state value 1 and the character will be added within the next few minutes. Query the endpoint again after a few minutes and it should contain data.

Params

Param Description
extended If set to 1, the API will return more data in the response by extending out the data IDs to useful objects.
data

By default only the `Character` data will return, you can request more data using the `data` query.

data
https://xivapi.com/character/730968?data=AC,FR,FC,FCM,PVP

Pass a long a comma separated list of codes that relate to specific data sets you would like to fetch, these are as follows:

AC Achievements
FR Friends List
FC Free Company (if added ot the system)
FCM Free Company Members (if added ot the system)
PVP PVP Team (if added ot the system)

Once you have the data you need, you can further reduce the data using the `columns` query

"Info" Statuses

At the top level of the response will be a `Info` field, this will contain the `State` and `LastUpdated` timestamp of various different pieces of character data. The `State` is a number and here is what they mean:

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!

/character/[lodestone_id]/verification #

https://xivapi.com/character/730968/verification

Calls Lodestone directly to retrieve the biography, this can be used for verifying character ownership. The response for this request will cache for 5 seconds to reduce spam.

Params

Param Description
token The token to test against, if the token is found then `Pass` will be true.

/character/[lodestone_id]/update #

https://xivapi.com/character/730968/update

Requests a character to be updated, this puts them at the front of the queue. You can do this once every 12 hours. Please note Lodestone has a "roughly" 6 hour player cache as well as Lodestone itself having a cache. The best way for a character to update is to logout and wait over night.

You will receive a true/false (1/0) response if this was successful:

Response Information
1 Character added to the front of the queue.
0 Character cannot be updated at this time.