Galactic Tycoons Local API

The Galactic Tycoons Local API allows tools to retrieve game data in real-time using browser window messaging, without requiring public API calls.

Usage

To use the Local API, your tool must run in a browser context with access to the Galactic Tycoons game window (e.g., a browser extension or userscript). Send messages to the game window using the window.postMessage method and listen for responses using the window.addEventListener method.

Implementation Example

/**
 * Global message listener for GT Local API responses
 * The response includes the original action and params, so you can match them
 */
window.addEventListener('message', (event) => {
  if (event.data.type !== 'GT_LAPI_RESPONSE')
    return;
  const { action, params, success, data, error } = event.data;
  
  if (success) {
    const result = JSON.parse(data);
    
    /** Route based on action and params */
    switch (action) {
      case 'getPrices':
        handlePrices(result);
        break;
      case 'getMyCompany':
        handleMyCompany(result);
        break;
      case 'getSpecialists':
        handleSpecialists(result);
        break;
      case 'getBase':
        handleBase(result, params.baseId);
        break;
      case 'getWarehouse':
        handleWarehouse(result, params.warehouseId);
        break;
      case 'getWishlists':
        handleWishlists(result);
        break;
      case 'getWishlist':
        handleWishlist(result, params.wishlistId);
        break;
      case 'getBasePlans':
        handleBasePlans(result);
        break;
      case 'getBasePlan':
        handleBasePlan(result, params.planId);
        break;
    }
  } else {
    console.error(`API Error [${action}]:`, error);
  }
});

/**
 * Send a request to GT Local API
 * @param {string} action - API action to call
 * @param {object} params - Parameters for the action
 */
function requestGTLocalAPI(action, params = {}) {
  window.postMessage({
    type: 'GT_LAPI_REQUEST',
    requestId: `${action}-${Date.now()}-${Math.random()}`,
    action: action,
    params: params
  }, '*');
}

Request Examples

/** Get material prices */
requestGTLocalAPI('getPrices');

/** Get company data */
requestGTLocalAPI('getMyCompany');

/** Get your executives */
requestGTLocalAPI('getSpecialists');

/** Get specific base */
requestGTLocalAPI('getBase', { baseId: 42 });

/** Get warehouse inventory */
requestGTLocalAPI('getWarehouse', { warehouseId: 100 });

/** Get all wishlists */
requestGTLocalAPI('getWishlists');

/** Get specific wishlist */
requestGTLocalAPI('getWishlist', { wishlistId: 42 });

/** Get all base plans */
requestGTLocalAPI('getBasePlans');

/** Get specific base plan */
requestGTLocalAPI('getBasePlan', { planId: 42 });

Available Actions

Response Structure

All responses include:

interface GTLocalAPIResponse {
  type: 'GT_LAPI_RESPONSE';
  /** Original requestId echoed back for matching requests to responses (no functional purpose) */
  requestId: string;
  /** Original action echoed back */
  action: string;
  /** Original request params echoed back */
  params: object;
  success: boolean;
  /** JSON string if success */
  data?: string;
  /** Error message if failure */
  error?: string;          
}

---

getPrices

Get current and average prices for all materials.

Parameters: None

Returns: Array of material prices

interface MaterialPrice {
  matId: number;
  matName: string;
  /** Current lowest price on exchange in cents (-1 if no orders available) */
  currentPrice: number;
  /** Average price from recent trades in cents (-1 if no trade history) */
  avgPrice: number;
}

---

getMyCompany

Get your company's complete information including bases, ships, and technologies.

Parameters: None

Returns: Company data object

interface MyCompany {
  /** 
   * Company ID; 
   * -1 if the user has no company (company creation screen)
   */
  id: number;
  name: string;
  /** Company cash balance in cents */
  cash: number;
  /** Company prestige */
  pr: number;
  rank: number;
  stars: number;
  /** Total value of the company in credits */
  value: number;
  /** Date when the company was founded */
  fDate: string;
  ic: string;
  /** Guild ID, 0 if not in a guild */
  gId: number;
  /** Rank within the guild */
  gRank: number;
  /** ID of the exchange warehouse */
  exWhId: number;
  /** Number of unlocked production order slots */
  poSlots: number;
  shipSlots: number;
  online: boolean;
  bases: BasePreview[];
  ships: Ship[];
  technologies: Technology[];
  /** Allocated perks */
  perks: CompanyPerk[];
}

