Laplace TypeScript/JavaScript SDK

The official TypeScript/JavaScript SDK for the Laplace stock data platform. Get easy access to stock data, collections, financials, funds, and AI-powered insights.

Features

• 🚀 Easy to use: Simple, intuitive API with TypeScript/JavaScript idioms
• 📊 Comprehensive data: Stocks, collections, financials, funds, and AI insights
• 🔧 Well-typed: Full TypeScript type safety with comprehensive interfaces
• 🧪 Well-tested: Comprehensive test coverage with real API integration
• 🌍 Multi-region: Support for US and Turkish markets
• ⚡ Fast: High-performance HTTP requests
• 📚 Well-documented: Complete documentation for all public methods
• 🔄 Real-time: Live price streaming with Server-Sent Events

Installation

npm install laplace-api-js

Quick Start

import { createClient } from "laplace-api-js";
import { LaplaceConfiguration } from "laplace-api-js";
import { Logger } from "winston";

// Initialize the client
const config: LaplaceConfiguration = {
  apiKey: "your-api-key-here",
  baseURL: "https://api.laplace.finfree.co",
};

const logger: Logger = {
  info: console.log,
  error: console.error,
  warn: console.warn,
  debug: console.log,
} as Logger;

const client = createClient(config, logger);

// Get stock details
async function getStockDetails() {
  try {
    const stock = await client.getStockDetailBySymbol(
      "AAPL",
      "equity",
      "us",
      "en"
    );
    console.log(`${stock.name}: ${stock.description}`);
  } catch (error) {
    console.error("Error fetching stock:", error);
  }
}

// Get all stocks in a region
async function getAllStocks() {
  try {
    const stocks = await client.getAllStocks("us", 1, 10);
    stocks.forEach((stock) => {
      console.log(`${stock.symbol}: ${stock.name}`);
    });
  } catch (error) {
    console.error("Error fetching stocks:", error);
  }
}

// Get collections
async function getCollections() {
  try {
    const collections = await client.getAllCollections("tr", "en");
    collections.forEach((collection) => {
      console.log(`${collection.title}: ${collection.numStocks} stocks`);
    });
  } catch (error) {
    console.error("Error fetching collections:", error);
  }
}

// Get live price data
async function getLivePrices() {
  try {
    const liveClient = client.getLivePriceForBIST(["THYAO", "GARAN"]);

    for await (const data of liveClient.receive()) {
      console.log("Live price:", data);
      break; // Get first data and exit
    }

    liveClient.close();
  } catch (error) {
    console.error("Error getting live prices:", error);
  }
}

API Reference

Stocks Client

// Get all stocks with pagination
const stocks = await client.getAllStocks("us", 1, 10);

// Get stock detail by symbol
const stock = await client.getStockDetailBySymbol("AAPL", "equity", "us", "en");

// Get stock detail by ID
const stock = await client.getStockDetailByID("stock-id", "en");

// Get historical prices
const prices = await client.getHistoricalPrices(["AAPL", "GOOGL"], "us", [
  "1d",
  "1w",
]);

// Get historical prices with custom interval
const prices = await client.getCustomHistoricalPrices(
  "AAPL",
  "us",
  "2024-01-01",
  "2024-01-31",
  "1m",
  true
);

// Get tick rules (Turkey only)
const rules = await client.getTickRules("THYAO", "tr");

// Get restrictions (Turkey only)
const restrictions = await client.getStockRestrictions("THYAO", "tr");

Collections Client

// Get all collections
const collections = await client.getAllCollections("tr", "en");

// Get collection detail
const detail = await client.getCollectionDetail("collection-id", "tr", "en");

// Get themes
const themes = await client.getAllThemes("tr", "en");

// Get theme detail
const themeDetail = await client.getThemeDetail("theme-id", "tr", "en");

// Get industries
const industries = await client.getAllIndustries("tr", "en");

// Get industry detail
const industryDetail = await client.getIndustryDetail(
  "industry-id",
  "tr",
  "en"
);

// Get sectors
const sectors = await client.getAllSectors("tr", "en");

// Get sector detail
const sectorDetail = await client.getSectorDetail("sector-id", "tr", "en");

Funds Client

// Get all funds
const funds = await client.getFunds("tr", 1, 10);

// Get fund statistics
const stats = await client.getFundStats("fund-symbol", "tr");

// Get fund distribution
const distribution = await client.getFundDistribution("fund-symbol", "tr");

// Get historical fund prices
const prices = await client.getHistoricalFundPrices("fund-symbol", "tr", "1y");

Financial Data Client

// Get financial ratios
const ratios = await client.getHistoricalRatios(
  "AAPL",
  ["pe-ratio"],
  "us",
  "en"
);

// Get financial ratio comparisons
const comparisons = await client.getFinancialRatioComparison(
  "AAPL",
  "us",
  "sector"
);

// Get stock dividends
const dividends = await client.getStockDividends("AAPL", "us");

// Get stock statistics
const stats = await client.getStockStats(["AAPL", "GOOGL"], "us");

// Get top movers
const movers = await client.getTopMovers(
  "us",
  1,
  10,
  "gainers",
  "stock",
  "equity"
);

Live Price Client

