API reference

This page provides autogenerated documentation on fflogsapi’s API.

Client

class fflogsapi.FFLogsClient(client_id: str, client_secret: str, mode: str = 'client', enable_caching: bool = True, cache_directory: str = './fflogs-querycache', cache_expiry: int = 86400, cache_override: str = '', ignore_cache_expiry: bool = False, clean_cache: bool = True)

A client capable of communicating with the FF Logs V2 GraphQL API.

Caching is enabled by default, but can be overriden with the enable_caching parameter when instantiating the client. A cache of executed queries will then be maintained by the client. To save the query cache for later reuse, you must manually call save_cache() on the client. It’s also possible to extend the lifetime of all cache queries with extend_cache(), or to manually clean up old cache files with clean_cache().

Two modes of use are supported by the client - client and user mode. When in client mode, the API client can access the public API. To access private information such as private logs or hidden characters’ information, you must use user mode.

Parameters:

  • client_id – Client application ID

  • client_secret – Client application secret

  • mode – Whether to use the client or user endpoint. Client mode gives public API access, while user mode allows access to private information. User mode requires login.

  • enable_caching – If enabled, the client will cache the result of queries for up to a time specified by the cache_expiry argument.

  • cache_directory – The directory to read and save query cache files in.

  • cache_expiry – How long to keep query results in cache, in seconds. Default is 1 day.

  • cache_override – If set, force the client to load cached queries from the given file path

  • ignore_cache_expiry – If set to True, the client will load the most up-to-date cache, even if it has expired

  • clean_cache – Automatically remove expired cache files from the cache directory

Raises:

ValueError if the provided client mode is invalid. –

clean_cache() → None

Delete expired cache files.

This goes through the cache file directory, deleting all pickled files with a timestamp less than the current unix timestamp. Such cache files are guaranteed not to contain useful data anymore.

close() → None

Close the OAuth session with the FF Logs API

extend_cache(extension_time: int) → None

Extend the lifetime of all cache entries.

Parameters:

extension_time – How much time to add to the cache entries’ expiry time, in seconds.

q(query: str, ignore_cache: bool = False) → dict[str, Any]

Executes a raw GraphQL query against the FFLogs API.

Generally, you should not use this unless you need to execute a query that is not properly supported by the client. You can also use this function to query for more information in batch than the client normally would.

The result of the query is stored in cache by default, and will be returned in place of a real query result if the same query is repeated. If you need up-to-date query results, use ignore_cache to force the client to query the actual API for the information. Note that the result is still cached if the client has caching enabled, so any repeat of the same query that does not use ignore_cache will always return the last result of actually executing the query.

Parameters:

  • query – The GraphQL query to execute.

  • ignore_cache – Whether or not to ignore cached results, forcing a query to be executed against the API.

Returns:

The result of the query as a dictionary.

rate_limit_allowance() → int

Fetches the amount of points the API client is allowed to spend each hour.

Returns:

The total point allowance of the API client.

rate_limit_reset_time() → int

Fetches the amount of seconds remaining until the point allowance resets for the current API client.

Returns:

Seconds left until points reset.

rate_limit_spent() → float

Fetches the amount of points that have been spent by the API client the past hour.

Returns:

The amount of points spent.

save_cache(silent: bool = True) → None

Stores all cached queries in pickled format.

The query cache file is stored in the cache directory. The file name is the the unix timestamp of the query with the largest expiry time. This means that there is no guarantee that all results in the cache are usable, but there is at least some useful data in the cache.

Parameters:

silent – If False, print the path of the cache file.

Authorization code flow

FFLogsClient.set_auth_response(response: str) → None

Manually set the authorization response after user login.

You can use this if you want to handle the user auth flow yourself, but this must be called before the first use of the client.

When using this, you must also handle token refresh logic yourself.

FFLogsClient.user_auth() → None

Prompt the user to login through their browser and fetch an authorization token.

Report API

FFLogsClient.reports(filters: dict = {}) → FFLogsReportPaginationIterator

Iterate over pages of FF Logs reports.

For valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/warcraft/reportdata.doc.html

Parameters:

filters – Filters to use when finding reports.

Returns:

An iterator over the pages of reports that match the given filters.

FFLogsClient.get_report(code: str) → FFLogsReport

Retrieves the given report data from FF Logs.

Parameters:

code – The report code.

Returns:

A FFLogsReport object representing the report.

Character API

FFLogsClient.get_character(filters: dict = {}, id: int | None = -1) → FFLogsCharacter

Retrieves character data from FFLogs. Note that it is possible to use only the filters argument, the id parameter is there for ease of use.

For valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/ff/characterdata.doc.html

Parameters:

  • filters – Optional filters to find the character by.

  • id – The ID of the character to retrieve.

