FoxAPI Documentation

Join our discord : https://discord.gg/XJJkuDYZXw

Installation

pip install foxapi

FoxAPI is a wrapper for the Official Foxhole API. It provides methods to interact with various endpoints related to maps, war data, dynamic/static map states, and more. The client supports data caching and etags natively to avoid overloading the Foxhole servers.

If you are new to the developer world or just like coding, it's the perfect tool!

Also, if you work with discord.py or any asynchronous API, this tool might be useful as well since it support async methods natively as well as synchronous

Table of Contents

• FoxAPI Documentation
  • Join our discord : https://discord.gg/XJJkuDYZXw
  • Installation
  • Table of Contents
  • Dependencies
  • Wrapper
  • Methods
    • API Interaction (async)
      • Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)
    • Map and War Data
    • Hexagon Operations
    • Listener Functions
    • Queue Tasks
  • Error Handling
  • Objects
  • Example Usage
    • I am not responsible for what you are doing with it

Dependencies

pip install pillow requests aiohttp

Wrapper

classFoxAPI(shard: str="", image_dir: str=None, safe_mode: bool=True)

Methods

API Interaction (async)

Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)

get_data(endpoint: str, session: aiohttp.ClientSession|None=None, etag: str=None, use_cache: bool=False) ->APIResponse

Fetches data from the specified endpoint, you can choose to use cache instead of sending a request and you can pass ETag.

• Parameters:

  • endpoint (str): The API endpoint to call.
  • session (aiohttp.ClientSession, optional) the async session
  • etag (str, optional): The ETag header for cache validation (not required since managed natively).
  • use_cache (bool, optional): Whether to use cached data (default: False).

• Returns: The response data from the API as a APIResponse object.

Map and War Data

get_maps(use_cache: bool=True, session: aiohttp.ClientSession|None=None) ->list[str]

• Retrieves a list of available hexagons (maps) in the game world.

get_war(use_cache: bool=False, session: aiohttp.ClientSession|None=None) ->WarObject

• Retrieves the current war state (war data).

get_static(hexagon: str, use_cache: bool=False, session: aiohttp.ClientSession|None=None) ->SDObject

• Retrieves the static data for the specified hexagon.

get_dynamic(hexagon: str, use_cache: bool=False, session: aiohttp.ClientSession|None=None) ->SDObject

• Retrieves the dynamic data for the specified hexagon.

get_war_report(hexagon: str, use_cache: bool=False, session: aiohttp.ClientSession|None=None) ->WarReportObject

• Retrieves the war report for the specified hexagon.

get_hexagon_data(hexagon: str, use_cache: bool=False, session: aiohttp.ClientSession|None=None) ->HexagonObject

• Retrieves all the data awailable for the specified hexagon.

Hexagon Operations

calc_distance(x1: float, y1: float, x2: float, y2: float) ->float

• Calculates the Euclidean distance between two points on the map.

get_captured_towns(hexagon: str=None, dynamic: SDObject=None, static: SDObject=None, session: aiohttp.ClientSession|None=None) ->dict

• Retrieves the captured towns for a given hexagon based on dynamic and static data.

load_hexagon_map(hexagon: str) ->pillow.Image

• Loads the PNG map for the specified hexagon.

make_map_png(hexagon: str, icons: str|list="all", colored: bool=False, dynamic: SDObject=None, static: SDObject=None, force: bool=False, session: aiohttp.ClientSession|None=None) ->pillow.Image

• Generates a PNG image of the hexagon map with all the icons associated to each faction in their respective colors (included fields and town base). Only public data will be present.
• colored -> display each region in the team's color
• icons -> display selected building in their team's color
• force -> bypass the cache and generate a new map

calculate_death_rate(hexagon: str=None, war_report: WarReportObject=None, session: aiohttp.ClientSession|None=None): ->dict

• calculate the death rate between the first launch and the current one

Listener Functions

on_api_update(callback: callable=None, endpoints: list=None)

• Registers a callback function to be called when the data for specified API endpoints is updated.

on_hexagon_update(callback: callable=None, hexagons: list="all")

• Registers a callback function to be called when the data for specified hexagons is updated.

Queue Tasks

