🚀 API 文档

时政术语管理系统 RESTful API v1.0

🚀 RESTful API 服务

为开发者提供强大的时政术语查询和匹配API服务，支持术语搜索、文本分析、分类查询等功能。

🔍 术语搜索
🎯 智能匹配
📁 分类查询
📊 统计分析
🧪 在线测试 ⚙️ 安装API 🏠 返回首页
💻 API 调用示例 
// 搜索术语
GET /api/v1/terms/search?q=中国梦
X-API-Key: your_api_key_here

// 术语匹配
POST /api/v1/match
Content-Type: application/json
{
  "text": "实现中华民族伟大复兴的中国梦"
}

📖 API 概述

时政术语管理系统API提供了强大的术语查询和匹配功能，支持开发者轻松集成到自己的应用中。

🎯 核心功能

  • 术语搜索 - 支持关键词搜索、分类筛选、分页查询
  • 术语匹配 - 在文本中智能识别和标注政治术语
  • 分类查询 - 获取术语分类和分类下的术语列表
  • 语种支持 - 支持多语种术语查询

🌐 基础信息

项目 值
API 基础URL http://your-domain.com/api/v1/
协议 HTTP/HTTPS
请求格式 JSON
响应格式 JSON
字符编码 UTF-8
🔔 注意: 所有API调用都需要提供有效的API密钥进行认证。

🔐 认证方式

API使用密钥认证方式，您可以通过以下三种方式提供API密钥：

1. HTTP Header (推荐)

X-API-Key: your_api_key_here

2. Authorization Header

Authorization: Bearer your_api_key_here

3. URL参数

GET /api/v1/terms/search?q=中国梦&api_key=your_api_key_here

🔑 获取API密钥

请联系管理员获取API密钥，或通过管理后台申请。每个密钥都有相应的调用限制和权限配置。

⚠️ 安全提醒: 请妥善保管您的API密钥，不要在客户端代码中暴露密钥。

📚 术语API

GET /api/v1/terms/search

根据关键词搜索术语，支持分类筛选和分页。

请求参数

参数名 类型 必需 说明
q string 必需 搜索关键词
category integer 可选 分类ID筛选
language integer 可选 语种ID筛选
page integer 可选 页码，默认1
limit integer 可选 每页数量，默认20，最大100

请求示例

GET /api/v1/terms/search?q=中国梦&category=1&page=1&limit=10 X-API-Key: ak_demo_1234567890abcdef1234567890abcdef12345678

响应示例

{
  "success": true,
  "message": "术语搜索成功",
  "data": [
    {
      "id": 1,
      "fn_name": "中国梦",
      "fn_orig": "Chinese Dream",
      "fn_def": "实现中华民族伟大复兴的梦想...",
      "fn_word": "中国梦",
      "view_count": 1250,
      "category_name": "核心理念",
      "language_name": "中文",
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-20 15:45:00"
    }
  ],
  "meta": {
    "query": "中国梦",
    "total": 1,
    "page": 1,
    "limit": 10,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  },
  "timestamp": "2024-01-20T15:45:30+08:00",
  "execution_time": "85.23ms"
}

GET /api/v1/terms/{id}

根据ID获取特定术语的详细信息，包括例句。

路径参数

参数名 类型 说明
id integer 术语ID

请求示例

GET /api/v1/terms/1 X-API-Key: ak_demo_1234567890abcdef1234567890abcdef12345678

响应示例

{
  "success": true,
  "message": "术语详情获取成功",
  "data": {
    "id": 1,
    "fn_name": "中国梦",
    "fn_orig": "Chinese Dream",
    "fn_def": "实现中华民族伟大复兴的梦想...",
    "fn_word": "中国梦",
    "view_count": 1251,
    "category_name": "核心理念",
    "language_name": "中文",
    "examples": [
      {
        "chinese_text": "实现中华民族伟大复兴的中国梦。",
        "foreign_text": "Realize the Chinese Dream of great national renewal.",
        "example_order": 1
      }
    ],
    "created_at": "2024-01-15 10:30:00",
    "updated_at": "2024-01-20 15:45:00"
  },
  "timestamp": "2024-01-20T15:45:30+08:00",
  "execution_time": "95.67ms"
}

🎯 术语匹配API

POST /api/v1/match

在指定文本中识别和匹配政治术语，返回匹配结果和位置信息。

请求体参数

参数名 类型 必需 说明
text string 必需 要分析的文本内容
include_context boolean 可选 是否包含上下文，默认true
max_results integer 可选 最大结果数量，默认50，最大100

请求示例

POST /api/v1/match Content-Type: application/json X-API-Key: ak_demo_1234567890abcdef1234567890abcdef12345678 { "text": "实现中华民族伟大复兴的中国梦，必须坚持一带一路建设。", "include_context": true, "max_results": 10 }

响应示例

