# GroundAPI

> One-stop data layer for AI Agents. A-share finance, web search, weather, logistics.

## MCP Server

Connect your Agent to GroundAPI via MCP:

```json
{
  "mcpServers": {
    "groundapi": {
      "url": "https://mcp.groundapi.net/sse",
      "env": { "GROUNDAPI_KEY": "YOUR_API_KEY" }
    }
  }
}
```

Get API Key: https://groundapi.net/dashboard/keys

## Finance Tools (6)

### finance_stock — Securities Data (Stocks / Indices / ETFs)
- Endpoint: GET /v1/finance/stock
- Params: symbol (e.g. 000001, 000001.SH, 510300; comma-separated for compare), keyword, aspects (default: overview), days (default: 60), period (5/15/30/60/d/w/m), limit
- 13 aspects: overview, profile, quote, kline, technical, financial, flow, holders, management, events, tick, summary, peers
- Examples:
  - Quick look: finance_stock(symbol="600519")
  - Deep dive: finance_stock(symbol="600519", aspects="quote,technical,financial,flow")
  - Index: finance_stock(symbol="000001.SH", aspects="kline,technical")
  - ETF: finance_stock(symbol="510300", aspects="quote")
  - Compare: finance_stock(symbol="601398,601939", aspects="quote")
  - Search: finance_stock(keyword="茅台")

### finance_market — Market Overview
- Endpoint: GET /v1/finance/market
- Params: scope (overview/hot/sectors/ipo/signals, comma-separated), sector (drill-down name), date, limit
- Scopes:
  - overview: 5 major indices + sentiment (limit-up count, seal rate, max streak)
  - hot: limit-up/down/strong/failed-limit/sub-new pools + streak tier stats
  - sectors: concept & industry lists; add sector="AI" for constituents
  - ipo: upcoming IPO calendar
  - signals: multi-streak stocks, high-gain stocks

### finance_screen — Stock Screening
- Endpoint: GET /v1/finance/stock/screen
- Params: industry, concept, pe_min, pe_max, pb_max, min_market_cap, max_market_cap, min_dividend_yield, filter_preset, sort_by, order, limit
- Presets: low_pe_high_div (PE<15 & yield>3%), small_cap_growth (cap<10B), large_cap_stable (cap>50B & PE<20)

### finance_search — Universal Search
- Endpoint: GET /v1/finance/search
- Params: keyword (required), type (stock/concept/sector/etf/index/all), limit
- Coverage: 6,104 stocks + 2,222 concepts + 1,466 sectors + 1,377 ETFs + 613 indices = 11,782 items

### finance_exchange_rate — Exchange Rate
- Endpoint: GET /v1/finance/exchange-rate
- Params: from (source currency, e.g. USD), to (target currency, e.g. CNY)
- Examples: finance_exchange_rate(from_currency="USD", to_currency="CNY")

### finance_gold_price — Gold & Precious Metals
- Endpoint: GET /v1/finance/gold-price
- Returns real-time gold, silver, platinum prices

## Info Tools (5)

### info_search — Web Search
- Endpoint: GET /v1/info/search
- Params: q, count, recency (oneDay/oneWeek/oneMonth/oneYear/noLimit)

### info_scrape — Webpage Scraping
- Endpoint: GET /v1/info/scrape
- Params: url

### info_news — News Headlines
- Endpoint: GET /v1/info/news
- Params: category (finance/general/tech), limit

### info_trending — Trending Topics
- Endpoint: GET /v1/info/trending
- Returns hot search rankings from major Chinese platforms (Weibo, Douyin, Zhihu, etc.)

### info_bulletin — Daily Briefing
- Endpoint: GET /v1/info/bulletin
- Returns daily news bulletin / morning briefing

## Life Tools (7)

### life_weather — Weather
- Endpoint: GET /v1/life/weather
- Params: city, location, forecast

### life_logistics — Package Tracking
- Endpoint: GET /v1/life/logistics
- Params: number, company

### life_ip — IP Geolocation
- Endpoint: GET /v1/life/ip
- Params: address

### life_tax — Income Tax Calculator
- Endpoint: GET /v1/life/tax
- Params: monthly_salary (required), bonus, insurance, special_deduction, additional_deduction
- Calculates Chinese individual income tax (monthly + annual + bonus)

### life_calendar — Calendar Info
- Endpoint: GET /v1/life/calendar
- Params: date (YYYY-MM-DD, defaults to today)
- Returns lunar date, solar terms, holiday status, trading day status

### life_oil_price — Fuel Prices
- Endpoint: GET /v1/life/oil-price
- Params: province (e.g. 北京, optional)
- Returns real-time 92/95/98/diesel fuel prices

### life_traffic — Traffic Restrictions
- Endpoint: GET /v1/life/traffic
- Params: city (required, e.g. 北京)
- Returns vehicle license plate restriction rules

## Authentication

All API requests require X-API-Key header:
```
curl -H "X-API-Key: sk_gapi_xxxxx" "https://api.groundapi.net/v1/finance/stock?symbol=000001"
```

## Links

- Website: https://groundapi.net
- API Docs: https://groundapi.net/documentation/quick-start
- MCP Server: https://mcp.groundapi.net/sse
- Dashboard: https://groundapi.net/dashboard