Deno GDELT Client

Modern, zero-dependency, type-safe GDELT 2.0 DOC API client with a fluent interface. Built specifically for Deno.

[

Features

• Fluent Query Builder: Create complex GDELT queries in a readable and intuitive way.
• Type Safety: TypeScript types for API responses help minimize errors during development.
• Zero Runtime Dependencies: Uses only Deno's built-in tools.
• Request Retry Logic: Configurable retry mechanism for resilience against temporary network failures.
• Article Content Extraction: Intelligently extracts main text, title, and other metadata from article URLs.

Installation

Import the library directly via URL into your project's mod.ts or any file:

import { GdeltClient, GdeltQueryBuilder } from "https://deno.land/x/your_module_name/mod.ts";

(Note: Not yet published on deno.land/x. URL will be updated after publication.)

Usage

Basic Usage

import { GdeltClient } from "./mod.ts";

const client = new GdeltClient();

// Get articles containing 'artificial intelligence' from the last 24 hours
const articlesResponse = await client.getArticles('"artificial intelligence"', { maxrecords: 10 });

for (const article of articlesResponse.articles) {
  console.log(article.title);
}

Fluent Query Builder

import { GdeltClient, GdeltQueryBuilder } from "./mod.ts";

const client = new GdeltClient();

const query = new GdeltQueryBuilder()
  .phrase("climate change")
  .fromCountry("Turkey")
  .withTheme("ENV_CLIMATECHANGE")
  .not("fossil fuels");

// Get timeline data using the constructed query
const timeline = await client.getTimeline("timelinevol", query, { timespan: "14d" });
console.log(timeline.timeline);

Article Content Extraction

import { GdeltClient } from "./mod.ts";

const client = new GdeltClient();
const articleUrl = "https://www.example.com/some-news-article.html";

const content = await client.getArticleContent(articleUrl);

if (content) {
  console.log("Title:", content.title);
  console.log("Excerpt:", content.excerpt);
}

Development

After cloning the project, run tests with:

deno test --allow-net

To run the example usage file:

deno run --allow-net examples/basic_usage.ts