# 📈 borsa-api
### Turkish Stock Market (BIST) API Wrapper & CLI Tool
**Türk Borsası (BIST) için API wrapper ve CLI aracı**
[](https://www.npmjs.com/package/borsa-api)
[](https://www.npmjs.com/package/borsa-api)
[](https://github.com/ibidi/borsa-api/blob/main/LICENSE)
[](https://github.com/ibidi/borsa-api)
[Installation](#-installation--kurulum) •
[Features](#-features--özellikler) •
[Usage](#-cli-usage--cli-kullanımı) •
[API](#-programmatic-usage--kod-içinde-kullanım) •
[Examples](#-usage-example)
---
## 🚀 Features / Özellikler
- 📊 **BIST Indexes** - XU100, XU030, XBANK, and more
- 📈 **Stock Data** - Delayed stock prices and information
- 🔍 **Search** - Find stocks by name or symbol (Turkish character support)
- ⭐ **Watchlist** - Save and track your favorite stocks
- ⚖️ **Compare** - Compare two stocks side by side
- 📈 **Top Gainers/Losers** - See best and worst performers
- 💹 **Volume Leaders** - Highest volume stocks
- 💻 **Beautiful CLI** - Professional terminal interface with colors and tables
- 📦 **API Wrapper** - Use programmatically in your code
- 🇹🇷 **Turkish Support** - Native Turkish language support
- ⚡ **Fast & Reliable** - Optimized for performance
- 📘 **TypeScript** - Full TypeScript support with type definitions
## 📦 Installation / Kurulum
### Global (CLI kullanımı için)
```bash
npm install -g borsa-api
```
### Local (Kod içinde kullanım için)
```bash
npm install borsa-api
```
## 🎯 CLI Usage / CLI Kullanımı
### Endeks Görüntüleme
```bash
# XU100 endeksi (varsayılan)
borsa endeks
# Belirli bir endeks
borsa endeks XU030
borsa endeks XBANK
```
### Hisse Senedi Görüntüleme
```bash
borsa hisse THYAO
borsa hisse GARAN
borsa hisse EREGL
```
### Popüler Hisseler
```bash
borsa populer
```
### Tüm Endeksler
```bash
borsa endeksler
```
### Hisse Arama
```bash
borsa ara garanti
borsa ara turkcell
```
### İzleme Listesi (Watchlist)
```bash
# İzleme listesine ekle
borsa watchlist --add THYAO
borsa watchlist --add GARAN
# İzleme listesini göster
borsa watchlist
# İzleme listesinden çıkar
borsa watchlist --remove THYAO
# İzleme listesini temizle
borsa watchlist --clear
```
### Hisse Karşılaştırma
```bash
borsa karsilastir THYAO GARAN
borsa compare AKBNK ISCTR
```
### En Çok Yükselenler/Düşenler
```bash
# En çok yükselenler (varsayılan 10)
borsa yukselenler
borsa yukselenler 5
# En çok düşenler
borsa dusenler
borsa dusenler 5
# En yüksek hacimli hisseler
borsa hacim
borsa hacim 5
```
### Historik Veri ve Detaylı Bilgi
```bash
# Geçmiş fiyat verileri
borsa gecmis THYAO # Son 1 ay (varsayılan)
borsa gecmis THYAO 5d # Son 5 gün
borsa gecmis THYAO 1y # Son 1 yıl
borsa historical AKBNK 3mo # Son 3 ay
# Detaylı hisse bilgisi (market cap, P/E ratio, sektör, vb.)
borsa detay THYAO
borsa details GARAN
```
## 💻 Programmatic Usage / Kod İçinde Kullanım
```javascript
const BorsaAPI = require('borsa-api');
const api = new BorsaAPI();
// Endeks verisi al
async function getIndex() {
try {
const xu100 = await api.getIndex('XU100');
console.log(xu100);
// {
// symbol: 'XU100',
// name: 'BIST 100',
// value: 9234.56,
// change: 123.45,
// changePercent: 1.35,
// high: 9250.00,
// low: 9100.00,
// volume: 12345678,
// timestamp: '2024-11-16T...'
// }
} catch (error) {
console.error(error.message);
}
}
// Hisse senedi verisi al
async function getStock() {
try {
const thyao = await api.getStock('THYAO');
console.log(thyao);
// {
// symbol: 'THYAO',
// name: 'TURK HAVA YOLLARI',
// price: 234.50,
// change: 5.25,
// changePercent: 2.29,
// high: 236.00,
// low: 230.00,
// open: 231.00,
// close: 229.25,
// volume: 1234567,
// timestamp: '2024-11-16T...'
// }
} catch (error) {
console.error(error.message);
}
}
// Popüler hisseler
async function getPopular() {
const stocks = await api.getPopularStocks();
console.log(stocks);
}
// Tüm endeksler
async function getAllIndexes() {
const indexes = await api.getAllIndexes();
console.log(indexes);
}
// Hisse arama
async function search() {
const results = await api.searchStock('garanti');
console.log(results);
}
// Historik veri
async function getHistorical() {
const data = await api.getHistoricalData('THYAO', {
period: '1mo', // 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
interval: '1d' // 1d, 1wk, 1mo
});
console.log(data);
// {
// meta: {
// currency: 'TRY',
// symbol: 'THYAO',
// longName: 'Türk Hava Yollari...',
// fiftyTwoWeekHigh: 346.25,
// fiftyTwoWeekLow: 249.20,
// ...
// },
// quotes: [
// {
// date: Date,
// open: 273.00,
// high: 274.75,
// low: 271.50,
// close: 273.00,
// adjClose: 266.68,
// volume: 19991989
// },
// ...
// ]
// }
}
// Detaylı hisse bilgisi
async function getDetails() {
const details = await api.getStockDetails('THYAO');
console.log(details);
// {
// ...StockData,
// marketCap: 123456789000,
// peRatio: 15.23,
// eps: 12.34,
// dividendYield: 0.025,
// fiftyTwoWeekHigh: 346.25,
// fiftyTwoWeekLow: 249.20,
// averageVolume: 25000000,
// beta: 1.15,
// sector: 'Industrials',
// industry: 'Airlines',
// description: 'Company description...'
// }
}
// İki hisseyi karşılaştır
async function compare() {
const comparison = await api.compareStocks('THYAO', 'GARAN');
console.log(comparison);
}
// En çok yükselenler
async function topGainers() {
const gainers = await api.getTopGainers(5);
console.log(gainers);
}
// En çok düşenler
async function topLosers() {
const losers = await api.getTopLosers(5);
console.log(losers);
}
// En yüksek hacimli hisseler
async function topVolume() {
const volume = await api.getTopVolume(5);
console.log(volume);
}
// Watchlist işlemleri
api.watchlist.addToWatchlist('THYAO', 'Türk Hava Yolları');
api.watchlist.addToWatchlist('GARAN', 'Garanti Bankası');
const watchlist = api.watchlist.getWatchlist();
console.log(watchlist);
// Watchlist verilerini getir
async function getWatchlistData() {
const stocks = await api.getWatchlistData();
console.log(stocks);
}
// Verileri export et
const { exportToJSON, exportToCSV } = api.utils;
const stocks = await api.getPopularStocks();
exportToJSON(stocks, 'stocks.json');
exportToCSV(stocks, 'stocks.csv');
```
## 🎨 CLI Screenshots / Ekran Görüntüleri
```
$ borsa endeks XU100
📊 BIST 100 (XU100)
──────────────────────────────────────────────────
Değer: 9234.56
Değişim: ▲ 123.45 (1.35%)
Yüksek: 9250.00
Düşük: 9100.00
Hacim: 12,345,678
──────────────────────────────────────────────────
```
## 🔧 API Methods / API Metodları
### `getIndex(symbol)`
Get index data / Endeks verisi al
**Parameters:**
- `symbol` (string) - Index symbol (XU100, XU030, etc.)
**Returns:** Promise