Returns:

A FFLogsCharacter representing the requested character.

User API

FFLogsClient.get_current_user() → FFLogsUser | None

Get the current user. This requires the client to be in user mode!

Raises:

PermissionError if the client is not in user mode –

FFLogsClient.get_user(id: int) → FFLogsUser

Get the user with the given ID.

Parameters:

id – The ID of the user to retrieve.

Guild API

FFLogsClient.guilds(filters: dict = {}) → FFLogsGuildPaginationIterator

Iterate over pages of guilds on FF Logs.

For valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/ff/guilddata.doc.html

Parameters:

filters – Filters to find guilds by.

Returns:

An iterator over the pages of guilds that match the given filters.

FFLogsClient.get_guild(filters: dict = {}, id: int = -1) → FFLogsGuild

Retrieves the given guild data from FFLogs.

For valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/ff/guilddata.doc.html

Parameters:

  • filters – Filters to find the guild by.

  • id – The guild ID.

Returns:

A FFLogsGuild object representing the guild.

Game API

FFLogsClient.icon_url(icon: str) → str

Get the full URL to a game object.

Parameters:

icons – The filename of the icon as given by the FF Logs API.

Returns:

The full URL to the icon.

FFLogsClient.abilities() → FFLogsAbilityPaginationIterator

Get a pagination of all game abilities.

Returns:

An iterator over all pages of game abilities.

FFLogsClient.ability(id: int) → FFAbility

Get ability data for the given ability id.

Parameters:

id – The ID of the game ability.

Returns:

The game ability.

FFLogsClient.items() → FFLogsItemPaginationIterator

Get a pagination of all game items.

Returns:

An iterator over all pages of game items.

FFLogsClient.item(id: int) → FFItem

Get item data for the given item id.

Parameters:

id – The ID of the game item.

Returns:

The game item.

FFLogsClient.maps() → FFLogsMapPaginationIterator

Get a pagination of all game maps.

Returns:

An iterator over all pages of game maps.

FFLogsClient.map(id: int) → FFMap

Get map data for the given map id.

Parameters:

id – The ID of the game map.

Returns:

The game map.

FFLogsClient.jobs() → list[FFJob]

Get a list of all game jobs supported by FF Logs.

Returns:

A list of all jobs.

FFLogsClient.grand_companies() → list[FFGrandCompany]

Get all grand companies (called factions by FF Logs) that guilds and characters can belong to.

Returns:

A list of all grand companies.

World API

FFLogsClient.get_encounter(id: int) → FFLogsEncounter

Retrieves the given encounter data from FF Logs.

Parameters:

id – The encounter ID.

Returns:

A FFLogsEncounter object representing the encounter.

FFLogsClient.get_expansion(id: int) → FFLogsExpansion

Retrieves the given expansion data from FF Logs.

Parameters:

id – The expansion ID.

Returns:

A FFLogsExpansion object representing the expansion.

FFLogsClient.all_expansions() → list[FFLogsExpansion]

Retrieves a list of all expansions supported by FF Logs.

Returns:

A list of FFLogsExpansions representing each expansion.

FFLogsClient.get_region(id: int) → FFLogsRegion

Retrieves the given region from FF Logs.

Parameters:

id – The region ID.

Returns:

A FFLogsRegion object representing the region.

FFLogsClient.all_regions() → list[FFLogsRegion]

Retrieves a list of all regions supported by FF Logs.

Returns:

A list of FFLogsRegions representing each region.

FFLogsClient.get_server(filters: dict = {}, id: int | None = -1) → FFLogsServer

Retrieves server information from FF Logs given server filters.

For valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/warcraft/worlddata.doc.html

Parameters:

  • filters – Optional filters to find the server by.

  • id – The ID of the server to retrieve.

Returns:

A FFLogsServer object representing the server.

FFLogsClient.get_subregion(id: int) → FFLogsSubregion

Retrieves the given subregion from FF Logs.

Parameters:

id – The subregion ID.

Returns:

A FFLogsSubregion object representing the subregion.

FFLogsClient.get_zone(id: int) → FFLogsZone

Retrieves the given zone from FF Logs.

Parameters:

id – The zone ID.

Returns:

A FFLogsZone object representing the zone.

FFLogsClient.all_zones(expansion_id: int) → list[FFLogsZone]

Retrieves a list of all zones belonging to a given expansion that are supported by FF Logs.

Returns:

A list of FFLogsZones representing each zone.

Prog race API

FFLogsClient.get_progress_race(filters: dict = {}) → dict[str, Any]

Retrieve progress race information from the FF Logs API. This includes information such as best fight percentages, pull counts and stream information for different guilds.

For valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/ff/progressracedata.doc.html

Parameters:

filters – Filters to use when finding progress races data.

