finddata.skill

v1.0.0

Query global public data series across 10 sources using natural language for instant financial, economic, and trade metrics with your FindData API key.

1· 259· 1 versions· 0 current· 0 all-time· Updated 20h ago· MIT-0

by@williamkonggh

Security Scans

VirusTotalBenign ClawScanBenign Static analysisBenign

Install

openclaw skills install finddata

FindData — Data Intelligence Skill

Query global data with a single API call. Supports natural language in English and Chinese.

Simple queries (stock price, GDP, exchange rate) use a fast path — Voyage AI selects the tool and rules extract parameters, no LLM needed (~1s). Complex queries (comparisons, derived metrics like profit margin) use LLM planning to generate a multi-step execution plan (~3-5s).

Endpoint: https://finddata.ai/api/query Method: POST Auth: X-API-Key

Content-Type: application/json Body: {"query": "your natural language question"}

Setup

Get your API key at https://finddata.ai (free tier available)
Set your environment variable:

export FINDDATA_API_KEY="odh_your_key_here"

If the user provides their key in the message (starts with odh_), extract it and use it directly.

Usage

curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Apple stock price"}'

More examples

# US economic data
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "US inflation rate"}'

# Chinese market data
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "贵州茅台股价"}'

# Derived metrics (triggers LLM calculation)
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Apple profit margin"}'

# SEC filings
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Tesla 10-K annual report"}'

# Global indicators
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "India GDP growth"}'

# International trade
curl -s -X POST https://finddata.ai/api/query \
  -H "X-API-Key: $FINDDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "China exports to USA 2023"}'

Sources

Source	Best For	Examples
Yahoo Finance	US/global stock prices, ETFs, crypto, forex	"AAPL price", "BTC-USD", "EURUSD"
FRED	US economic data (840K+ series)	"US GDP", "federal funds rate", "CPI"
China Market (Sina+Tencent)	Chinese A-share market data	"贵州茅台股价", "A股行情"
World Bank	Global indicators, 217 economies	"India GDP", "Brazil poverty rate"
SEC EDGAR	US company filings (663K+ companies)	"TSLA 10-K", "NVDA quarterly revenue"
BIS	Central bank rates, financial stability	"global policy rates"
Eurostat	EU economic data, 27 member states	"EU inflation", "Germany unemployment"
BOJ	Bank of Japan, Japanese economy	"Japan TANKAN", "BOJ policy rate"
Our World in Data	Global development, health, environment	"life expectancy", "CO2 emissions"
UN Comtrade	International merchandise trade, 200+ countries	"China exports to USA", "oil trade", "semiconductor imports"

Tool selection is automatic — Voyage AI matches your query to the best tool.

Response Format (v5.1)

The response includes: query result, execution details, data quality issues (if any), and usage info.

Always check success first. Then read data.records for the actual data.

Response Structure

{
  "query": "...",
  "success": true,
  "data": {
    "records": { ... },
    "sources": [ { "tool": "...", "source": "...", "dataType": "...", "latencyMs": 123 } ]
  },
  "derived_metrics": { ... },
  "execution": {
    "planMethod": "fast_path | llm | fallback",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [ { "tool": "...", "params": { ... }, "success": true, "latencyMs": 123 } ],
    "latency_ms": 456
  },
  "issues": [ { "type": "missing | partial | stale | error", "description": "..." } ],
  "usage": { "plan": "free", "latency_ms": 456, "monthly_limit": 100, "cooldown_seconds": 10 }
}

Key Fields

Field	Type	Description
`success`	boolean	Whether data was retrieved successfully
`data.records`	object	The actual data — structure depends on the tool used
`data.sources`	array	Which tools/sources provided the data
`derived_metrics`	object or null	Calculated metrics (profit margin, growth rate, etc.) — only present when calculation was needed
`execution.planMethod`	string	`"fast_path"` (simple query, no LLM), `"llm"` (complex query, LLM planned), or `"fallback"`
`issues`	array or absent	Data quality issues — missing data, partial results, stale data, or errors. Absent when no issues.

Example 1: Simple stock price (fast path)

Query: "Apple stock price"

