XIVAPI Client

The Client class is the core of this library, and thus has the most features. It takes a bit to walk through all of them, so it's best to categorize them by feature:

Getting data from Sheets¶

The easiest item is fetching row(s) from sheets as mentioned in the quickstart, but there's a lot of extra options for the sheets method, which changes the return type. In short:

Using row= results in one (or None) Model returns
Using rows= results in an async iterator which return Model(s)

Some brief examples:

Sheets - One Item¶

class ContentFinderCondition(xivapy.Model):
    row_id: int
    Name: str

async with xivapy.Client() as client:
    result = await client.sheet(ContentFinderCondition, row=44)

Sheets - Multiple Items¶

class ContentFinderCondition(xivapy.Model):
    row_id: int
    Name: str

client = xivapy.Client()
async for row in client.sheet(ContentFinderCondition, rows=[1, 2, 99, 41, 6])

Note

rows can be take any sort of Sequence type, and even iterators (async included!)

Searching for data¶

If you need to search for data, you need one (or more!) models and a query. Let's start with a simple example:

class ContentFinderCondition(xivapy.Model):
    row_id: int
    Name: str

client = xivapy.Client()
async for result in client.search(ContentFinderCondition, query='Name~"The"'):
    print(result)

This searches for every instance of content that has 'The' in the name. You'll see several SearchResult entries, with some extra fields:

SearchResult(score=0.375, sheet='ContentFinderCondition', row_id=39, data=ContentFinderCondition(row_id=39, Name='the Aery'))
SearchResult(score=0.375, sheet='ContentFinderCondition', row_id=585, data=ContentFinderCondition(row_id=585, Name='the Burn'))
SearchResult(score=0.33333334, sheet='ContentFinderCondition', row_id=34, data=ContentFinderCondition(row_id=34, Name='the Vault'))
SearchResult(score=0.33333334, sheet='ContentFinderCondition', row_id=57, data=ContentFinderCondition(row_id=57, Name='the Navel'))

SearchResults are the wrapper around your actual requested content, but have some useful tidbits of data:

Field	Type	Description
score	`float`	How closely this matches to your query (from 0.0 to 1.0 - higher is a better match)
sheet	`str`	What sheet this came from
row_id	`int`	The row in the sheet this entry comes from
data	`xivapy.Model`	The content formatted by your model

Note

You may notice that the query parameter is a string. You can use QueryBuilder to build these query strings programmatically.

Searching multiple sheets for data¶

The above example is nice, but what if you wanted to search multiple sheets? You can do that by providing a tuple of models to search:

class ContentFinderCondition(xivapy.Model):
    row_id: int
    Name: str

class ContentUICategory(xivapy.Model):
    row_id: int
    Name: str

client = xivapy.Client()
async for result in client.search((ContentFinderCondition, ContentUICategory), query='Name~"Savage"'):
    print(result.data.Name)

Now, if you're typing this up in an IDE with good python support, you might be noticing something here: it knows about the fields in result.data - this is because the return type is AsyncIterator[SearchResult[ContentFinderCondition | ContentUICategory]]. As long as you can narrow the scope via match/instanceof/etc for custom fields, the IDE will happily autocomplete whatever you want.

Warning

You can put any number of Models that you want in the search query and it will work, but the type checking breaks down after 3 models - this is partially by design since complex queries for several sheets of data is unlikely to be useful beyond the basics of searching for a field common to all of them.

Retrieving non-json data¶

Some methods of the client return bytes - usually things related to assets, icons, and maps. They all function roughly the same:

map_jpg = await client.map('s1d1', '00')
loading_screen_png = await client.asset(path='ui/loadingimage-nowloading_base01_hr1.tex', format='png')
icon_webp = await client.icon(20650, format='webp')

You can write these to a file and get images right out of it. If you want more specifics, check out the associated functions.

Note

The only formats supported are jpg, webp, and png. If you're using an IDE, it helpfully gives those options for you anyway!

Customizing data received¶

Most of the constructor options for the client are based around customizing where and what kind of data is being received - look at the constructor for xivapy.Client. However, at a high level, you can customize the base url, api base path, and batch size (for methods like sheet and search). There are two functions that might be important for fetching specific kinds of data

game_version - a version string (you can get a list with client.versions()) that specifically requests that version of the data. If you want to pin all your data to 7.2, for instance, you can absolutely do that.
schema_version - not fully supported in the client yet, but this lets you pin the shape of the data returned by a request. See the xivapi docs for more information

Client API¶

Client¶

Async client for gathering data from xivapi rest api.

Provides methods that touch all documented endpoints in xivapi. For information on those endpoints, please read https://v2.xivapi.com/api/docs.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	Base URL for xivapi host; defaults to 'https://v2.xivapi.com'	`'https://v2.xivapi.com'`
`base_api_path`	`str`	API path prevfix; defaults to '/api'	`'/api'`
`game_version`	`str`	Default game version for requests; defaults to 'latest'	`'latest'`
`schema_version`	`Optional[str]`	Default schema version to use for requests	`None`
`batch_size`	`int`	For the sheets endpoint, it will fetch in batches of that size	`100`

Example

class Item(xivapy.Model):
    id: Annotated[int, xivapy.FieldMapping('row_id')]
client = xivapy.Client()
item = await client.sheet(Item, row=123)
print(item)
await client.close()

close `async` ¶

close() -> None

Close the interior HTTP client.

patch ¶

patch(version: str) -> None

Sets the version for all endpoints to the version provided.