This library also give the possibility to queue up some sync and async methods to run them simultaneously

fromfoxapiimportFoxAPIapi=FoxAPI()
foriinrange(10):
api.add_task(function=api.get_war) # or any other methoddata=api.run_task_sync()
forelemindata:
print(elem.result)

fromfoxapiimportFoxAPIimportasyncioapi=FoxAPI()
asyncdefmain():
foriinrange(10):
api.add_task(function=api.get_war) # or any other methoddata=awaitapi.run_task()
forelemindata:
print(elem.result)
asyncio.run(main())

Error Handling

EndpointError: Raised if an invalid API endpoint is used.

HexagonError: Raised if an invalid hexagon is provided.

FoxAPIError: A general error for issues within the FoxAPI class (e.g., missing data).

Objects

classAPIResponse:
headers: dictjson: dictstatus_code: inthexagon: stris_cache: boolclassHexagonObject:
hexagon: strwar_report: WarReportObjectstatic: SDObjectdynamic: SDObjectcaptured_towns: dictcasualty_rate: dictclassWarObject:
warId: strwarNumber: intwinner: strconquestStartTime: strconquestEndTime: strresistanceStartTime: strscheduledConquestEndTime: strrequiredVictoryTowns: strshortRequiredVictoryTowns: strresponse: APIResponseclassWarReportObject:
totalEnlistments: intcolonialCasualties: intwardenCasualties: intdayOfWar: intversion: intresponse: APIResponseclassMapItemsObject:
teamId: striconType: intx: floaty: floatflags: intviewDirection: intclassMapTextItemsObject:
text: strx: floaty: floatmapMarkerType: strclassSDObject:
regionId: intscorchedVictoryTowns: intmapItems: list[MapItemsObject]
mapItemsC: list[MapItemsObject]
mapItemsW: list[MapItemsObject]
mapTextItems: list[MapTextItemsObject]
lastUpdated: intversion: intresponse: APIResponse

Example Usage

fromfoxapiimportFoxAPI# Initialize the API client in safe mode# if you are a developer and plane to use the exact hexagons name# you can turn the safe_mode off, otherwise it will convert# api calls and hexagons name into valid ones# Ex: deadlands -> DeadLandsHex (Yes, I am *that* lazy)fox=FoxAPI(shard="1")
deffunction(hexagon: str="DeadLandsHex"):
# Get the list of available hexagons (maps) and state of the current warmaps: list=fox.get_maps_sync()
war: WarObject=fox.get_war_sync()
# Retrieve data for a specific hexagondynamic_data: SDObject=fox.get_dynamic_sync(hexagon)
static_data: SDObject=fox.get_static_sync(hexagon)
war_report: WarReportObject=fox.get_war_report_sync(hexagon)
# Create a map PNG for a hexagon with building informations on itmap_image=fox.make_map_png_sync(hexagon)
map_image.show()
# to get all the data at oncedata: HexagonObject=fox.get_hexagon_data_sync(hexagon=hexagon, use_cache=True)
# Async equivalentasyncdeffunction(hexagon: str="DeadLandsHex"):
# Get the list of available hexagons (maps) and state of the current warmaps: list=awaitfox.get_maps()
war: WarObject=awaitfox.get_war()
# Retrieve data for a specific hexagondynamic_data: SDObject=awaitfox.get_dynamic(hexagon)
static_data: SDObject=awaitfox.get_static(hexagon)
war_report: WarReportObject=awaitfox.get_war_report(hexagon)
# Create a map PNG for a hexagon with building informations on itmap_image=awaitfox.make_map_png(hexagon)
map_image.show()
# to get all the data at oncedata: HexagonObject=awaitfox.get_hexagon_data(hexagon=hexagon, use_cache=True)
# Register a callback to listen for updates on all the hexagons# it will run forever don't worry@fox.on_hexagon_update("all")defon_update(hexa: HexagonObject):
print(f"Hexagon {hexa.hexagon} has been updated")
# The following async code works as well@fox.on_hexagon_update("all")asyncdefon_update(hexa: HexagonObject):
print(f"Hexagon {hexa.hexagon} has been updated")

I am not responsible for what you are doing with it