Instruction file imported from Pericles-Cloud/pericles (
.cursor/rules/001-application/000-Integrations/002-gdelt-full-text-search-core-standards.mdc). Copyright stays with the author.
<requirement priority="critical">
<description>Use the official endpoint and supported outputs per GDELT docs. Base: https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch</description>
<examples>
<example title="Outputs">
<correct-example title="Article lists and timelines" conditions="Choosing output" expected-result="Supported outputs only" correctness-criteria="Use artlist, artimgonlylist, artimglist, imagecollagelist, timeline(vol|tone), url list"><![CDATA[
// Text-only list https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=artlist&dropdup=true
// Image-only list https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=artimgonlylist&dropdup=true
// Mixed article list https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=artimglist&dropdup=true
// Image collage list https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=imgcollagelist&dropdup=true
// Volume timeline (with smoothing) https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=timeline&outputtype=vol&timelinesmooth=5
// Tone timeline (with smoothing) https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=timeline&outputtype=tone&timelinesmooth=5
// URL CSV list https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=urlonly ]]>
<requirement priority="high">
<description>Construct queries using supported query commands; commands are lowercase and AND’d together.</description>
<examples>
<example title="Query Commands">
<correct-example title="Language, sorting, max rows, dedup, translate" conditions="Building query" expected-result="Valid query parameters" correctness-criteria="Use searchlang/sourcelang, sort/sortby, maxrows, dropdup, trans=googtrans where applicable"><![CDATA[
// Arabic native phrase, mixed list, dedup https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=searchlang:arabic%20%D8%A7%D9%84%D8%AF%D9%88%D9%84%D8%A9%20%D8%A7%D9%84%D8%A5%D8%B3%D9%84%D8%A7%D9%85%D9%8A%D8%A9&output=artimglist&dropdup=true
// Latest coverage for keyword with maxrows https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria%20sortby:date&output=artlist&maxrows=50
// Translate headlines in HTML list outputs https://api.gdeltproject.org/api/v1/search_ftxtsearch/search_ftxtsearch?query=nigeria&output=artlist&trans=googtrans ]]>
<requirement priority="high">
<description>Embedding: use iframe for HTML visualizations; for machine workflows, prefer URL CSV (output=urlonly).</description>
<examples>
<example title="Embedding">
<correct-example title="iframe" conditions="Embedding visualizations" expected-result="Simple iframe embed" correctness-criteria="Uses documented src URL"><![CDATA[
<requirement priority="high">
<description>Internationalization: GDELT searches English translations across 65 languages; support searchlang/sourcelang and optional trans=googtrans for HTML outputs.</description>
</requirement>
<requirement priority="medium">
<description>Error handling: detect and surface HTTP errors; GDELT may return HTML for human outputs—prefer JSON parsing only where applicable or treat as text for diagnostics.</description>
<examples>
<example title="Error normalization">
<correct-example title="Consistent mapping" conditions="Handling errors" expected-result="Status-aware errors" correctness-criteria="Include status, text body excerpt"><![CDATA[
async function fetchGdelt(url) {
const res = await fetch(url, { cache: 'no-store' });
if (!res.ok) {
const body = await res.text();
const err = new Error(gdelt ${res.status});
err.status = res.status;
err.details = body.slice(0, 1000);
throw err;
}
return res.text(); // HTML or CSV depending on output
}
]]>
<requirement priority="medium">
<description>Performance: throttle concurrent requests, add backoff on 429/5xx, and cache stable queries where safe.</description>
</requirement>
<requirement priority="medium">
<description>Security: sanitize user-provided query fragments before constructing URLs; avoid reflecting untrusted HTML.</description>
</requirement>