Returns:

Progress race data made available by the FF Logs API.

Report API

Reports

class fflogsapi.reports.FFLogsReport(code: str, client: FFLogsClient = None)

Representation of a report on FF Logs.

abilities() → list[FFLogsReportAbility]
Returns:

A list of all abilities in the report

actor(id: int) → FFLogsActor | None

Get a specific actor by their report ID.

Parameters:

id – The report ID of the actor.

Returns:

An actor or None if there is no actor with the given ID.

actors() → list[FFLogsActor]
Returns:

A list of all actors in the report

archivation_data() → FFLogsArchivalData

Get the archivation status for this report, including archival date, if any.

Returns:

The report’s archivation data.

code: str = ''

The code for this report

duration() → float
Returns:

The total duration of the report

end_time() → float
Returns:

The end timestamp of the report.

exported_segments() → int
Returns:

The amount of segments in this report that were exported.

fight(id: int = -1) → FFLogsFight

Get a specific fight from this report.

Parameters:

id – The ID of the fight to retrieve. Default: last fight

Returns:

An FFLogsFight object or None if the fight is not in the report

fight_count() → int
Returns:

The total amount of fights in the report

fights() → list[FFLogsFight]
Returns:

A list of all fights in this report.

guild() → FFLogsGuild | None
Returns:

The guild this report belongs to, if any.

log_version() → int
Returns:

The version of the parser client used to parse and upload the log file.

owner() → FFLogsUser
Returns:

The user that owns this report.

ranked_characters() → list[FFLogsCharacter]

Get all the characters that ranked on kills in this report.

Returns:

A list of all ranked characters.

region() → FFLogsRegion
Returns:

The region of the report.

revision() → int

Get the report’s revision number, which is increased every time the report is re-exported.

Returns:

The report’s revision number.

segments() → int
Returns:

The amount of segments uploaded to this report.

start_time() → float
Returns:

The start timestamp of the report.

tag() → FFLogsReportTag | None

The tag applied to this report used by the guild to which this report belongs. If a tag was not applied, returns None.

Returns:

The report tag, if any.

title() → str
Returns:

The title of this report.

visibility() → str

Get the visibility level of the report. Can be public, private or unlisted.

Returns:

The visibility of the report.

zone() → FFLogsZone
Returns:

The principal zone for fights in this report.

Fights

class fflogsapi.reports.FFLogsFight(report: FFLogsReport, fight_id: int, client: FFLogsClient)

Representation of a single fight on FF Logs.

bounding_box() → tuple[int, int, int, int]

Get the bounding box that encloses all player’s positions throughout the fight.

Returns:

The bounding box of player positions as a tuple of the form (minX, minY, maxX, maxY).

complete_raid() → bool

Whether or not this fight represents a full raid start to finish, i.e. a ‘complete raid’.

Returns:

Whether or not this is a complete raid.

difficulty() → int | None

Usually not very descriptive, as difficulty level 100 covers a wide variety of content.

Returns:

The difficulty of the fight.

duration() → float
Returns:

The total duration of the right

encounter() → FFLogsEncounter
Returns:

The encounter the fight was a part of.

end_time() → float
Returns:

End time of the fight relative to the start time of the report

enemy_npcs() → list[FFLogsNPCData]

Get a list of all enemy NPCs that appear in this fight.

Returns:

A list of enemy NPCs in the fight or None if there are none.

events(filters: dict[str, Any] = {}) → list[dict[str, Any]]

Retrieves the events of the fight.

If start/end time is not specified in filters, the default is the start/end of the fight.

This data isn’t considered frozen by FF Logs and may therefore change without notice.

For a full list of valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/warcraft/report.doc.html

Parameters:

filters – Filters to use when retrieving event log data.

Returns:

A filtered list of all events in the fight or None if the fight has zero duration

fight_percentage() → float
Returns:

The minimum percentage of the entire fight that was reached

friendly_npcs() → list[FFLogsNPCData] | None

Get a list of all friendly NPCs that appear in this fight.

Returns:

A list of all friendly NPCs in the fight or None if there are none.

friendly_players() → list[int]
Returns:

The IDs of all friendly players in the fight

game_zone() → FFGameZone

The in-game zone in which this fight took place.

Returns:

The game zone this fight takes place in.

graph(filters: dict[str, Any] = {}) → dict[Any, Any]

Retrieves the graph information for the fight, i.e. damage done, healing done, etc. for various points in the fight. Shorter time intervals give higher point resolution.

If start/end time is not specified in filters, the default is the start/end of the fight.

This data isn’t considered frozen by FF Logs and may therefore change without notice.

For a full list of valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/warcraft/report.doc.html

Parameters:

filters – Filters to use when retrieving graph data.

Returns:

