get_market_overview
Retrieve market cap, volume, and sector performance data for specific stock exchanges on chosen dates to analyze historical market conditions.
Instructions
Get total market cap, volume, value, and performance for an exchange on a specific date with a sector breakdown.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stockExchange | Yes | Stock exchange: amex, nasdaq, nyse, us-all, lse, moex, bist, hkex | |
| year | No | ||
| month | No | ||
| day | No |
Implementation Reference
- src/core.ts:490-545 (handler)The handler function for the 'get_market_overview' tool. It fetches market data for the given exchange and date, filters sector items, aggregates market totals and sector metrics (marketCap, volume, value, numTrades, change %), and returns a formatted response including charts links.async ({ stockExchange, year, month, day, }: { stockExchange: StockExchange; year?: number; month?: number; day?: number; }) => { try { const formattedDate = getDate(year, month, day); const marketDataResponse = await fetchMarketData( stockExchange, formattedDate, ); const sectorItems = marketDataResponse.securities.data.filter( (item: any) => item[INDICES.TYPE] === "sector", ); let marketTotal = {}; const sectors: any[] = []; sectorItems.forEach((item: any) => { const sectorData = { name: item[INDICES.TICKER], marketCap: item[INDICES.MARKET_CAP], marketCapChangePct: item[INDICES.PRICE_CHANGE_PCT], volume: item[INDICES.VOLUME], value: item[INDICES.VALUE], numTrades: item[INDICES.NUM_TRADES], itemsPerSector: item[INDICES.ITEMS_PER_SECTOR], }; if (item[INDICES.SECTOR] === "") { marketTotal = sectorData; } else { sectors.push(sectorData); } }); return createResponse({ info: INFO, charts: createCharts(stockExchange, formattedDate), date: formattedDate, exchange: stockExchange.toUpperCase(), currency: EXCHANGE_INFO[stockExchange as StockExchange].currency, marketTotal, sectors, }); } catch (error) { return createErrorResponse(error); } },
- src/core.ts:484-489 (schema)Input schema and metadata (title, description) for the 'get_market_overview' tool, referencing shared exchangeSchema and dateSchema.{ title: "Market overview", description: "Get total market cap, volume, value, and performance for an exchange on a specific date with a sector breakdown.", inputSchema: { stockExchange: exchangeSchema, ...dateSchema }, },
- src/core.ts:482-546 (registration)The server.registerTool call that registers the 'get_market_overview' tool within the registerFinmapTools function.server.registerTool( "get_market_overview", { title: "Market overview", description: "Get total market cap, volume, value, and performance for an exchange on a specific date with a sector breakdown.", inputSchema: { stockExchange: exchangeSchema, ...dateSchema }, }, async ({ stockExchange, year, month, day, }: { stockExchange: StockExchange; year?: number; month?: number; day?: number; }) => { try { const formattedDate = getDate(year, month, day); const marketDataResponse = await fetchMarketData( stockExchange, formattedDate, ); const sectorItems = marketDataResponse.securities.data.filter( (item: any) => item[INDICES.TYPE] === "sector", ); let marketTotal = {}; const sectors: any[] = []; sectorItems.forEach((item: any) => { const sectorData = { name: item[INDICES.TICKER], marketCap: item[INDICES.MARKET_CAP], marketCapChangePct: item[INDICES.PRICE_CHANGE_PCT], volume: item[INDICES.VOLUME], value: item[INDICES.VALUE], numTrades: item[INDICES.NUM_TRADES], itemsPerSector: item[INDICES.ITEMS_PER_SECTOR], }; if (item[INDICES.SECTOR] === "") { marketTotal = sectorData; } else { sectors.push(sectorData); } }); return createResponse({ info: INFO, charts: createCharts(stockExchange, formattedDate), date: formattedDate, exchange: stockExchange.toUpperCase(), currency: EXCHANGE_INFO[stockExchange as StockExchange].currency, marketTotal, sectors, }); } catch (error) { return createErrorResponse(error); } }, );
- src/core.ts:219-235 (helper)Helper function fetchMarketData used by the handler to retrieve market data JSON from GitHub for the specified exchange and date.async function fetchMarketData( stockExchange: StockExchange, formattedDate: string, ): Promise<{ securities: { data: any[][] } }> { const country = EXCHANGE_TO_COUNTRY_MAP[stockExchange]; const date = formattedDate.replaceAll("-", "/"); const url = `${DATA_BASE_URL}/data-${country}/refs/heads/main/marketdata/${date}/${stockExchange}.json`; const response = await fetch(url); if (response.status === 404) { throw new Error( `Not found, try another date. The date must be on or after ${EXCHANGE_INFO[stockExchange].availableSince} for ${stockExchange}`, ); } return response.json(); }