interface BasePreview {
  id: number;
  planetId: number;
  warehouseId: number;
  name: string;
  /** How many slot expansions have been added to this base */
  exp: number;
}

interface Ship {
  id: number;
  /** Company ID */
  cId: number;
  name: string;
  /** Planet ID where the ship is currently located OR is traveling from */
  pId: number;
  warehouseId: number;
  fuel: number;
  /** Condition of the ship (0-1) */
  condition: number;
  fuelCapacity: number;
  blueprint: ShipBlueprint;
  /** Current flight information, null if stationary */
  flight?: ShipFlight;
}

interface ShipBlueprint {
  name: string;
  reactorType: number;
  emitterType: number;
  emittersCount: number;
  cargoCapacity: number;
  tankType: number;
  heatShielding: number;
  radiationShielding: number;
  autoUnloadUnlocked: boolean;
}

interface ShipFlight {
  /** Destination Planet ID */
  destPId: number;
  /** Date when the flight started */
  sDate: string;
  /** Date when the flight ends (arrival) */
  aDate: string;
  /** Fuel at the start of the flight */
  startFuel: number;
  /** Fuel at the end of the flight */
  arrivalFuel: number;
  type: number;
  /** Auto unload on arrival */
  aUnload: boolean;
}

interface Technology {
  id: number;
  level: number;
}

interface CompanyPerk {
  /** Perk enum ID */
  id: number;
  /** Allocated perk level */
  lvl: number;
}

---

getSpecialists

Get your company's executives.

Returns your active roster (pooled, base-assigned and enrolled at university). Retired, dismissed and auction-listed executives are not included.

Parameters: None

Returns: Array of executives (empty array if you have none)

interface Specialist {
  id: number;
  name: string;
  /** Species */
  species: number;
  /** 0 = male, 1 = female */
  gender: number;
  /** Rarity */
  rarity: number;
  /** Packed portrait appearance as URL-safe base64 */
  appearance: string;
  /** Current level */
  lvl: number;
  /** Experience toward the next level (resets on level-up) */
  xp: number;
  /** Age in years (fractional) */
  age: number;
  /** Retire age in years; 0 = not yet known (revealed only once retirement is near) */
  retireAge: number;
  /** Current assignment */
  assignment: number;
  /** Base ID when assignment = Base, 0-based university slot index when assignment = University, otherwise 0 */
  holderId: number;
  /** Date the current base posting finishes acclimating and its trait effects start applying; null = fully acclimated */
  acclimatedDate: string | null;
  /** Traits - buffs and flaws alike (split by the catalogue trait kind) */
  traits: SpecialistTrait[];
}

interface SpecialistTrait {
  /** Trait ID from the trait catalogue in gamedata.json */
  id: number;
  /** Maximum points this trait accepts; a flaw instead holds its always-on effect level here (where the flaw scales, else 1) */
  maxPts: number;
  /** Points allocated into this trait; effect level = allocated points / catalogue points-per-level; always 0 on flaws */
  pts: number;
  /** Polymorphic target (e.g. worker type or material ID); 0 = use the catalogue bonus target, 0 there = whole axis */
  target: number;
}

---

getBase

Get detailed information about a specific base including buildings, production orders, workforce, and warehouse inventory.

Parameters:

• baseId (number) - The base ID

Returns: Base details or null if not found

interface BaseDetail {
  id: number;
  name: string;
  planetId: number;
  warehouseId: number;
  /** How many slot expansions have been added to this base */
  exp: number;
  /** True when the base is in vacation mode */
  vacation: boolean;
  buildingSlots: BuildingSlot[];
  productionOrders: ProductionOrder[];
  workforce?: Workforce;
  warehouse?: Warehouse;
}

interface BuildingSlot {
  id: number;
  status: number;
  building?: Building;
}