A dictionary of graph information for the fight or None if the fight has zero duration

has_echo() → bool
Returns:

Whether or not Echo was enabled for this fight

id: int = -1

The ID of the fight, within the report which this fight belongs to

in_progress() → bool

If the report is being live logged, the fight may be marked as in progress. When the entire fight has been uploaded, the fight will be marked as no longer in progress.

Returns:

Whether or not the fight is still in progress.

is_kill() → bool
Returns:

Whether or not the fight resulted in a kill

last_phase(ignore_intermissions: bool = True, as_dataclass: bool = False) → int | FFLogsPhase

Get the phase the fight was in when the fight ended.

Parameters:

  • ignore_intermissions – When True, the last non-intermission phase is returned

  • as_dataclass – Return the last phase as a FFLogsPhase dataclass. This will become standard in the future.

Returns:

The last phase the fight was in when it ended

last_phase_absolute() → int
Returns:

The last phase the fight was in when it ended, counting from 0 and including intermissions

last_phase_intermission() → bool
Returns:

Whether or not the last phase of the fight is an intermission

maps() → list[FFMap]

Get a list of all the maps involved in this fight.

Returns:

All maps involved in the fight.

name() → str
Returns:

The name of the fight

percentage() → float
Returns:

The minimum percentage of HP that was reached for the last boss in the fight

pets() → list[FFLogsNPCData]

Get a list of all friendly pet NPCs that appear in this fight.

Returns:

All friendly pets in the fight.

phases() → list[FFLogsPhase]

Get a list of phases in this fight.

Returns:

A list of phases

player_details() → list[FFLogsPlayerDetails]

Get a list of player details such as each player’s job, name and server for this fight.

This data isn’t considered frozen by FF Logs and may therefore change without notice.

Returns:

The player details for this fight.

rankings(metric: str = 'default', compare: str = 'Rankings', timeframe: str = 'Today') → FFLogsReportRanking | None

Retrieves ranking data for the fight.

This data isn’t considered frozen by FF Logs and may therefore change without notice.

Parameters:

  • metric – The type of metric to retrieve rankings for. The following are supported: default, bossdps, bossrdps, dps, hps, rdps, tankhps

  • compare – What to compare against. Rankings and Parses are supported. Parses will compare against all parses in a two week window.

  • timeframe – The time frame to compare against. Today and Historical are supported.

Returns:

A dictionary of player ranking information or None if there is no ranking information for this fight.

report: FFLogsReport = None

The report which this fight belongs to

size() → int
Returns:

The amount of players participating in the fight

standard_comp() → bool
Returns:

Whether or not this fight had a standard composition. A standard composition is two tanks, two healers and four DPS.

start_time() → float
Returns:

Start time of the fight relative to the start time of the report

table(filters: dict[str, str] = {}) → dict[Any, Any]

Retrieves the table information for the fight.

If start/end time is not specified in filters, the default is the start/end of the fight.

This data isn’t considered frozen by FF Logs and may therefore change without notice.

For a full list of valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/warcraft/report.doc.html

Parameters:

filters – Filters to use when retrieving table data.

Returns:

A dictionary of table information for the fight or None if the fight has zero duration

Character API

class fflogsapi.characters.FFLogsCharacter(filters: dict = {}, id: int = -1, client: FFLogsClient = None)

Representation of a character on FFLogs.

encounter_rankings(filters: dict[str, Any] = {}) → dict | FFLogsEncounterRankings

Get this character’s rankings for a specific encounter. encounterID is mandatory.

For valid filter fields, see the API documentation: https://www.fflogs.com/v2-api-docs/ff/character.doc.html

Parameters:

filters – Key-value filters to filter the rankings by. E.g. job name, encounter ID, etc.

Returns:

The character’s filtered ranking data.

fc_rank() → str

Get the FC rank of the character. This is game data, not FFLogs data.

Returns:

The character’s FC rank.

game_data(filters: dict = {}) → dict

Get cached game data tied to the character, such as gear.

Parameters:

filters – Filter game data to a specific specID or force an update by the API with forceUpdate.

Returns:

The character’s game data.

guilds() → list[FFLogsGuild]

Get a list of all guilds that this character belongs to.

Returns:

A list of guilds the character is in.

hidden() → bool

Whether or not the character’s rankings are hidden.

Returns:

True if the rankings are hidden, False otherwise.

id: int = -1

The ID of the character

lodestone_id() → int

Get the character’s Lodestone ID.

Returns:

The character’s Lodestone ID.

name() → str

Get the character’s name.

Returns:

The character’s name.

server() → FFLogsServer

Get the server the character belongs to.

Returns:

The character’s server.

zone_rankings(filters: dict[str, Any] = {}) → dict | FFLogsZoneRanking

