changedInput schema / properties / maxRecords / description
Previous value: -"Maximum number of articles to return (1–250). 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."New value: +"Maximum number of articles to fetch (1–250); the response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."
changedOutput schema / properties / continuationWindows / description
Previous value: -"The queried window halved, to re-run this query against one pair at a time when maxRecords is at its 250 ceiling. The halves overlap by one second so no article falls through the seam; an article published on that second can come back in both, so de-duplicate by url. Absent unless the ceiling was reached with a window that is both known and wide enough to divide."New value: +"Windows to re-run this query against, one at a time, when more articles are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned article, reaching back to the second it was published, so articles from that second come back again — or, when resuming there cannot reach a new article, one window skipping past that second. Otherwise — maxRecords at its 250 ceiling, or a cut under any other sort — the queried window halved, overlapping by one second so no article falls through the seam. Either way, de-duplicate by url. Absent when no window is known, or none would reach further."
changedOutput schema / properties / error / properties / data / properties / reason / description
Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."
changedOutput schema / properties / error / properties / data / properties / reason / examples
Previous value: -[
- "no_articles",
- "invalid_date_range",
- "invalid_query",
- "gdelt_rate_limited",
- "gdelt_unavailable"
-]New value: +[
+ "invalid_date_range",
+ "invalid_query",
+ "gdelt_rate_limited",
+ "gdelt_unavailable"
+]
changedOutput schema / properties / notice / description
Previous value: -"Disclosure that the maxRecords cap was reached and more articles may exist, naming the route to them — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap."New value: +"Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget."
addedOutput schema / properties / withheldCount
Added value: +{
+ "description": "Articles GDELT returned inside the window that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting articles dropped for falling outside an explicit window. Absent when every in-window article fit.",
+ "type": "number"
+}