Get Started with the GroundAPI REST API in 5 Minutes

This tutorial will walk you through making your first GroundAPI call from scratch in just 5 minutes.

Step 1: Get Your API Key

Visit groundapi.net and create an account
Go to Dashboard → API Keys → Create New Key
Save your sk_live_xxxxx key somewhere safe

Every new account gets 500 free calls per month — no credit card required.

Step 2: Make Your First Request

Use curl to query the real-time stock price of Moutai:

curl "https://api.groundapi.net/v1/finance/stock?symbol=600519" \
  -H "X-API-Key: sk_live_your_key"

Response:

{
  "success": true,
  "data": {
    "symbol": "600519",
    "name": "贵州茅台",
    "price": 1520.00,
    "change_pct": 1.25
  }
}

Step 3: Call with Python

import requests
 
API_KEY = "sk_live_your_key"
BASE_URL = "https://api.groundapi.net"
headers = {"X-API-Key": API_KEY}
 
# Query weather
resp = requests.get(f"{BASE_URL}/v1/life/weather",
                    params={"city": "Beijing"},
                    headers=headers)
print(resp.json())
 
# Track a package
resp = requests.get(f"{BASE_URL}/v1/life/logistics",
                    params={"number": "SF1234567890", "carrier": "sf"},
                    headers=headers)
print(resp.json())
 
# Web search
resp = requests.get(f"{BASE_URL}/v1/info/search",
                    params={"q": "latest AI Agent news", "count": 5},
                    headers=headers)
print(resp.json())

All Endpoints at a Glance

Finance

API	Method	Path	Key Parameters
Stock Data	GET	`/v1/finance/stock`	`symbol`
Stock Screening	GET	`/v1/finance/stock/screen`	`industry`, `pe_max`, `sort_by`
Market Overview	GET	`/v1/finance/market`	`date`
Fund Data	GET	`/v1/finance/fund`	`code`, `sort_by`

Information

API	Method	Path	Key Parameters
Web Search	GET	`/v1/info/search`	`q`, `engine`, `count`, `recency`
Web Scraping	GET	`/v1/info/scrape`	`url`, `format`
Trending News	GET	`/v1/info/news`	`category`, `limit`, `page`

Life Services

API	Method	Path	Key Parameters
Weather	GET	`/v1/life/weather`	`city`, `forecast`
Logistics Tracking	GET	`/v1/life/logistics`	`number`, `carrier`
IP Geolocation	GET	`/v1/life/ip`	`ip`

Error Handling

All endpoints return a unified format. When an error occurs:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}

Common error codes: 401 (invalid key), 429 (rate limit exceeded), 502 (upstream data source error).

Next Steps

Read the full API Documentation to learn about all parameters and response fields
Try the MCP integration to let your AI assistant call APIs directly
Use the CLI tool pip install groundapi-cli for quick terminal queries

Questions? Email support@wisefuturus.com.