versions `async` ¶

versions() -> list[str]

Retrieve a list of available game versions supported by the API.

map `async` ¶

map(
    territory: str,
    index: str,
    version: Optional[str] = None,
) -> Optional[bytes]

Retrieve a composed map from the api.

Parameters:

Name	Type	Description	Default
`territory`	`str`	A 4-character string in the format of [letter][number][letter][number]	required
`index`	`str`	A 2-digit (0-padded) numerical string	required
`version`	`Optional[str]`	A game version to fetch from	`None`

Returns:

Type	Description
`Optional[bytes]`	A bytes object that that is a jpeg formatted map, or None

sheets `async` ¶

sheets(version: Optional[str] = None) -> list[str]

Gets a list of all sheets supported by the api.

search ¶

search(
    model_spec: type[T],
    query: QueryBuilder | str,
    **params,
) -> AsyncIterator[SearchResult[T]]

search(
    model_spec: tuple[type[T1], type[T2]],
    query: QueryBuilder | str,
    **params,
) -> AsyncIterator[SearchResult[T1 | T2]]

search(
    model_spec: tuple[type[T1], type[T2], type[T3]],
    query: QueryBuilder | str,
    **params,
) -> AsyncIterator[SearchResult[T1 | T2 | T3]]

search(
    model_spec: type[Model] | tuple[type[Model], ...],
    query: QueryBuilder | str,
    **params,
) -> Any

Search XIVAPI for data using a query.

Parameters:

Name	Type	Description	Default
`model_spec`	`type[Model] \| tuple[type[Model], ...]`	Model class or tuple of model classes to search the sheets for.	required
`query`	`QueryBuilder \| str`	A QueryBuilder search or a plain string with the search terms	required
`**params`		Additional search parameters	`{}`

Returns:

Type	Description
`Any`	AsyncIterator yielding SearchResult objects with data typed against your model_spec

Example

class ContentFinderCondition(Model):
    name: Annotated[str, FieldMapping('Name')]
    content_type: Annotated[str, FieldMapping('ContentType.Name')]

async for result in client.search(ContentFinderCondition, 'ContentType.Name="Trials"'):
    print(f'{result.data.name} - {result.data.content_type}')

query = QueryBuilder().where(ItemLevelRequired=690).contains(Name='extreme')
async for result in client.search(ContentFinderCondition, query):
    # result.data is still properly typed

asset `async` ¶

asset(
    path: str,
    format: Format = 'png',
    version: Optional[str] = None,
) -> Optional[bytes]

Fetches an asset from the game, formatted into a more user-friendly format.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to fetch from	required
`format`	`Format`	The format for the resource to be formatted as ('jpg', 'png', 'webp')	`'png'`
`version`	`Optional[str]`	A game version to fetch from	`None`

Returns:

Type	Description
`Optional[bytes]`	A bytes object in the format requested, or None if not found.

icon `async` ¶

icon(
    icon_id: int,
    format: Format = 'jpg',
    version: Optional[str] = None,
) -> Optional[bytes]

Fetches an icon resource from the game by id.

Parameters:

Name	Type	Description	Default
`icon_id`	`int`	The icon id in game data.	required
`format`	`Format`	The format for the icon to be in (defaults to 'jpg')	`'jpg'`
`version`	`Optional[str]`	A game version to fetch from	`None`

Returns:

Type	Description
`Optional[bytes]`	A bytes object of the icon in the selected format, or None if not found.

sheet ¶

sheet(
    model_class: type[T], *, row: int, **params
) -> Coroutine[Any, Any, Optional[T]]

sheet(
    model_class: type[T],
    *,
    rows: Iterable[int] | AsyncIterable[int],
    **params,
) -> AsyncIterator[T]

sheet(
    model_class: type[T],
    *,
    row: Optional[int] = None,
    rows: Optional[
        Iterable[int] | AsyncIterable[int]
    ] = None,
    **params,
) -> Coroutine[Any, Any, Optional[T]] | AsyncIterator[T]

Fetch one or more rows from a sheet.

Parameters:

Name	Type	Description	Default
`model_class`	`type[T]`	An xivapy.Model class for the results to be coerced to	required
`row`	`Optional[int]`	A single row id to fetch	`None`
`rows`	`Optional[Iterable[int] \| AsyncIterable[int]]`	Multiple row ids to fetch	`None`
`**params`		Extra parameters which are passed to the sheets endpoint	`{}`

Returns:

Type	Description
`Coroutine[Any, Any, Optional[T]] \| AsyncIterator[T]`	This returns either:
`Coroutine[Any, Any, Optional[T]] \| AsyncIterator[T]`	A single row formatted by the model given
`Coroutine[Any, Any, Optional[T]] \| AsyncIterator[T]`	An AsyncIterator of the rows requested
`Coroutine[Any, Any, Optional[T]] \| AsyncIterator[T]`	None in the case of the item not being found

SearchResult¶

Returned as part of using xivapy.Client's search() method.

XIVAPI Client

Getting data from Sheets¶

Sheets - One Item¶

Sheets - Multiple Items¶

Searching for data¶

Searching multiple sheets for data¶

Retrieving non-json data¶

Customizing data received¶

Client API¶

Client¶

close async ¶

patch ¶

versions async ¶

map async ¶

sheets async ¶

search ¶

asset async ¶

icon async ¶

sheet ¶

SearchResult¶

close `async` ¶

versions `async` ¶

map `async` ¶

sheets `async` ¶

asset `async` ¶

icon `async` ¶