MCP + REST APIFree Tier Available

YIVA Digital API

Integrate China marketing intelligence directly into your AI assistants, tools, and dashboards. Supports the Model Context Protocol (MCP) for AI-native integration, plus REST, iCal, and Atom endpoints.

MCP Protocol

JSON-RPC 2.0 over HTTP

AI-Friendly

tools/list + tools/call

Free Tier

No API key required

10+ Tools

Free + Premium tiers

Model Context Protocol (MCP)

YIVA Digital exposes a full Model Context Protocol (MCP) endpoint at https://www.yivadigital.com/api/mcp. Any MCP-compatible AI client (Cline, Claude Desktop, OpenClaw, custom agents) can directly access China marketing intelligence, GEO Scores, and calendar data.

Uses JSON-RPC 2.0 over HTTP POST (Streamable HTTP transport). No WebSocket or SSE needed.

Access Tiers

Free7 tools

Preview marketing calendar, articles, case studies. No API key needed. Read-only.

Premium3 tools

Full calendar, GEO Score, brand profiles. Requires a valid API key. Read-only.

Authentication

Pass your API key via the Authorization: Bearer header. Free tools work without any auth.

bash

# List all available tools for your auth level
curl -X POST "https://www.yivadigital.com/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

⚠️ Never use ?key= query parameter — it leaks in server logs and Referer headers.

Call a Free Tool

bash

# Call a free MCP tool (no auth needed)
curl -X POST "https://www.yivadigital.com/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "china_marketing_calendar_stats",
      "arguments": { "year": 2026 }
    }
  }'

Call a Premium Tool

bash

# Call a premium MCP tool (requires API key)
curl -X POST "https://www.yivadigital.com/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer yiva_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "check_brand_geo_score",
      "arguments": { "brandName": "Nike" }
    }
  }'

Python

python

import requests, json

MCP_URL = "https://www.yivadigital.com/api/mcp"
API_KEY = "yiva_your_key_here"  # optional for premium tools

def call_tool(name, args={}):
    payload = {
        "jsonrpc": "2.0", "id": 1,
        "method": "tools/call",
        "params": {"name": name, "arguments": args}
    }
    headers = {"Content-Type": "application/json"}
    if API_KEY and API_KEY != "yiva_your_key_here":
        headers["Authorization"] = f"Bearer {API_KEY}"
    resp = requests.post(MCP_URL, json=payload, headers=headers)
    return resp.json().get("result")

# Free: no key needed
stats = call_tool("china_marketing_calendar_stats", {"year": 2026})
# Premium
geo = call_tool("check_brand_geo_score", {"brandName": "Starbucks"})

JavaScript

javascript

const MCP_URL = "https://www.yivadigital.com/api/mcp";
const API_KEY = "yiva_your_key_here";

async function callTool(name, args = {}) {
  const headers = { "Content-Type": "application/json" };
  if (API_KEY !== "yiva_your_key_here")
    headers["Authorization"] = `Bearer ${API_KEY}`;
  const res = await fetch(MCP_URL, {
    method: "POST", headers,
    body: JSON.stringify({
      jsonrpc: "2.0", id: 1,
      method: "tools/call",
      params: { name, arguments: args },
    }),
  });
  return (await res.json()).result;
}