laplace-api
Version:
Client library for Laplace API for the US stock market and BIST (Istanbul stock market) fundamental financial data.
475 lines (367 loc) • 11 kB
Markdown
# Laplace TypeScript/JavaScript SDK
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/laplace-api-js)
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
### Stocks Client
```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");
```
### Collections Client
```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");
```
### Funds Client
```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");
```
### Financial Data Client
```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"
);
```
### Live Price Client
```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();
```
### Brokers Client
```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
);
```
### Search Client
```typescript
// Search across stocks, collections, sectors, and industries
const results = await client.search(
"technology",
["stock", "collection"],
"us",
"en"
);
```
### WebSocket Client
```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);
```
### Capital Increase Client
```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"
);
```
### Custom Themes Client
```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);
```
### Key Insights Client
```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
### Setup
```bash
git clone https://github.com/Laplace-Analytics/laplace-api-js.git
cd laplace-api-js
npm install
```
### Building
```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](https://laplace.finfree.co/en/docs)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.