npm package: @indices-api/sdk
Description: Official Node.js client for the Indices-API.
Author: Zyla Labs
Latest version: 0.1.1

# Indices-API Node.js SDK

Official Node.js SDK for Indices-API – the ultimate API for accessing comprehensive and accurate real-time and historical rates on a wide range of financial indices.

Indices-API supports many index symbols with frequent updates (depending on your plan). Start a 7‑day free trial and cancel anytime.

## Key Features

- **Built for developers**: Simple, typed API designed for Node.js and TypeScript.
- **Robust JSON API**: Thin, predictable wrapper over the Indices-API JSON endpoints.
- **Top-tier security**: Your API key is sent over HTTPS to trusted, enterprise-grade infrastructure.
- **Reliable data sources**: Data aggregated from reputable financial and market data providers.
- **Flexible integration**: Works in any Node.js app (CommonJS or ESM) and with TypeScript.
- **Historical data access**: Query historical and time-series data for deeper analysis.
- **Exceptional accuracy**: Real-time and historical index data with high precision.
- **User-friendly documentation**: See the full API docs at `https://indices-api.com/documentation`.
- **Specialized support**: Dedicated support team to help with integration and use-cases.

## Supported Indices

Indices-API covers a wide range of instruments, including (examples):

- **Equity indices**: S&P 500, Nasdaq 100, Dow Jones, FTSE 100, and more.
- **Regional indices**: European, Asian, and emerging market indices.
- **Sector indices**: Technology, financials, energy, and other sector-based benchmarks.

You can find the full, always up-to-date list of supported symbols in the Supported Indices section of the official documentation.

## Installation

Install the SDK from npm:

```bash
npm install @indices-api/sdk
```

This package is written in TypeScript and ships with type definitions out of the box.

## Getting Started

First, sign up at `https://indices-api.com` to get your API key and some free credits.

### Basic Usage (TypeScript / ESM)

```typescript
import { IndicesClient } from "@indices-api/sdk";

const client = new IndicesClient("REPLACE-WITH-YOUR-ACCESS-KEY");

async function main() {
  const latest = await client.latest({
    base: "USD",
    symbols: "000001,IXIC,GSPC,EGX-30"
  });

  console.log(latest);
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});
```

### Basic Usage (CommonJS)

```js
// If your project uses CommonJS, you can import via dynamic import:
(async () => {
  const { IndicesClient } = await import("@indices-api/sdk");

  const client = new IndicesClient("REPLACE-WITH-YOUR-ACCESS-KEY");
  const latest = await client.latest({
    base: "USD",
    symbols: "000001,IXIC,GSPC,EGX-30"
  });

  console.log(latest);
})();
```

## Example Response

Example response for a successful latest request (shape may vary depending on plan and endpoint):

```json
{
  "data": {
    "success": true,
    "timestamp": 1715796300,
    "date": "2024-05-15",
    "base": "USD",
    "rates": {
      "000001": 3025.15,
      "IXIC": 18450.33,
      "GSPC": 5231.57,
      "EGX-30": 27500.42,
      "USD": 1
    },
    "unit": {
      "000001": "index points",
      "IXIC": "index points",
      "GSPC": "index points",
      "EGX-30": "index points"
    }
  }
}
```

The exact structure of the `data` object depends on the endpoint and your plan. Refer to the official documentation for the complete schema.

## Available Methods

All methods live on the `IndicesClient` class.

### `latest(params?: LatestParams)`

Fetches the most recent rates for the requested symbols.

```ts
await client.latest({
  base: "USD",
  symbols: "000001,IXIC,GSPC,EGX-30"
});
```

### `historical(params: HistoricalParams)`

Get historical rates for a given date (`YYYY-MM-DD`).

```ts
await client.historical({
  date: "2024-05-15",
  base: "USD",
  symbols: "000001,IXIC,GSPC,EGX-30"
});
```

### `timeSeries(params: TimeSeriesParams)`

Retrieve time-series data between two dates.

```ts
await client.timeSeries({
  start_date: "2024-05-01",
  end_date: "2024-05-15",
  base: "USD",
  symbols: "000001,IXIC,GSPC,EGX-30"
});
```

### `fluctuation(params: FluctuationParams)`

Get day-to-day or period fluctuation data.

```ts
await client.fluctuation({
  start_date: "2024-05-01",
  end_date: "2024-05-15",
  base: "USD",
  symbols: "000001,IXIC,GSPC,EGX-30"
});
```

### `convert(params: ConvertParams)`

Convert an amount between two symbols.

```ts
await client.convert({
  from: "GSPC",
  to: "IXIC",
  amount: 100
});
```

### `symbols()`

List available symbols and their metadata (depends on plan).

```ts
await client.symbols();
```

### `seasonality(params: SeasonalityParams)`

Retrieve seasonality metrics for a given symbol.

```ts
await client.seasonality({
  symbol: "GSPC",
  group_by: "month",
  base: "USD",
  years: 5
});
```

Types like `LatestParams`, `HistoricalParams`, `TimeSeriesParams`, etc. are exported from the SDK for strong typing in TypeScript projects.

## Error Handling

All requests may throw an `IndicesApiError` when:

- The API returns an error payload, or
- The network fails, or
- The response is not valid JSON.

```ts
import { IndicesClient, IndicesApiError } from "@indices-api/sdk";

const client = new IndicesClient("REPLACE-WITH-YOUR-ACCESS-KEY");

async function main() {
  try {
    const latest = await client.latest({ base: "USD", symbols: "000001,IXIC,GSPC,EGX-30" });
    console.log(latest);
  } catch (err) {
    if (err instanceof IndicesApiError) {
      console.error("Status code:", err.statusCode);
      console.error("Error code:", err.errorCode);
      console.error("Message:", err.message);
    } else {
      console.error("Unexpected error:", err);
    }
  }
}

main().catch(console.error);
```

## Documentation & Support

- **API documentation**: `https://indices-api.com/documentation`
- **Website**: `https://indices-api.com`

If you have questions or need help with integration, please reach out through the official support channels listed in the Indices-API dashboard.