Get this character’s rankings for a zone (boss).

For valid filter fields, see the API documentation: https://www.fflogs.com/v2-api-docs/ff/character.doc.html

Parameters:

filters – Key-value filters to filter the rankings by. E.g. job name, zone ID, etc.

Returns:

The character’s filtered ranking data.

User API

class fflogsapi.user.FFLogsUser(id: int, client: FFLogsClient = None)

FF Logs user information object.

characters() → list[FFLogsCharacter]

Query for a list of all characters claimed by the user.

This is only available when the client is in user mode. If the client is in client mode, the API will return an error stating that you do not have permission to view the user’s claimed characters.

Returns:

A list of characters claimed by the user.

guilds() → list[FFLogsGuild]

Get a list of all the guilds the user belongs to.

This is only available when the client is in user mode. If the client is in client mode, the API will return an error stating that you do not have permission to view the user’s claimed characters.

Returns:

A list of guilds the user belongs to.

id: int = -1

The ID of the user

name() → str

Get the name of the user.

Returns:

The name of the user.

Guild API

class fflogsapi.guilds.FFLogsGuild(filters: dict = {}, id: int = -1, client: FFLogsClient = None)

FFLogs guild information object.

attendance(filters: dict = {}) → FFLogsGuildAttendancePaginationIterator

Get a pagination of attandance reports.

For valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/ff/guild.doc.html

Parameters:

filters – Zone and tag ID filters to filter attendance reports by.

Returns:

An iterator over all attendance report pages.

characters() → FFLogsCharacterPaginationIterator

Get a pagination of all characters belonging to the guild.

Returns:

An iterator over all guild character pages.

competition_mode() → bool

Get whether or not the guild has competition mode enabled.

Returns:

The competition mode of the guild.

current_rank() → str

Requires the API client to be in user mode.

Gets the current user’s rank in the guild. This is not ranking data. The rank can be NonMember, Applicant, Recruit, Member, Officer or GuildMaster.

Returns:

The user’s rank in the guild.

description() → str

Get the description of the guild.

Returns:

The description of the guild.

grand_company() → FFGrandCompany

Get the grand company to which this guild belongs.

Returns:

The grand company the guild belongs to.

id: int = -1

The ID of the guild

name() → str

Get the name of the guild.

Returns:

The name of the guild.

server() → FFLogsServer

Get the server to which this guild belongs.

Returns:

The server the guild belogns to

stealth_mode() → bool

Get whether or not the guild has stealth mode enabled.

Returns:

The stealth mode of the guild.

tags() → list[FFLogsReportTag]

Get a list of all the tags this guild uses to label its reports.

Returns:

The guild’s tags.

type() → str

Get the type of the guild. A type of 0 indicates the guild is a Free Company, while a type of 1 indicates the guild is a Static.

Returns:

The type of the guild.

zone_rankings(zone: int | FFLogsZone, size: int = 8, difficulty: int = 101) → FFLogsGuildZoneRankings

Retrieve the guild’s ranking information for a given zone, party size and difficulty.

Parameters:

  • zone – Either the int ID of the zone, or the zone to retrieve ranking information for.

  • size – The party size for which to retrieve rankings.

  • difficulty – The difficulty level for which to retrieve rankings.

World API

class fflogsapi.world.FFLogsExpansion(id: int, client: FFLogsClient = None)

Representation of an expansion on FF Logs.

id: int = -1

The ID of the expansion

name() → str

Get the expansion’s name.

Returns:

The expansion’s name.

zones() → list[FFLogsZone]

Get a list of all zones within this expansion.

Returns:

A list of the expansion’s zones.

class fflogsapi.world.FFLogsEncounter(id: int, client: FFLogsClient = None)

Representation of an encounter on FF Logs.

character_rankings(filters: dict[str, Any] = {}) → dict

Get character/player ranking information for the encounter. Character ranking pagination for encounters must be handled by hand.

For a full list of valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/warcraft/encounter.doc.html

Parameters:

filters – Filters to use when retrieving character rankings for the encounter.

Returns:

The encounter’s filtered character ranking data.

fight_rankings(filters: dict[str, Any] = {}) → dict

Get fight rankings for the encounter. Fight ranking pagination for encounters must be handled by hand.

For a full list of valid filters see the API documentation: https://www.fflogs.com/v2-api-docs/warcraft/encounter.doc.html

Parameters:

filters – Filters to use when retrieving fight rankings for the encounter.

Returns:

The encounter’s filtered fight ranking data.

id: int = -1

The ID of the encounter

name() → str

Get the encounter’s name.

Returns:

The encounter’s name.

zone() → FFLogsZone

Get the zone the encounter is found in.

Returns:

The encounter’s zone.