{
  "success": true,
  "message": "文本术语匹配完成",
  "data": {
    "text": "实现中华民族伟大复兴的中国梦，必须坚持一带一路建设。",
    "matches": [
      {
        "term": {
          "id": 1,
          "fn_name": "中国梦",
          "fn_orig": "Chinese Dream",
          "fn_def": "实现中华民族伟大复兴的梦想...",
          "category_name": "核心理念",
          "language_name": "中文"
        },
        "positions": [
          {
            "start": 11,
            "end": 14,
            "context": "实现中华民族伟大复兴的中国梦，必须坚持"
          }
        ],
        "count": 1
      },
      {
        "term": {
          "id": 2,
          "fn_name": "一带一路",
          "fn_orig": "Belt and Road",
          "fn_def": "丝绸之路经济带和21世纪海上丝绸之路...",
          "category_name": "发展战略",
          "language_name": "中文"
        },
        "positions": [
          {
            "start": 20,
            "end": 24,
            "context": "中国梦，必须坚持一带一路建设。"
          }
        ],
        "count": 1
      }
    ],
    "total_matches": 2,
    "total_occurrences": 2
  },
  "timestamp": "2024-01-20T15:45:30+08:00",
  "execution_time": "120.45ms"
}

📁 分类API

GET /api/v1/categories

获取所有术语分类列表，包含每个分类的术语数量。

请求示例

GET /api/v1/categories X-API-Key: ak_demo_1234567890abcdef1234567890abcdef12345678

响应示例

{
  "success": true,
  "message": "分类列表获取成功",
  "data": [
    {
      "id": 1,
      "name": "核心理念",
      "description": "党和国家的核心理念和价值观",
      "sort_order": 1,
      "term_count": 25,
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-20 15:45:00"
    },
    {
      "id": 2,
      "name": "发展战略",
      "description": "国家发展战略和重大倡议",
      "sort_order": 2,
      "term_count": 18,
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-20 15:45:00"
    }
  ],
  "timestamp": "2024-01-20T15:45:30+08:00",
  "execution_time": "65.23ms"
}

GET /api/v1/categories/{id}/terms

获取指定分类下的术语列表，支持分页。

路径参数

参数名 类型 说明
id integer 分类ID

查询参数

参数名 类型 必需 说明
page integer 可选 页码，默认1
limit integer 可选 每页数量，默认20，最大100

请求示例

GET /api/v1/categories/1/terms?page=1&limit=10 X-API-Key: ak_demo_1234567890abcdef1234567890abcdef12345678

GET /api/v1/languages

获取系统支持的所有语种列表。

请求示例

GET /api/v1/languages X-API-Key: ak_demo_1234567890abcdef1234567890abcdef12345678

❌ 错误码说明

API使用标准HTTP状态码，同时在响应体中提供详细的错误信息。

HTTP状态码

状态码 说明
200 请求成功
400 请求参数错误
401 未授权 - API密钥无效或缺失
403 禁止访问 - 权限不足或密钥被禁用
404 资源不存在
429 调用频率超限
500 服务器内部错误

错误响应格式

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API密钥无效",
    "timestamp": "2024-01-20T15:45:30+08:00"
  }
}

常见错误码

错误码 说明
MISSING_API_KEY 缺少API密钥
INVALID_API_KEY API密钥无效
DISABLED_API_KEY API密钥已被禁用
EXPIRED_API_KEY API密钥已过期
DAILY_LIMIT_EXCEEDED 超出每日调用限制
MONTHLY_LIMIT_EXCEEDED 超出每月调用限制
PERMISSION_DENIED 权限不足
MISSING_PARAMETERS 缺少必需参数

💻 代码示例

JavaScript (Fetch API)

// 搜索术语 const searchTerms = async (query) => { const response = await fetch('/api/v1/terms/search?q=' + encodeURIComponent(query), { headers: { 'X-API-Key': 'your_api_key_here' } }); const data = await response.json(); return data; }; // 术语匹配 const matchTerms = async (text) => { const response = await fetch('/api/v1/match', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': 'your_api_key_here' }, body: JSON.stringify({ text: text }) }); const data = await response.json(); return data; };

PHP (cURL)

<?php // 搜索术语 function searchTerms($query, $apiKey) { $url = '/api/v1/terms/search?q=' . urlencode($query); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'X-API-Key: ' . $apiKey ]); $response = curl_exec($ch); curl_close($ch); return json_decode($response, true); } // 术语匹配 function matchTerms($text, $apiKey) { $url = '/api/v1/match'; $data = json_encode(['text' => $text]); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'X-API-Key: ' . $apiKey ]); $response = curl_exec($ch); curl_close($ch); return json_decode($response, true); } ?>

Python (requests)

import requests import json class TermsAPI: def __init__(self, base_url, api_key): self.base_url = base_url self.headers = {'X-API-Key': api_key} def search_terms(self, query, category=None, page=1, limit=20): """搜索术语""" params = {'q': query, 'page': page, 'limit': limit} if category: params['category'] = category response = requests.get( f'{self.base_url}/terms/search', params=params, headers=self.headers ) return response.json() def match_terms(self, text, include_context=True): """术语匹配""" data = { 'text': text, 'include_context': include_context } response = requests.post( f'{self.base_url}/match', json=data, headers=self.headers ) return response.json() # 使用示例 api = TermsAPI('http://your-domain.com/api/v1', 'your_api_key_here') result = api.search_terms('中国梦') print(result)

© 2024 时政术语管理系统 API v1.0 | 技术支持