interface Building {
  id: number;
  /** Type of the building */
  type: number;
  level: number;
  /** Condition of the building (0-1) */
  cond: number;
  task?: ProductionTask;
}

interface ProductionTask {
  /** Building Id */
  bId: number;
  /** Recipe Id */
  rId: number;
  /** Date when production started */
  startDate: string;
  /** Date when production was last updated */
  updD: string;
  /** Expected completion Date */
  comD: string;
  /** Part of the task completed at last update */
  updPart: number;
  /** Amount multiplier (both input and output, level 2 building produces 2x) */
  mul: number;
}

interface ProductionOrder {
  id: number;
  /** Recipe ID */
  rId: number;
  /** How many times to produce the recipe */
  amt: number;
}

interface Workforce {
  baseId: number;
  /** Workforce needed per type */
  workersNeeded: number[];
  /** Workforce housing per type */
  workersHousing: number[];
  /** Working Workforce per type */
  workersCount: number[];
  /** Workforce satisfaction per type (0-1) */
  workersSatisfaction: number[];
  consumptionMaterials: ConsumptionMaterial[];
}

interface ConsumptionMaterial {
  /** Material ID */
  matId: number;
  /** Is currently fulfilled */
  isEating: boolean;
  /** Last updated date */
  luDate: string;
  /** Amount consumed per day */
  rate: number;
  /** Extra amount eaten last update date */
  buffer: number;
}

---

getWarehouse

Get warehouse inventory and capacity.

Parameters:

• warehouseId (number) - The warehouse ID

Returns: Warehouse data or null if not found

interface Warehouse {
  id: number;
  /** Warehouse capacity in tonnes */
  cap: number;
  /** Materials stored in this warehouse */
  mats: MaterialAmount[];
}

interface MaterialAmount {
  /** ID of the material */
  id: number;
  /** Amount */
  am: number;
}

---

getWishlists

Get all wishlists for your company.

Parameters: None

Returns: Array of wishlists

interface Wishlist {
  /** Wishlist ID (1-10,000,000 = planet ID; 50,000,001+ = custom wishlist) */
  id: number;
  /** Wishlist title, null for planet wishlists */
  title: string | null;
  /** Materials in the wishlist */
  mats: MaterialAmount[];
  /** True if this is a client-only planet wishlist (empty and does not exist on server yet) */
  isClientOnly?: boolean;
}

---

getWishlist

Get a specific wishlist by ID.

Parameters:

• wishlistId (number) - The wishlist ID

Returns: Wishlist data or null if not found

interface Wishlist {
  /** Wishlist ID (1-10,000,000 = planet ID; 50,000,001+ = custom wishlist) */
  id: number;
  /** Wishlist title, null for planet wishlists */
  title: string | null;
  /** Materials in the wishlist */
  mats: MaterialAmount[];
  /** True if this is a client-only planet wishlist (empty and does not exist on server yet) */
  isClientOnly?: boolean;
}

---

getBasePlans

Get all saved base plans for your company.

Parameters: None

Returns: Array of base plans

interface BasePlan {
  /** Plan ID - planet ID this plan is for */
  id: number;
  /** Display name of the plan (max 40 characters) - Currently not used in UI */
  title: string | null;
  /** Number of base expansions to target (0-2) */
  exp: number;
  /** Building slots that this plan affects */
  slots: BasePlanSlot[];
}

interface BasePlanSlot {
  /** Slot position ID (1-based) */
  id: number;
  /** Status of the slot */
  status: number;
  /** Building type in this slot; 0 for no building */
  buildingType: number;
  /** Target level for the building */
  level: number;
}

---

getBasePlan

Get a specific base plan by plan ID.

Parameters:

• planId (number) - The plan ID (planet ID this plan is for)

Returns: Base plan data or null if not found

interface BasePlan {
  /** Plan ID - planet ID this plan is for */
  id: number;
  /** Display name of the plan (max 40 characters) - Currently not used in UI */
  title: string | null;
  /** Number of base expansions to target (0-2) */
  exp: number;
  /** Building slots that this plan affects */
  slots: BasePlanSlot[];
}

---