class fflogsapi.world.FFLogsZone(id: int, client: FFLogsClient = None)

Representation of a zone on FF Logs.

brackets() → dict

Get bracket information about the zone.

Returns:

The zone’s bracket information.

difficulties() → dict

Get difficulty information about the zone.

Returns:

The zone’s difficulty information.

encounters() → list[FFLogsEncounter]

Get a list of all encounters within this zone.

Returns:

A list of the zone’s encounters.

expansion() → FFLogsExpansion

Get the expansion to which this zone belongs.

Returns:

The expansion that this zone belongs to.

frozen() → bool

Get whether or not data about the zone has been permanently frozen.

Returns:

Whether or not the zone is frozen.

id: int = -1

The ID of the zone

name() → str

Get the zone’s name.

Returns:

The zone’s name.

partitions() → dict | list[FFLogsPartition]

Get partition information about the zone.

Returns:

The zone’s partition information.

class fflogsapi.world.FFLogsRegion(id: int, client: FFLogsClient = None)

Representation of a region on FF Logs. These correspond to geographical server regions.

compact_name() → str

Get the region’s compact name. E.g. ‘EU’ for Europe, ‘NA’ for North America, etc.

Returns:

The region’s compact name.

id: int = -1

The ID of the region

name() → str

Get the region’s name. E.g. Europe, North America, etc.

Returns:

The region’s name.

servers() → FFLogsRegionServerPaginationIterator

Get a pagination of all servers in the region.

Returns:

A pagination iterator of the region’s servers.

slug() → str

Get the region’s slug. This is usually the exact same as the region’s compact name

Returns:

The region’s slug.

subregions() → list[FFLogsSubregion]

Get a list of subregions belonging to this region

Returns:

A list of subregions.

class fflogsapi.world.FFLogsSubregion(id: int, client: FFLogsClient = None)

Representation of a subregion on FF Logs. These correspond to data centers.

id: int = -1

The ID of the subregion

name() → str

Get the subregion’s name. E.g. Light, Crystal, Mana, etc.

Returns:

The subregion’s name.

region() → FFLogsRegion

Get the subregion’s parent region. This is the geographical region in which the data center resides.

Returns:

The subregion’s parent region.

servers() → FFLogsSubregionServerPaginationIterator

Get a list of all servers within this subregion/data center.

Returns:

A list of the subregion’s servers.

class fflogsapi.world.FFLogsServer(filters: dict = {}, id: int = -1, client: FFLogsClient = None)

Representation of a server on FFLogs.

characters() → FFLogsServerCharacterPaginationIterator

Get a pagination of all characters found on the server.

Returns:

A pagination iterator over all pages of characters belonging to the server.

id: int = -1

The ID of the server

name() → str

Get the server’s name. E.g. Lich, Tonberry, Siren, etc.

Returns:

The server’s name.

normalized_name() → str

Get the server’s normalized name. This is the server name without spaces.

Returns:

The server’s normalized name.

region() → FFLogsRegion

Get the server’s region. This is the geographical region in which the server resides.

Returns:

The server’s region.

slug() → str

Get the server’s slug. This is usually the exact same as the server’s compact name

Returns:

The server’s slug.

subregion() → FFLogsSubregion

Get the server’s subregion, AKA data center.

Returns:

The server’s subregion.

Dataclasses

class fflogsapi.data.FFLogsAllStarsRanking(partition: int, job: FFJob, points: float, possible_points: int, rank: int, region_rank: int, server_rank: int, rank_percent: float, total: int)

All stars ranking information

job: FFJob
partition: int
points: float
possible_points: int
rank: int
rank_percent: float
region_rank: int
server_rank: int
total: int
class fflogsapi.data.FFLogsFightRank(locked_in: bool, bracket_data: str, rank_percent: float, rank_total_parses: int, today_percent: float, today_total_parses: int, historical_percent: float, historical_total_parses: int, guild: FFLogsGuild | None, fight: FFLogsFight, job: FFJob, best_job: FFJob, adps: float | None, rdps: float | None, ndps: float | None, pdps: float | None)

Rank information from one fight

adps: float | None
best_job: FFJob
bracket_data: str
fight: FFLogsFight
guild: FFLogsGuild | None
historical_percent: float
historical_total_parses: int
job: FFJob
locked_in: bool
ndps: float | None
pdps: float | None
rank_percent: float
rank_total_parses: int
rdps: float | None
today_percent: float
today_total_parses: int
class fflogsapi.data.FFLogsEncounterRankings(zone: FFLogsZone, metric: str, best_amount: float, average_performance: float, median_performance: float, kills: int, fastest_kill: int, difficulty: int, ranks: list[FFLogsFightRank])

Ranking information for a character on a specific encounter (boss)

