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

``bash
npm install laplace-api-js
`

Quick Start

`typescript
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

$3

`typescript
// 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");
`

$3

`typescript
// 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");
`

$3

`typescript
// 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");
`

$3

`typescript
// 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"
);
`

$3

`typescript
// 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();
`

$3

`typescript
// 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
);
`

$3

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

$3

`typescript
// 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);
`

$3

`typescript
// 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"
);
`

$3

`typescript
// 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);
`

$3

`typescript
// 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

`typescript
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:

`typescript
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:

`typescript
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

$3

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

$3

`bash


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.