// Get live prices for BIST stocks
const bistClient = client.getLivePriceForBIST(["THYAO", "GARAN"]);

// Get live prices for US stocks
const usClient = client.getLivePriceForUS(["AAPL", "GOOGL"]);

// Receive live data
for await (const data of bistClient.receive()) {
  console.log("Received BIST data:", data);
  // data.s - symbol, data.p - price, data.ch - change, data.d - date
}

// Subscribe to different symbols
await bistClient.subscribe(["AKBNK", "EREGL"]);

// Close connection
bistClient.close();

Brokers Client

// Get all brokers
const brokers = await client.getBrokers("tr", 1, 10);

// Get market stocks with broker statistics
const marketStocks = await client.getMarketStocks(
  "tr",
  "netAmount",
  "desc",
  "2024-01-01",
  "2024-01-31",
  1,
  10
);

// Get brokers by stock
const brokersByStock = await client.getBrokersByStock(
  "THYAO",
  "tr",
  "netAmount",
  "desc",
  "2024-01-01",
  "2024-01-31",
  1,
  10
);

Search Client

// Search across stocks, collections, sectors, and industries
const results = await client.search(
  "technology",
  ["stock", "collection"],
  "us",
  "en"
);

WebSocket Client

// Server Side
// Initialize LivePriceClient for server side use
const livePriceClient = new LivePriceClient(config, logger);

// Retrieve a websocket connection URL for the client, pass the URL to the client
const wsURL = await livePriceClient.getClientWebsocketUrl('external-user-id', [LivePriceFeed.LiveBist])

// Client Side
// Client side retrieves the websocket connection URL from the server as wsURL
// Create WebSocket client for real-time data
const webSocketClient = new LivePriceWebSocketClient();

// Connect to WebSocket
await webSocketClient.connect(wsURL);

// Subscribe to live price feeds
const unsubscribe = webSocketClient.subscribe(
  ["THYAO", "GARAN"],
  LivePriceFeed.LiveBist,
  (data) => {
    console.log("Received live data:", data);
  }
);

// Close connection
await webSocketClient.close();

// Server Side
// Use livePriceClient.getWebsocketUsageForMonth for getting a report on websocket client usage
const usage = await livePriceClient.getWebsocketUsageForMonth('8', '2025', LivePriceFeed.LiveBist);

Capital Increase Client

// Get all capital increases
const increases = await client.getAllCapitalIncreases(1, 10, "tr");

// Get capital increases for a specific instrument
const instrumentIncreases = await client.getCapitalIncreasesForInstrument(
  "THYAO",
  1,
  10,
  "tr"
);

// Get active rights for an instrument
const rights = await client.getActiveRightsForInstrument(
  "THYAO",
  "2024-01-15",
  "tr"
);

Custom Themes Client

// Get all custom themes
const themes = await client.getAllCustomThemes("en");

// Get custom theme detail
const themeDetail = await client.getCustomThemeDetail("theme-id", "en", null);

// Create a custom theme
const id = await client.createCustomTheme({
  title: { en: "My Tech Portfolio" },
  description: { en: "Technology stocks portfolio" },
  region: ["us"],
  stocks: ["stock-id-1", "stock-id-2"],
  status: "active",
});

// Update a custom theme
await client.updateCustomTheme(id, {
  title: { en: "Updated Tech Portfolio" },
  stockIds: ["stock-id-1", "stock-id-2"],
});

// Delete a custom theme
await client.deleteCustomTheme(id);

Key Insights Client

// Get key insights for a stock
const insights = await client.getKeyInsights("AAPL", "us");

Supported Regions

• US: United States stock market
• TR: Turkey stock market (Borsa Istanbul)

Error Handling

import { createClient } from "laplace-api-js";
import { LaplaceHTTPError } from "laplace-api-js";

const client = createClient(config, logger);

try {
  const stock = await client.getStockDetailBySymbol(
    "INVALID",
    "equity",
    "us",
    "en"
  );
} catch (error) {
  if (error instanceof LaplaceHTTPError) {
    console.log(`API Error: ${error.message}`);
    console.log(`Status Code: ${error.httpStatus}`);
  } else {
    console.log(`Error: ${error}`);
  }
}

Authentication

Get your API key from the Laplace platform and initialize the client:

import { createClient } from "laplace-api-js";
import { LaplaceConfiguration } from "laplace-api-js";

const config: LaplaceConfiguration = {
  apiKey: "your-api-key-here",
  baseURL: "https://api.laplace.finfree.co",
};

const client = createClient(config, logger);

Configuration

You can also load configuration from environment variables:

import { loadGlobal } from "laplace-api-js";

const config = loadGlobal();
const client = createClient(config, logger);

Environment variables:

• API_KEY: Your API key
• BASE_URL: API base URL

Development

Setup

git clone https://github.com/Laplace-Analytics/laplace-api-js.git
cd laplace-api-js
npm install

Building

# Build the project
npm run build

# Build with type checking
npm run build:check

Requirements

• Node.js 18+
• TypeScript 5.0+

Documentation

Full API documentation is available at laplace.finfree.co/en/docs

License

This project is licensed under the MIT License - see the LICENSE file for details.