备考内容/Public

Search prediction records and candidates

Search sourced IELTS prediction records and their possible matching questions by record kind, source, exact id, date, month, subject, or keyword. Results preserve source attribution, distinguish dated exam reports from rolling rankings, and include practice targets only for candidates already in the question bank.

Endpoint

POST/api/v1/agent/capabilities/ielts_prediction_search_hits

请求参数

字段	类型	必填	说明
reportIds	number[]	否	Optional exact prediction-record ids returned by an earlier search.
kind	exam_report \| rolling_ranking	否	Prediction record kind: dated exam reports or a rolling ranking snapshot.
limit	number	否	Result limit, 1-12.
offset	number	否	Pagination offset.
query	string	否	Optional recall, venue, source, or candidate-question keyword.
source	string	否	Optional prediction source slug, such as nine-score.
subject	\| listening \| reading \| speaking \| writing	否	Optional IELTS subject filter.
testDate	string	否	Optional exam date in YYYY-MM-DD.
testMonth	string	否	Optional exam month in YYYY-MM; use it instead of one call per day.

调用示例

curl -X POST \
  'https://work.ieltsbuddy.igopx.cn/api/v1/agent/capabilities/ielts_prediction_search_hits' \
  -H 'Content-Type: application/json' \
  --data '{"reportIds":[],"kind":"exam_report","limit":6,"offset":0,"query":"","source":"","subject":"","testDate":"","testMonth":""}'

请求结构

{
  "type": "object",
  "properties": {
    "reportIds": {
      "default": [],
      "description": "Optional exact prediction-record ids returned by an earlier search.",
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "kind": {
      "default": "exam_report",
      "description": "Prediction record kind: dated exam reports or a rolling ranking snapshot.",
      "type": "string",
      "enum": [
        "exam_report",
        "rolling_ranking"
      ]
    },
    "limit": {
      "default": 6,
      "description": "Result limit, 1-12.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "query": {
      "default": "",
      "description": "Optional recall, venue, source, or candidate-question keyword.",
      "type": "string"
    },
    "source": {
      "default": "",
      "description": "Optional prediction source slug, such as nine-score.",
      "type": "string"
    },
    "subject": {
      "default": "",
      "description": "Optional IELTS subject filter.",
      "type": "string",
      "enum": [
        "",
        "listening",
        "reading",
        "speaking",
        "writing"
      ]
    },
    "testDate": {
      "default": "",
      "description": "Optional exam date in YYYY-MM-DD.",
      "type": "string",
      "pattern": "^(?:|\\d{4}-\\d{2}-\\d{2})$"
    },
    "testMonth": {
      "default": "",
      "description": "Optional exam month in YYYY-MM; use it instead of one call per day.",
      "type": "string",
      "pattern": "^(?:|\\d{4}-(?:0[1-9]|1[0-2]))$"
    }
  },
  "required": [
    "reportIds",
    "kind",
    "limit",
    "offset",
    "query",
    "source",
    "subject",
    "testDate",
    "testMonth"
  ],
  "additionalProperties": false
}

统一响应

接口结果位于 data；code 为 0 表示调用成功。

{
  "code": 0,
  "data": {},
  "message": "ok"
}

错误码

40040001请求参数不符合接口契约

40440401接口或目标资源不存在