{
  "query": "Apple stock price",
  "success": true,
  "data": {
    "records": {
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "price": 173.50,
      "currency": "USD",
      "change": -2.15,
      "changePercent": -1.22,
      "volume": 54321000,
      "marketCap": 2700000000000,
      "pe": 28.5,
      "fiftyTwoWeekHigh": 199.62,
      "fiftyTwoWeekLow": 124.17
    },
    "sources": [
      { "tool": "get_stock_price", "source": "yahoo_finance", "dataType": "quote", "latencyMs": 450 }
    ]
  },
  "execution": {
    "planMethod": "fast_path",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [
      { "tool": "get_stock_price", "params": { "ticker": "AAPL" }, "purpose": "Fast-path: direct match", "success": true, "source": "yahoo_finance", "latencyMs": 450 }
    ],
    "latency_ms": 890
  },
  "usage": { "plan": "free", "latency_ms": 890, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract the price: response.data.records.price → 173.50

Example 2: Chinese A-Share (fast path)

Query: "贵州茅台股价"

{
  "query": "贵州茅台股价",
  "success": true,
  "data": {
    "records": {
      "type": "a_share_quote",
      "provider": "sina",
      "records": [
        {
          "code": "600519",
          "market": "SH",
          "name": "贵州茅台",
          "price": 1392.00,
          "open": 1395.00,
          "high": 1403.95,
          "low": 1391.01,
          "volume": 2758646
        }
      ]
    },
    "sources": [
      { "tool": "get_a_share_quote", "source": "china_market", "dataType": "a_share_quote", "latencyMs": 320 }
    ]
  },
  "execution": {
    "planMethod": "fast_path",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [
      { "tool": "get_a_share_quote", "params": { "stock": "贵州茅台" }, "purpose": "Fast-path: direct match", "success": true, "source": "china_market", "latencyMs": 320 }
    ],
    "latency_ms": 680
  },
  "usage": { "plan": "free", "latency_ms": 680, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract the price: response.data.records.records[0].price → 1392.00

Example 3: US economic data (fast path)

Query: "US unemployment rate"

{
  "query": "US unemployment rate",
  "success": true,
  "data": {
    "records": {
      "series_id": "UNRATE",
      "title": "Unemployment Rate",
      "frequency": "Monthly",
      "units": "Percent",
      "observations": [
        { "date": "2024-01-01", "value": "3.7" },
        { "date": "2024-02-01", "value": "3.9" }
      ]
    },
    "sources": [
      { "tool": "get_fred_series", "source": "fred", "dataType": "time_series", "latencyMs": 280 }
    ]
  },
  "execution": {
    "planMethod": "fast_path",
    "plan": { "steps": 1, "requiresCalculation": false },
    "toolsUsed": [
      { "tool": "get_fred_series", "params": { "series_id": "UNRATE" }, "success": true, "source": "fred", "latencyMs": 280 }
    ],
    "latency_ms": 620
  },
  "usage": { "plan": "free", "latency_ms": 620, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract the value: response.data.records.observations[0].value → "3.7"

Example 4: Derived metrics (LLM planning + calculation)

Query: "Apple profit margin"

{
  "query": "Apple profit margin",
  "success": true,
  "data": {
    "records": {
      "type": "financials",
      "company": "APPLE INC",
      "cik": "0000320193",
      "metrics": {
        "Revenues": { "2024-Q3": 85777000000, "2024-Q2": 90753000000 },
        "NetIncomeLoss": { "2024-Q3": 21448000000, "2024-Q2": 23636000000 }
      }
    },
    "sources": [
      { "tool": "get_company_financials", "source": "sec_edgar", "dataType": "financials", "latencyMs": 1200 }
    ]
  },
  "derived_metrics": {
    "profit_margin": {
      "2024-Q3": "25.0%",
      "2024-Q2": "26.0%"
    },
    "calculation": "Net Income / Revenue"
  },
  "execution": {
    "planMethod": "llm",
    "plan": { "steps": 1, "requiresCalculation": true, "calculation": "profit_margin = NetIncomeLoss / Revenues" },
    "toolsUsed": [
      { "tool": "get_company_financials", "params": { "ticker": "AAPL" }, "success": true, "source": "sec_edgar", "latencyMs": 1200 }
    ],
    "latency_ms": 4500
  },
  "usage": { "plan": "free", "latency_ms": 4500, "monthly_limit": 100, "cooldown_seconds": 10 }
}

How to extract derived metrics: response.derived_metrics.profit_margin → { "2024-Q3": "25.0%", ... }

Example 5: Data quality issues

When data cannot be fully retrieved, the issues array explains what happened:

{
  "success": false,
  "issues": [
    {
      "type": "error",
      "description": "Failed to fetch data from get_stock_price: Ticker 'INVALID' not found",
      "tool": "get_stock_price"
    }
  ]
}

Issue types:

"missing" — No data returned at all
"partial" — Some data sources failed, partial results available
"stale" — Data may be outdated (market closed, delayed feed)
"error" — Tool execution failed with an error

Data Extraction Quick Reference

Source	Tool	data.records structure	Price/Value Path
Yahoo Finance	get_stock_price	`{ ticker, name, price, ... }`	`data.records.price`
China Market	get_a_share_quote	`{ type, records: [{ price, ... }] }`	`data.records.records[0].price`
FRED	get_fred_series	`{ series_id, observations: [{ date, value }] }`	`data.records.observations[0].value`
World Bank	get_world_bank_indicator	`{ indicator, records: [{ value, ... }] }`	`data.records.records[0].value`
SEC EDGAR	get_company_financials	`{ company, metrics: { ... } }`	`data.records.metrics`
BIS	get_bis_data	`{ records: [{ value, ... }] }`	`data.records.records[0].value`
Eurostat	get_eurostat_data	`{ records: [{ value, ... }] }`	`data.records.records[0].value`
BOJ	get_boj_data	`{ records: [{ value, ... }] }`	`data.records.records[0].value`
OWID	get_owid_indicator	`{ entities: [{ entity, values: [...] }] }`	`data.records.entities[0].values`
UN Comtrade	get_trade_data	`{ summary: { totalExportsUSD, ... }, records: [...] }`	`data.records.summary.totalExportsUSD`

Parameters

Field	Required	Description
query	Yes	Natural language question (English or Chinese)

Error Handling

When success is false, check the issues array for details. The error field may also be present at the top level.

{
  "success": false,
  "data": { "records": null, "sources": [] },
  "issues": [
    { "type": "error", "description": "Failed to fetch data: API timeout" }
  ],
  "error": "All data sources failed"
}

HTTP Status Codes

Code	Meaning
200	Success (check `success` field for data-level errors)
400	Missing or empty query
401	Invalid or missing API key
429	Rate limit exceeded — check `retry_after_ms` and wait
500	Server error

Version tags

latestvk978vdjs51wj8qmy2th4ba1vmh82whvy