Package Exports
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (laplace-api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
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 keyBASE_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.