average_performance: float
best_amount: float
difficulty: int
fastest_kill: int
kills: int
median_performance: float
metric: str
ranks: list[FFLogsFightRank]
zone: FFLogsZone
class fflogsapi.data.FFLogsZoneEncounterRanking(locked_in: bool, encounter: FFLogsEncounter, rank_percent: float, median_percent: float, best_amount: float, kills: int, fastest_kill: int, all_stars: FFLogsAllStarsRanking, job: FFJob, best_job: FFJob)

Zone ranking information for a character for a specific encounter

all_stars: FFLogsAllStarsRanking
best_amount: float
best_job: FFJob
encounter: FFLogsEncounter
fastest_kill: int
job: FFJob
kills: int
locked_in: bool
median_percent: float
rank_percent: float
class fflogsapi.data.FFLogsZoneRanking(zone: FFLogsZone, metric: str, encounter_ranks: list[FFLogsZoneEncounterRanking], difficulty: int, best_performance_avg: float, median_performance_avg: float, all_stars: list[FFLogsAllStarsRanking])

Ranking information for a character in a specific zone

Note that all_stars is a list of all stars rankings for different partitions

all_stars: list[FFLogsAllStarsRanking]
best_performance_avg: float
difficulty: int
encounter_ranks: list[FFLogsZoneEncounterRanking]
median_performance_avg: float
metric: str
zone: FFLogsZone
class fflogsapi.data.FFLogsReportCharacterRanking(character: FFLogsCharacter, job: FFJob, amount: float, rank: str, best_rank: str, total_parses: int, percentile: int)

Ranking information for a single character as provided by a report.

amount is ambiguous and depends on the metric asked for. You’ll just have to keep track yourself.

rank and best_rank are strings because the ranking may be approximate. If the rank begins with a ‘~’, that means the rank is approximate.

amount: float
best_rank: str
character: FFLogsCharacter
job: FFJob
percentile: int
rank: str
total_parses: int
class fflogsapi.data.FFLogsReportComboRanking(type: str, character_a: FFLogsCharacter, character_b: FFLogsCharacter, job_a: FFJob, job_b: FFJob, amount: float, rank: str, best_rank: str, total_parses: int, percentile: int)

Ranking information for a combination of two tanks/healers.

type is either ‘tanks’ or ‘healers’ to indicate what kind of combination ranking this is.

amount: float
best_rank: str
character_a: FFLogsCharacter
character_b: FFLogsCharacter
job_a: FFJob
job_b: FFJob
percentile: int
rank: str
total_parses: int
type: str
class fflogsapi.data.FFLogsReportRanking(patch: float, bracket: int, deaths: int, damage_taken_not_tanks: int, character_rankings: list[FFLogsReportCharacterRanking], combo_rankings: list[FFLogsReportComboRanking])

Ranking information provided by a report.

Combo rankings are tank/healer combination rankings, i.e. the rank of both tanks/healers combined.

bracket: int
character_rankings: list[FFLogsReportCharacterRanking]
combo_rankings: list[FFLogsReportComboRanking]
damage_taken_not_tanks: int
deaths: int
patch: float
class fflogsapi.data.FFAbility(id: int, name: str, description: str, icon: str, type: int | None = None)

A FFXIV ability.

The type field is only set if the ability is retrieved from a report as they are the only data objects through which the API will return that information.

description: str
icon: str
id: int
name: str
type: int | None = None
class fflogsapi.data.FFItem(id: int, name: str, icon: str)

A FFXIV item.

icon: str
id: int
name: str
class fflogsapi.data.FFJob(id: int, name: str, slug: str)

A FFXIV job, called spec by the FF Logs API.

id: int
name: str
slug: str
class fflogsapi.data.FFGrandCompany(id: int, name: str)

A grand company.

id: int
name: str
class fflogsapi.data.FFMap(id: int, name: str, filename: str, offset_x: int, offset_y: int, size_factor: int)

A FFXIV map.

The filename refers to the file name of the image for the map. If None, there is no such image available.

filename: str
id: int
name: str
offset_x: int
offset_y: int
size_factor: int
class fflogsapi.data.FFLogsReportTag(id: int, name: str, guild: FFLogsGuild)

A tag used by a specific guild to categorize the guild’s reports.

guild: FFLogsGuild
id: int
name: str
class fflogsapi.data.FFLogsAttendanceReport(report: FFLogsReport, players: tuple[tuple[str, int, str]], start: float, zone: FFLogsZone)

An attendance report belonging to a guild. The attendance report consists of a report and an accompanying list of attendance statuses for players.

The players list contains tuples of the form (name, presence, job) where the presence value indicates what capacity the player presented in. A presence value of 1 indicates the player was present, while a presence value of 2 indicates the player was present on bench.

