# Historical Data

The **Developer API** provides endpoints for **time-series** **candlestick data**, allowing you to retrieve both **intraday** and **daily (EOD) price** information. This historical data is vital for charting, backtesting, and analysing market trends—whether for short-term decisions (using **1-minute** or **5-minute** candles) or long-term strategies (using **daily** candlesticks).

### Candle Data (Intraday)

#### Overview of Intraday Candlesticks

The **time-price-series-regular-interval** endpoint (sometimes referred to as **Intraday Candle Data**) returns candlesticks at intervals such as **1 minute, 2 minutes, 5 minutes,** etc. These lower timeframes are ideal for day traders, algorithmic strategies, or any application needing detailed **intra-session** movements.

**Key Features:**

* **Customisable Intervals:** Acceptable values typically include "1mi", "2mi", "5mi", and so on.
* **Flexible Date Range:** Provide startTime and endTime in DD-MM-YYYY HH:MM:SS format to retrieve data within that window.
* **Common Use Cases:** Building intraday charts, scanning for real-time patterns, or backtesting short-term signals.

#### Formats

Each candle returned by the API usually contains fields like:

* **time:** The candle’s start timestamp, often in ISO-like format (e.g., "YYYY-MM-DDTHH:MM:SS").
* **epochTime:** An integer representing Unix timestamp (seconds since 1970-01-01).
* **open / high / low / close (floats):** The intraday O-H-L-C values for that interval.
* **volume (float or integer):** The total traded volume during the candle.
* **oi (Open Interest):** A number relevant to futures/options; often 0 for equities.
* **token:** A field that may remain empty ("") in some responses or represent an internal identifier.

**Example Intraday Candle:**

```json
{
  "time": "2025-02-10T09:15:00",
  "epochTime": 1739159100,
  "open": 23543.8,
  "high": 23548.65,
  "low": 23472.2,
  "close": 23480.1,
  "volume": 0,
  "oi": 0,
  "token": ""
}
```

**Reference:** See time-price-regular-interval for request/response details.

### Day Chart Data

#### Overview of Daily Candles (EOD)

For **day-by-day** candlestick data—often called **EOD (End of Day)** data—the **time-price-series-day-interval** endpoint lets you retrieve open, high, low, close for each trading day within a specified date range. This is crucial for:

* **Long-Term Analysis:** Spotting broader trends in daily, weekly, or monthly horizons.
* **Backtesting:** Historical patterns spanning months or years.
* **EOD Charting:** Plotting daily candles for longer timeframes.

#### Request Format & Usage

Unlike intraday intervals (e.g., "1mi"), the **daily** endpoint typically requires interval = "1d". You’ll also specify startTime and endTime in the DD-MM-YYYY HH:MM:SS format, but it effectively returns day-level data.

**Reference:** See [time-price-day-interval](https://firstock.in/api/docs/time-price-day-interval/) for details on forming requests and interpreting responses.

#### Example Day Candle

```json
{
  "time": "2025-02-11T00:00:00",
  "epochTime": 1739212200,
  "open": 23383.55,
  "high": 23390.05,
  "low": 22986.65,
  "close": 23071.8,
  "volume": 0,
  "oi": 0,
  "token": ""
}
```

**Notes:**

* volume may be zero or a float, depending on the instrument.
* For F\&O instruments, oi (Open Interest) can provide further insight.

### Best Practices & Tips

* **Choose the Right Interval**
  * For day traders or short-term signals, use intraday intervals (1mi, 2mi, etc.).
  * For longer-term strategy or EOD charting, use daily intervals (1d).
* **Manage Date Ranges**
  * Avoid overly large requests in a single call to prevent timeouts or performance issues.
  * Paginate or chunk date windows if you need extensive historical data.
* **Parse & Store Data**
  * Convert any numeric fields (like open, close) from strings to floats if needed for calculations or chart libraries.
  * Store historical data locally for faster repeated access and offline analysis.
* **Authentication**
  * Ensure valid jKey is included in each request; session tokens can expire.
  * Check for INVALID\_JKEY or session-related errors if your calls fail unexpectedly.
* **Rate Limit Respect**
  * The current limit is **10 requests per second**. If you plan to load many intervals or large date ranges, consider queueing or backoff to avoid 429 errors.

### Further Reading

* Request & Response: [General guidelines](https://firstock.in/api/docs/request-responses/) on JSON structures, error objects, etc.
* Exception & Error Handling: [Overview](https://firstock.in/api/docs/exception-errors/) of how to parse failed responses, including missing fields or session token issues.
* Versioning & Upgrading: If you’re using older endpoints, see [Versioning](https://firstock.in/api/docs/versioning/) to learn about new releases and migration tips.

### Conclusion

By leveraging the **time-price-series-regular-interval** and **time-price-day-interval** endpoints, developers can gather both **intraday** and **daily** candlestick data—essential for dynamic charting, backtesting, or data analysis. Keep in mind the best practices around **rate limits, authentication,** and **data parsing** for smooth, efficient usage of these historical data APIs. If you encounter issues or have further questions, consult the official documentation or reach out to support for tailored help.
