From de875a3ebeb74ac6d506f1b09777931efe3cb612 Mon Sep 17 00:00:00 2001
From: donpat1to <patrick@inca-vikingo.de>
Date: Mon, 1 Dec 2025 13:24:55 +0100
Subject: [PATCH] added figi.md for figi description

---
 src/corporate/figi.md | 141 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 src/corporate/figi.md

diff --git a/src/corporate/figi.md b/src/corporate/figi.md
new file mode 100644
index 0000000..9c4d619
--- /dev/null
+++ b/src/corporate/figi.md
@@ -0,0 +1,141 @@
+# OpenFIGI API Summary: Mapping, Search, and Filter Endpoints
+
+This Markdown summary covers the **API Guidelines**, **Request Format**, and **Sample Request -> Sample Response** for the key OpenFIGI endpoints: Mapping, Search, and Filter. Information is based on the official documentation as of December 1, 2025.
+
+## Mapping Endpoint
+
+### API Guidelines
+- **Endpoint**: `POST /v3/mapping`
+- **Purpose**: Map third-party identifiers (e.g., ISIN, TICKER) to FIGIs (Financial Instrument Global Identifiers).
+- **Request Format**: JSON array of objects (mapping jobs). Each job requires `idType` and `idValue`. Optional filters: `exchCode`, `micCode`, `currency`, `marketSecDes`, `securityType`, `securityType2`, `includeUnlistedEquities`, `optionType`, `strike`, `contractSize`, `coupon`, `expiration`, `maturity`, `stateCode`.
+- **Key Parameters**:
+  - `idType` (String, Required): Identifier type (e.g., `ID_BB_GLOBAL`, `TICKER`, `ID_ISIN`).
+  - `idValue` (String/Number, Required): The identifier value.
+  - `exchCode` (String, Optional): Exchange code (mutually exclusive with `micCode`).
+  - `micCode` (String, Optional): Market Identification Code (mutually exclusive with `exchCode`).
+  - Range parameters (e.g., `strike`, `expiration`): Arrays like `[a, b]` or `[a, null]` for intervals.
+  - `includeUnlistedEquities` (Boolean, Optional): Defaults to `false`.
+- **Limits**:
+  - Without API key: Max 5 jobs per request.
+  - With API key: Max 100 jobs per request.
+- **Rate Limits**:
+  - Without API key: 25 requests/minute.
+  - With API key: 25 requests/6 seconds.
+- **Authentication**: Include `X-OPENFIGI-APIKEY` header for higher limits.
+
+### Sample Request
+```json
+[
+    { "idType": "ID_BB_GLOBAL", "idValue": "BBG000BLNNH6" },
+    { "idType": "TICKER", "idValue": "IBM", "exchCode": "US" },
+    { "idType": "BASE_TICKER", "idValue": "TSLA 10 C100", "securityType2": "Option", "expiration": ["2018-10-01", "2018-12-01"] }
+]
+```
+
+### Sample Response
+```json
+[{
+    "data": [{
+        "figi": "BBG000BLNNH6",
+        "securityType": "Common Stock",
+        "marketSector": "Equity",
+        "ticker": "IBM",
+        "name": "INTL BUSINESS MACHINES CORP",
+        "exchCode": "US",
+        "shareClassFIGI": "BBG001S5S399",
+        "compositeFIGI": "BBG000BLNNH6",
+        "securityType2": "Common Stock",
+        "securityDescription": "IBM"
+    }]
+}]
+```
+
+## Search Endpoint
+
+### API Guidelines
+- **Endpoint**: `POST /v3/search`
+- **Purpose**: Keyword-based search for FIGIs with optional filters; supports pagination.
+- **Request Format**: JSON object with optional `query` (keywords) and filters (same as Mapping). Use `start` for pagination.
+- **Key Parameters**:
+  - `query` (String, Optional): Search keywords (e.g., "ibm").
+  - `start` (String, Optional): Pagination token from previous `next` field.
+  - All Mapping filters supported (e.g., `exchCode`, `securityType`, `optionType`).
+- **Limits**:
+  - Max results: 15,000.
+  - Max per page: 100.
+  - Max pages: 150.
+- **Rate Limits**:
+  - Without API key: 5 requests/minute.
+  - With API key: 20 requests/minute.
+- **Pagination**: Response includes `next` token; use as `start` in next request.
+- **Authentication**: Same as Mapping.
+
+### Sample Request
+```json
+{
+    "query": "ibm",
+    "exchCode": "US"
+}
+```
+
+### Sample Response
+```json
+{
+    "data": [
+        {
+            "figi": "BBG000BLNNH6",
+            "name": "INTL BUSINESS MACHINES CORP",
+            "ticker": "IBM",
+            "exchCode": "US",
+            "compositeFIGI": "BBG000BLNNH6",
+            "securityType": "Common Stock",
+            "marketSector": "Equity",
+            "shareClassFIGI": "BBG001S5S399",
+            "securityType2": "Common Stock",
+            "securityDescription": "IBM"
+        }
+    ],
+    "next": "QW9JSVFEOFMrQ3hDUWtjd01ERTRTMHhhUXpBPSAx.3AG33VCsv54AsUl5fGHehSytWPuWLJxf0t8VL3YXuJh="
+}
+```
+
+## Filter Endpoint
+
+### API Guidelines
+- **Endpoint**: `POST /v3/filter`
+- **Purpose**: Filter-based search for FIGIs (no keywords required); results sorted alphabetically by FIGI, includes total count.
+- **Request Format**: JSON object with optional `query` and filters (same as Search/Mapping). Use `start` for pagination.
+- **Key Parameters**: Identical to Search (`query`, `start`, and all Mapping filters).
+- **Limits**: Same as Search (15,000 max results, 100/page, 150 pages).
+- **Rate Limits**: Same as Search (5/min without key, 20/min with key).
+- **Pagination**: Same as Search; response includes `total` count.
+- **Authentication**: Same as Mapping.
+
+### Sample Request
+```json
+{
+    "exchCode": "US"
+}
+```
+
+### Sample Response
+```json
+{
+    "data": [
+        {
+            "figi": "BBG000BLNNH6",
+            "name": "INTL BUSINESS MACHINES CORP",
+            "ticker": "IBM",
+            "exchCode": "US",
+            "compositeFIGI": "BBG000BLNNH6",
+            "securityType": "Common Stock",
+            "marketSector": "Equity",
+            "shareClassFIGI": "BBG001S5S399",
+            "securityType2": "Common Stock",
+            "securityDescription": "IBM"
+        }
+    ],
+    "next": "QW9JSVFEOFMrQ3hDUWtjd01ERTRTMHhhUXpBPSAx.3AG33VCsv54AsUl5fGHehSytWPuWLJxf0t8VL3YXuJh=",
+    "total": 29930312
+}
+```
\ No newline at end of file