Imported from tiangong-ai/agent-skills (gdelt-web-ngrams-search/SKILL.md). Install upstream with npx skills add tiangong-ai/agent-skills --skill gdelt-web-ngrams-search. Copyright stays with the author.

GDELT Web NGrams Search

Use CLI-owned gdelt.web-ngrams; this Skill selects and explains the operation, without a second download, search, or join implementation.

Before running

1. Read references/tiangong-data-requirement.json.
2. Use the caller- or workspace-resolved stable CLI for both describe and run. Confirm that the capability and required operation contract majors exist. If unavailable, report the missing capability; do not assume every package with the same CLI version contains an unreleased candidate extension.
3. Read current Discovery Metadata and input/output schemas:

tiangong-ai data describe gdelt.web-ngrams --json

Prepare and run

Select one explicit published UTC minute and literal phrases accepted by the current input schema. Replace the version placeholders from that same describe response. This historical minute is a documented sample, not a current-news default:

{
  "schemaVersion": "tiangong.data.run-request.v1",
  "capabilityId": "gdelt.web-ngrams",
  "capabilityVersion": "<describe.manifest.capabilityVersion>",
  "operationId": "search",
  "operationVersion": "<describe.manifest.operations[0].operationVersion>",
  "input": {
    "fileTimestamp": "2026-06-30T20:16:00Z",
    "phrases": ["disease", "diseases"],
    "match": "any"
  }
}

tiangong-ai data run gdelt.web-ngrams search \
  --input /absolute/path/to/request.json --json

Keep data, contract, summary, warnings, errors, and receipt together.

Selection and interpretation

• Choose this operation for literal topic-to-article discovery. Switching from DOC is an explicit change of retrieval method, not an equivalent retry: do not translate DOC operators into phrases or invent DOC timelines.
• Choose GKG for extracted themes/entities/document tone, Events for coded events, and Mentions for event-to-document linkage. Use only the layers the question needs; this Skill does not automatically invoke or join them.
• A successful call covers only the requested file pair, not a complete day or all monitored news. The caller owns range enumeration and must retain missing minutes. Do not present a handful of available minutes as full-window coverage.
• Distinguish successful zero matches from blocked file acquisition and partial validation. For truncation, report returned versus matched versus omitted records and resolve the limit before claiming exhaustive retrieval.
• Identify documents by (fileTimestamp, documentId). Matched phrases indicate presence, not counts: overlapping quadgrams must not be summed into phrase frequencies. Article links and optional unvalidated image-reference text are provider metadata, not downloaded or verified content.
• Full-text retrieval, longitudinal aggregation, persistence, and research evidence admission remain with the caller or Auto Research.