players: tuple[tuple[str, int, str]]
report: FFLogsReport
start: float
zone: FFLogsZone
class fflogsapi.data.FFLogsRank(number: int, percentile: int | None, color: str)

Ranking information for the world, relevant region and server.

The number is the ordinal rank for the ranking metric, i.e. “Rank #N”. The percentile is the 0-100 percentile score of the rank. This is unused by guild rankings. The color string is the color class used internally by FF Logs.

color: str
number: int
percentile: int | None
class fflogsapi.data.FFLogsGuildZoneRankings(completion_speed: tuple[FFLogsRank] | None, progress: tuple[FFLogsRank] | None, speed: tuple[FFLogsRank] | None)

Ranking information for a specific guild, for a specific zone.

For each ranking metric, there is a subdivision into world, region and server rank.

completion_speed refers to the complete raid speed ranks for the guild. progress ranks the guild’s progression through the zone. speed is the all-star based speed ranking for the guild in the zone.

completion_speed: tuple[FFLogsRank] | None
progress: tuple[FFLogsRank] | None
speed: tuple[FFLogsRank] | None
class fflogsapi.data.FFLogsActor(report: FFLogsReport, id: int, name: str, type: str, sub_type: str, server: str, game_id: int, job: FFJob | None, pet_owner: FFLogsActor)

Represents an actor in a report.

game_id: int
id: int
job: FFJob | None
name: str
pet_owner: FFLogsActor
report: FFLogsReport
server: str
sub_type: str
type: str
class fflogsapi.data.FFLogsReportAbility(game_id: int, name: str, type: int)

A game ability as represented in a report.

These are slightly different than game abilities as they contain an additional type field indicating damage type.

You can get more information about the ability for querying for the ability with game_id.

game_id: int
name: str
type: int
class fflogsapi.data.FFLogsArchivalData(archived: bool, accessible: bool, date: int | None)

Archivation data for a report.

accessible denotes if the current user can access the report. date is the archival date, if the report is archived.

accessible: bool
archived: bool
date: int | None
class fflogsapi.data.FFLogsPlayerDetails(id: int, actor: FFLogsActor, guid: int, name: str, server: str, job: FFJob, role: str)

Player details as provided by FF Logs for individual fights in a report.

Note that most of the data here is only partially complete. For example, server name is given but server region is not. Spec information empty/useless as FFXIV does not have them, and there is no gear information.

actor: FFLogsActor
guid: int
id: int
job: FFJob
name: str
role: str
server: str
class fflogsapi.data.FFLogsNPCData(id: int, actor: FFLogsActor, hostile: bool, game_id: int, group_count: int, instance_count: int, pet_owner: FFLogsActor)

NPC data as provided by a fight in a report.

group_count is how many packs of the NPC were seen during the fight.

id is the report ID of the NPC, and can be used to filter by source and target in the report.

instanceCount is how many instances of the NPC were seen in the fight.

If this NPC is a pet, pet_owner is the report ID of the pet owner.

actor: FFLogsActor
game_id: int
group_count: int
hostile: bool
id: int
instance_count: int
pet_owner: FFLogsActor
class fflogsapi.data.FFGameZone(id: int, name: str)

A named in-game zone.

id: int
name: str
class fflogsapi.data.FFLogsPartition(id: int, name: str, compact_name: str, default: bool)

A partition within a zone.

compact_name: str
default: bool
id: int
name: str
class fflogsapi.data.FFLogsPhase(id: int, name: str, intermission: bool, separates_wipes: bool)

Phase information for an encounter

The encounter is not part of this dataclass because it can be queried from the fight from which this information was gotten

id: int
intermission: bool
name: str
separates_wipes: bool

Does this visually distinguish wipes in the FF Logs report UI?

Pagination

Many methods return Page and PaginationIterator objects. In such cases, the pagination iterators allow you to iterate over multiple Page s, while each Page allows you to iterate over the relevant objects in the page. For example, a FFLogsReportPaginationIterator lets you iterate over multiple FFLogsReportPage s, which in turn allow you to iterate over FFLogsReport s.

Page API

class fflogsapi.data.page.FFLogsPage(page_num: int, filters: dict[str, str] = {}, client: FFLogsClient = None, additional_formatting: dict[str, str] = {})

Representation of a page of data on FFLogs. Base class for specific page types, do not use.

count() → int
Returns:

The amount of objects in this page.

object(idx: int) → Any | None

Get a specific object from this page.

Parameters:

idx – The page index of the object to retrieve from the page

Returns:

An object or None if the object is not contained in the page

class fflogsapi.data.page.FFLogsPaginationIterator(client: FFLogsClient, filters: dict[str, Any] = {}, additional_formatting: dict[str, str] = {})

Iterates over multiple pages (a pagination), returning pages