gdelt-ts-client 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +455 -0
- package/dist/client.d.ts +228 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +478 -0
- package/dist/client.js.map +1 -0
- package/dist/constants/index.d.ts +184 -0
- package/dist/constants/index.d.ts.map +1 -0
- package/dist/constants/index.js +193 -0
- package/dist/constants/index.js.map +1 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +40 -0
- package/dist/index.js.map +1 -0
- package/dist/interfaces/api-parameters.d.ts +201 -0
- package/dist/interfaces/api-parameters.d.ts.map +1 -0
- package/dist/interfaces/api-parameters.js +3 -0
- package/dist/interfaces/api-parameters.js.map +1 -0
- package/dist/interfaces/api-responses.d.ts +258 -0
- package/dist/interfaces/api-responses.d.ts.map +1 -0
- package/dist/interfaces/api-responses.js +6 -0
- package/dist/interfaces/api-responses.js.map +1 -0
- package/dist/types/enhanced-types.d.ts +227 -0
- package/dist/types/enhanced-types.d.ts.map +1 -0
- package/dist/types/enhanced-types.js +89 -0
- package/dist/types/enhanced-types.js.map +1 -0
- package/dist/types/query-builder.d.ts +252 -0
- package/dist/types/query-builder.d.ts.map +1 -0
- package/dist/types/query-builder.js +458 -0
- package/dist/types/query-builder.js.map +1 -0
- package/dist/types/type-guards.d.ts +110 -0
- package/dist/types/type-guards.d.ts.map +1 -0
- package/dist/types/type-guards.js +271 -0
- package/dist/types/type-guards.js.map +1 -0
- package/package.json +54 -0
package/README.md
ADDED
|
@@ -0,0 +1,455 @@
|
|
|
1
|
+
# GDELT TypeScript Client
|
|
2
|
+
|
|
3
|
+
A comprehensive TypeScript client for the GDELT API that provides strongly-typed access to global news data, events, and media analysis. This library supports both TypeScript and JavaScript projects with full type safety and intelligent code completion.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Complete API Coverage**: Access all GDELT API endpoints including articles, images, timelines, tone analysis, and more
|
|
8
|
+
- **Type Safety**: Comprehensive TypeScript definitions for all parameters, responses, and configuration options
|
|
9
|
+
- **Query Building**: Fluent API for constructing complex search queries with type safety
|
|
10
|
+
- **Validation**: Built-in parameter validation with helpful error messages
|
|
11
|
+
- **Retry Logic**: Configurable retry mechanism for handling transient network errors
|
|
12
|
+
- **Response Validation**: Type guards and validation for ensuring data integrity
|
|
13
|
+
- **Method Overloads**: Simplified method signatures for common use cases
|
|
14
|
+
- **JavaScript Compatible**: Works in both TypeScript and JavaScript environments
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install gdelt-ts-client
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Quick Start
|
|
23
|
+
|
|
24
|
+
### TypeScript Example
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
import { GdeltClient, TimespanUnit } from 'gdelt-ts-client';
|
|
28
|
+
|
|
29
|
+
const client = new GdeltClient();
|
|
30
|
+
|
|
31
|
+
async function getRecentNews() {
|
|
32
|
+
const response = await client.getArticles({
|
|
33
|
+
query: 'climate change',
|
|
34
|
+
timespan: '1d',
|
|
35
|
+
maxrecords: 10
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
console.log(`Found ${response.count} articles`);
|
|
39
|
+
response.articles.forEach(article => {
|
|
40
|
+
console.log(`${article.title} (${article.domain})`);
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
getRecentNews();
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### JavaScript Example
|
|
48
|
+
|
|
49
|
+
```javascript
|
|
50
|
+
const { GdeltClient } = require('gdelt-ts-client');
|
|
51
|
+
|
|
52
|
+
const client = new GdeltClient();
|
|
53
|
+
|
|
54
|
+
async function getRecentNews() {
|
|
55
|
+
const response = await client.getArticles({
|
|
56
|
+
query: 'technology',
|
|
57
|
+
timespan: '1d',
|
|
58
|
+
maxrecords: 10
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
console.log(`Found ${response.count} articles`);
|
|
62
|
+
response.articles.forEach(article => {
|
|
63
|
+
console.log(`${article.title} (${article.domain})`);
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
getRecentNews();
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## API Reference
|
|
71
|
+
|
|
72
|
+
### Client Configuration
|
|
73
|
+
|
|
74
|
+
Create a client with optional configuration:
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
const client = new GdeltClient({
|
|
78
|
+
timeout: 30000, // Request timeout in milliseconds
|
|
79
|
+
retry: true, // Enable retry on failures
|
|
80
|
+
maxRetries: 3, // Maximum number of retries
|
|
81
|
+
retryDelay: 1000, // Delay between retries in milliseconds
|
|
82
|
+
defaultFormat: 'json' // Default response format
|
|
83
|
+
});
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Core Methods
|
|
87
|
+
8
|
|
88
|
+
#### Article Search
|
|
89
|
+
|
|
90
|
+
Get articles matching your query:
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
// Simple query
|
|
94
|
+
const articles = await client.getArticles('climate change');
|
|
95
|
+
|
|
96
|
+
// With options
|
|
97
|
+
const articles = await client.getArticles('climate change', {
|
|
98
|
+
timespan: '1w',
|
|
99
|
+
maxrecords: 50
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
// Full parameter object
|
|
103
|
+
const articles = await client.getArticles({
|
|
104
|
+
query: 'climate change',
|
|
105
|
+
timespan: '1w',
|
|
106
|
+
maxrecords: 50,
|
|
107
|
+
sort: 'datedesc'
|
|
108
|
+
});
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
#### Image Search
|
|
112
|
+
|
|
113
|
+
Find images related to your query:
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
// Simple image search
|
|
117
|
+
const images = await client.getImages('natural disasters');
|
|
118
|
+
|
|
119
|
+
// With filtering
|
|
120
|
+
const images = await client.getImages('natural disasters', {
|
|
121
|
+
timespan: '1d',
|
|
122
|
+
maxrecords: 20
|
|
123
|
+
});
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
#### Timeline Analysis
|
|
127
|
+
|
|
128
|
+
Get timeline data for coverage volume:
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
// Simple timeline
|
|
132
|
+
const timeline = await client.getTimeline('covid-19', '1m');
|
|
133
|
+
|
|
134
|
+
// With smoothing
|
|
135
|
+
const timeline = await client.getTimeline('covid-19', {
|
|
136
|
+
timespan: '1m',
|
|
137
|
+
timelinesmooth: 7
|
|
138
|
+
});
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
#### Tone Analysis
|
|
142
|
+
|
|
143
|
+
Analyze emotional tone of coverage:
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
const toneChart = await client.getToneChart('election 2024');
|
|
147
|
+
|
|
148
|
+
// Process tone distribution
|
|
149
|
+
toneChart.tonechart.forEach(bin => {
|
|
150
|
+
console.log(`Tone ${bin.bin}: ${bin.count} articles`);
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Enhanced Query Building
|
|
155
|
+
|
|
156
|
+
Use the fluent query builder for complex searches:
|
|
157
|
+
|
|
158
|
+
```typescript
|
|
159
|
+
// Create a complex query
|
|
160
|
+
const query = client.query()
|
|
161
|
+
.phrase('climate change')
|
|
162
|
+
.fromCountry('us')
|
|
163
|
+
.withPositiveTone(3)
|
|
164
|
+
.not('opinion')
|
|
165
|
+
.build();
|
|
166
|
+
|
|
167
|
+
const articles = await client.getArticles(query);
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
#### Article-specific Query Builder
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
const articleQuery = client.articleQuery()
|
|
174
|
+
.breakingNews()
|
|
175
|
+
.fromDomain('cnn.com')
|
|
176
|
+
.build();
|
|
177
|
+
|
|
178
|
+
const articles = await client.getArticles(articleQuery);
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
#### Image-specific Query Builder
|
|
182
|
+
|
|
183
|
+
```typescript
|
|
184
|
+
const imageQuery = client.imageQuery()
|
|
185
|
+
.disasters()
|
|
186
|
+
.withNovelImages()
|
|
187
|
+
.build();
|
|
188
|
+
|
|
189
|
+
const images = await client.getImages(imageQuery);
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Query Validation
|
|
193
|
+
|
|
194
|
+
Validate queries before execution:
|
|
195
|
+
|
|
196
|
+
```typescript
|
|
197
|
+
const validation = client.validateQuery('climate change AND (weather OR temperature)');
|
|
198
|
+
|
|
199
|
+
if (!validation.valid) {
|
|
200
|
+
console.error('Query errors:', validation.errors);
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// Get optimization suggestions
|
|
204
|
+
const suggestions = client.getQueryOptimizations('very complex query here');
|
|
205
|
+
suggestions.forEach(suggestion => {
|
|
206
|
+
console.log('Suggestion:', suggestion);
|
|
207
|
+
});
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Available Methods
|
|
211
|
+
|
|
212
|
+
| Method | Description |
|
|
213
|
+
|--------|-------------|
|
|
214
|
+
| `getArticles()` | Search for news articles |
|
|
215
|
+
| `getImages()` | Search for images and photos |
|
|
216
|
+
| `getTimeline()` | Get timeline of coverage volume |
|
|
217
|
+
| `getTimelineWithArticles()` | Get timeline with article details |
|
|
218
|
+
| `getTimelineByLanguage()` | Get timeline broken down by language |
|
|
219
|
+
| `getTimelineByCountry()` | Get timeline broken down by country |
|
|
220
|
+
| `getTimelineTone()` | Get timeline of average tone |
|
|
221
|
+
| `getToneChart()` | Get tone distribution chart |
|
|
222
|
+
| `getImageTagCloud()` | Get word cloud of image tags |
|
|
223
|
+
| `getImageWebTagCloud()` | Get word cloud of web image tags |
|
|
224
|
+
|
|
225
|
+
### Query Parameters
|
|
226
|
+
|
|
227
|
+
All methods support these parameters:
|
|
228
|
+
|
|
229
|
+
| Parameter | Type | Description |
|
|
230
|
+
|-----------|------|-------------|
|
|
231
|
+
| `query` | string | Search query (required) |
|
|
232
|
+
| `timespan` | string | Time period (e.g., '1d', '1w', '1m') |
|
|
233
|
+
| `startdatetime` | string | Start date (YYYYMMDDHHMMSS format) |
|
|
234
|
+
| `enddatetime` | string | End date (YYYYMMDDHHMMSS format) |
|
|
235
|
+
| `maxrecords` | number | Maximum results (1-250, default 75) |
|
|
236
|
+
| `sort` | string | Sort order ('datedesc', 'dateasc', 'tonedesc', 'toneasc') |
|
|
237
|
+
| `timelinesmooth` | number | Timeline smoothing (1-30) |
|
|
238
|
+
| `format` | string | Response format ('json', 'csv', 'html') |
|
|
239
|
+
|
|
240
|
+
### Query Operators
|
|
241
|
+
|
|
242
|
+
Build powerful queries using GDELT operators:
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
// Domain filtering
|
|
246
|
+
const query = 'climate change domain:cnn.com';
|
|
247
|
+
|
|
248
|
+
// Country filtering
|
|
249
|
+
const query = 'elections sourcecountry:unitedstates';
|
|
250
|
+
|
|
251
|
+
// Language filtering
|
|
252
|
+
const query = 'brexit sourcelang:english';
|
|
253
|
+
|
|
254
|
+
// Tone filtering
|
|
255
|
+
const query = 'economy tone>5'; // Positive tone articles
|
|
256
|
+
|
|
257
|
+
// Theme filtering
|
|
258
|
+
const query = 'theme:ENV_CLIMATE';
|
|
259
|
+
|
|
260
|
+
// Image filtering
|
|
261
|
+
const query = 'imagetag:"flood"';
|
|
262
|
+
|
|
263
|
+
// Complex combinations
|
|
264
|
+
const query = 'climate change AND sourcecountry:germany AND tone>2';
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### Error Handling
|
|
268
|
+
|
|
269
|
+
The client provides comprehensive error handling:
|
|
270
|
+
|
|
271
|
+
```typescript
|
|
272
|
+
try {
|
|
273
|
+
const response = await client.getArticles({
|
|
274
|
+
query: 'climate change',
|
|
275
|
+
maxrecords: 300 // Invalid: exceeds 250 limit
|
|
276
|
+
});
|
|
277
|
+
} catch (error) {
|
|
278
|
+
if (error instanceof Error) {
|
|
279
|
+
console.error('Error:', error.message);
|
|
280
|
+
// Handle specific error types
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### Type Safety
|
|
286
|
+
|
|
287
|
+
Take advantage of full TypeScript support:
|
|
288
|
+
|
|
289
|
+
```typescript
|
|
290
|
+
import {
|
|
291
|
+
GdeltClient,
|
|
292
|
+
IArticleListResponse,
|
|
293
|
+
IImageCollageResponse,
|
|
294
|
+
TimespanUnit,
|
|
295
|
+
Mode,
|
|
296
|
+
Format
|
|
297
|
+
} from 'gdelt-ts-client';
|
|
298
|
+
|
|
299
|
+
// Strongly typed responses
|
|
300
|
+
const articles: IArticleListResponse = await client.getArticles('query');
|
|
301
|
+
const images: IImageCollageResponse = await client.getImages('query');
|
|
302
|
+
|
|
303
|
+
// Type-safe constants
|
|
304
|
+
const timespan = client.createTimespan(1, TimespanUnit.DAYS);
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## Advanced Usage
|
|
308
|
+
|
|
309
|
+
### Custom Configuration
|
|
310
|
+
|
|
311
|
+
```typescript
|
|
312
|
+
const client = new GdeltClient({
|
|
313
|
+
timeout: 60000,
|
|
314
|
+
retry: true,
|
|
315
|
+
maxRetries: 5,
|
|
316
|
+
retryDelay: 2000,
|
|
317
|
+
defaultFormat: Format.JSON
|
|
318
|
+
});
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
### Complex Query Building
|
|
322
|
+
|
|
323
|
+
```typescript
|
|
324
|
+
const complexQuery = client.query()
|
|
325
|
+
.phrase('artificial intelligence')
|
|
326
|
+
.anyOf('machine learning', 'deep learning', 'neural networks')
|
|
327
|
+
.fromCountry('us')
|
|
328
|
+
.withTheme('SCI_TECH')
|
|
329
|
+
.withPositiveTone(3)
|
|
330
|
+
.not('opinion')
|
|
331
|
+
.group()
|
|
332
|
+
.build();
|
|
333
|
+
|
|
334
|
+
const response = await client.getArticles(complexQuery, {
|
|
335
|
+
timespan: '1w',
|
|
336
|
+
maxrecords: 100,
|
|
337
|
+
sort: 'datedesc'
|
|
338
|
+
});
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
### Response Processing
|
|
342
|
+
|
|
343
|
+
```typescript
|
|
344
|
+
const response = await client.getArticles('climate change');
|
|
345
|
+
|
|
346
|
+
// Process articles with null safety
|
|
347
|
+
response.articles.forEach(article => {
|
|
348
|
+
if (article.title && article.url) {
|
|
349
|
+
console.log(`${article.title}`);
|
|
350
|
+
console.log(`URL: ${article.url}`);
|
|
351
|
+
console.log(`Tone: ${article.tone?.toFixed(2) ?? 'N/A'}`);
|
|
352
|
+
console.log(`Date: ${article.seendate}`);
|
|
353
|
+
}
|
|
354
|
+
});
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
### Timeline Analysis
|
|
358
|
+
|
|
359
|
+
```typescript
|
|
360
|
+
const timeline = await client.getTimeline('covid-19', '1m');
|
|
361
|
+
|
|
362
|
+
if (timeline.timeline && timeline.timeline.length > 0) {
|
|
363
|
+
timeline.timeline.forEach(point => {
|
|
364
|
+
if (point && point.date && typeof point.value === 'number') {
|
|
365
|
+
console.log(`${point.date}: ${point.value.toFixed(4)}%`);
|
|
366
|
+
}
|
|
367
|
+
});
|
|
368
|
+
}
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
## Examples
|
|
372
|
+
|
|
373
|
+
### Basic News Search
|
|
374
|
+
|
|
375
|
+
```typescript
|
|
376
|
+
import { GdeltClient } from 'gdelt-ts-client';
|
|
377
|
+
|
|
378
|
+
const client = new GdeltClient();
|
|
379
|
+
|
|
380
|
+
async function searchNews() {
|
|
381
|
+
const articles = await client.getArticles({
|
|
382
|
+
query: 'renewable energy',
|
|
383
|
+
timespan: '1d',
|
|
384
|
+
maxrecords: 20
|
|
385
|
+
});
|
|
386
|
+
|
|
387
|
+
console.log(`Found ${articles.count} articles about renewable energy`);
|
|
388
|
+
|
|
389
|
+
articles.articles.forEach((article, index) => {
|
|
390
|
+
console.log(`${index + 1}. ${article.title}`);
|
|
391
|
+
console.log(` Source: ${article.domain}`);
|
|
392
|
+
console.log(` Date: ${article.seendate}`);
|
|
393
|
+
console.log(` Tone: ${article.tone?.toFixed(2) ?? 'N/A'}`);
|
|
394
|
+
});
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
searchNews();
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
### Image Analysis
|
|
401
|
+
|
|
402
|
+
```typescript
|
|
403
|
+
async function analyzeImages() {
|
|
404
|
+
const images = await client.getImages({
|
|
405
|
+
query: 'imagetag:"protest"',
|
|
406
|
+
timespan: '1w',
|
|
407
|
+
maxrecords: 10
|
|
408
|
+
});
|
|
409
|
+
|
|
410
|
+
console.log(`Found ${images.count} protest images`);
|
|
411
|
+
|
|
412
|
+
images.images.forEach((image, index) => {
|
|
413
|
+
console.log(`${index + 1}. ${image.url}`);
|
|
414
|
+
console.log(` Article: ${image.articleurl}`);
|
|
415
|
+
console.log(` Tags: ${image.tags?.join(', ') ?? 'None'}`);
|
|
416
|
+
});
|
|
417
|
+
}
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
### Tone Distribution Analysis
|
|
421
|
+
|
|
422
|
+
```typescript
|
|
423
|
+
async function analyzeTone() {
|
|
424
|
+
const toneChart = await client.getToneChart({
|
|
425
|
+
query: 'cryptocurrency',
|
|
426
|
+
timespan: '1w'
|
|
427
|
+
});
|
|
428
|
+
|
|
429
|
+
console.log('Tone distribution for cryptocurrency coverage:');
|
|
430
|
+
|
|
431
|
+
const totalArticles = toneChart.tonechart.reduce((sum, bin) => sum + bin.count, 0);
|
|
432
|
+
|
|
433
|
+
toneChart.tonechart.forEach(bin => {
|
|
434
|
+
const percentage = (bin.count / totalArticles * 100).toFixed(1);
|
|
435
|
+
console.log(`Tone ${bin.bin}: ${bin.count} articles (${percentage}%)`);
|
|
436
|
+
});
|
|
437
|
+
}
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
## Requirements
|
|
441
|
+
|
|
442
|
+
- Node.js >= 18.0.0
|
|
443
|
+
- TypeScript >= 5.0.0 (for TypeScript projects)
|
|
444
|
+
|
|
445
|
+
## License
|
|
446
|
+
|
|
447
|
+
MIT License - see LICENSE file for details.
|
|
448
|
+
|
|
449
|
+
## Contributing
|
|
450
|
+
|
|
451
|
+
Contributions are welcome. Please ensure all tests pass and maintain code coverage above 90%.
|
|
452
|
+
|
|
453
|
+
## Support
|
|
454
|
+
|
|
455
|
+
For bug reports and feature requests, please use the GitHub issues page.
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
import { ETimespanUnit } from './constants';
|
|
2
|
+
import { IGdeltApiBaseParams, IGdeltClientConfig } from './interfaces/api-parameters';
|
|
3
|
+
import { IArticleListResponse, IImageCollageResponse, ITimelineResponse, ITimelineBreakdownResponse, IToneChartResponse, IWordCloudResponse } from './interfaces/api-responses';
|
|
4
|
+
import { TimespanUnitType, TimespanString, ComplexQuery } from './types/enhanced-types';
|
|
5
|
+
import { QueryBuilder, ArticleQueryBuilder, ImageQueryBuilder } from './types/query-builder';
|
|
6
|
+
/**
|
|
7
|
+
* GDELT API Client
|
|
8
|
+
* A strongly-typed client for interacting with the GDELT API
|
|
9
|
+
*/
|
|
10
|
+
export declare class GdeltClient {
|
|
11
|
+
/**
|
|
12
|
+
* The Axios instance used for making HTTP requests
|
|
13
|
+
* @private
|
|
14
|
+
*/
|
|
15
|
+
private readonly _axiosInstance;
|
|
16
|
+
/**
|
|
17
|
+
* The base URL for the GDELT API
|
|
18
|
+
* @private
|
|
19
|
+
*/
|
|
20
|
+
private readonly _baseUrl;
|
|
21
|
+
/**
|
|
22
|
+
* The default format for API responses
|
|
23
|
+
* @private
|
|
24
|
+
*/
|
|
25
|
+
private readonly _defaultFormat;
|
|
26
|
+
/**
|
|
27
|
+
* Whether to retry failed requests
|
|
28
|
+
* @private
|
|
29
|
+
*/
|
|
30
|
+
private readonly _retry;
|
|
31
|
+
/**
|
|
32
|
+
* The maximum number of retries for failed requests
|
|
33
|
+
* @private
|
|
34
|
+
*/
|
|
35
|
+
private readonly _maxRetries;
|
|
36
|
+
/**
|
|
37
|
+
* The delay between retries in milliseconds
|
|
38
|
+
* @private
|
|
39
|
+
*/
|
|
40
|
+
private readonly _retryDelay;
|
|
41
|
+
/**
|
|
42
|
+
* Creates a new GDELT API client
|
|
43
|
+
* @param config - The client configuration
|
|
44
|
+
*/
|
|
45
|
+
constructor(config?: IGdeltClientConfig);
|
|
46
|
+
/**
|
|
47
|
+
* Creates a timespan string from a timespan object
|
|
48
|
+
* @param timespan - The timespan object
|
|
49
|
+
* @returns The timespan string
|
|
50
|
+
* @private
|
|
51
|
+
*/
|
|
52
|
+
private _createTimespanString;
|
|
53
|
+
/**
|
|
54
|
+
* Validates API parameters
|
|
55
|
+
* @param params - The API parameters to validate
|
|
56
|
+
* @private
|
|
57
|
+
*/
|
|
58
|
+
private _validateParams;
|
|
59
|
+
/**
|
|
60
|
+
* Transforms API response data without mutating the original
|
|
61
|
+
* @param data - The original response data
|
|
62
|
+
* @returns The transformed response data
|
|
63
|
+
* @private
|
|
64
|
+
*/
|
|
65
|
+
private _transformResponse;
|
|
66
|
+
/**
|
|
67
|
+
* Builds the query parameters for the API request
|
|
68
|
+
* @param params - The API parameters
|
|
69
|
+
* @returns The query parameters object
|
|
70
|
+
* @private
|
|
71
|
+
*/
|
|
72
|
+
private _buildQueryParams;
|
|
73
|
+
/**
|
|
74
|
+
* Makes a request to the GDELT API
|
|
75
|
+
* @param params - The API parameters
|
|
76
|
+
* @returns A promise that resolves to the API response
|
|
77
|
+
* @private
|
|
78
|
+
*/
|
|
79
|
+
private _makeRequest;
|
|
80
|
+
/**
|
|
81
|
+
* Gets a list of articles that match the query
|
|
82
|
+
* @param params - The API parameters
|
|
83
|
+
* @returns A promise that resolves to the article list response
|
|
84
|
+
*/
|
|
85
|
+
getArticles(params: IGdeltApiBaseParams): Promise<IArticleListResponse>;
|
|
86
|
+
/**
|
|
87
|
+
* Gets a list of articles that match the query (simplified overload)
|
|
88
|
+
* @param query - The search query string
|
|
89
|
+
* @param options - Optional parameters
|
|
90
|
+
* @returns A promise that resolves to the article list response
|
|
91
|
+
*/
|
|
92
|
+
getArticles(query: string | ComplexQuery, options?: Partial<IGdeltApiBaseParams>): Promise<IArticleListResponse>;
|
|
93
|
+
/**
|
|
94
|
+
* Gets a list of images that match the query
|
|
95
|
+
* @param params - The API parameters
|
|
96
|
+
* @returns A promise that resolves to the image collage response
|
|
97
|
+
*/
|
|
98
|
+
getImages(params: IGdeltApiBaseParams): Promise<IImageCollageResponse>;
|
|
99
|
+
/**
|
|
100
|
+
* Gets a list of images that match the query (simplified overload)
|
|
101
|
+
* @param query - The search query string
|
|
102
|
+
* @param options - Optional parameters
|
|
103
|
+
* @returns A promise that resolves to the image collage response
|
|
104
|
+
*/
|
|
105
|
+
getImages(query: string | ComplexQuery, options?: Partial<IGdeltApiBaseParams>): Promise<IImageCollageResponse>;
|
|
106
|
+
/**
|
|
107
|
+
* Gets a timeline of news coverage volume that matches the query
|
|
108
|
+
* @param params - The API parameters
|
|
109
|
+
* @returns A promise that resolves to the timeline response
|
|
110
|
+
*/
|
|
111
|
+
getTimeline(params: IGdeltApiBaseParams): Promise<ITimelineResponse>;
|
|
112
|
+
/**
|
|
113
|
+
* Gets a timeline of news coverage volume that matches the query (simplified overload)
|
|
114
|
+
* @param query - The search query string
|
|
115
|
+
* @param timespanOrOptions - Timespan string or full options object
|
|
116
|
+
* @returns A promise that resolves to the timeline response
|
|
117
|
+
*/
|
|
118
|
+
getTimeline(query: string | ComplexQuery, timespanOrOptions?: TimespanString | Partial<IGdeltApiBaseParams>): Promise<ITimelineResponse>;
|
|
119
|
+
/**
|
|
120
|
+
* Gets a timeline of news coverage volume with article info that matches the query
|
|
121
|
+
* @param params - The API parameters
|
|
122
|
+
* @returns A promise that resolves to the timeline response
|
|
123
|
+
*/
|
|
124
|
+
getTimelineWithArticles(params: IGdeltApiBaseParams): Promise<ITimelineResponse>;
|
|
125
|
+
/**
|
|
126
|
+
* Gets a timeline of news coverage volume with article info that matches the query (simplified overload)
|
|
127
|
+
* @param query - The search query string
|
|
128
|
+
* @param options - Optional parameters
|
|
129
|
+
* @returns A promise that resolves to the timeline response
|
|
130
|
+
*/
|
|
131
|
+
getTimelineWithArticles(query: string | ComplexQuery, options?: Partial<IGdeltApiBaseParams>): Promise<ITimelineResponse>;
|
|
132
|
+
/**
|
|
133
|
+
* Gets a timeline of news coverage volume broken down by language that matches the query
|
|
134
|
+
* @param params - The API parameters
|
|
135
|
+
* @returns A promise that resolves to the timeline breakdown response
|
|
136
|
+
*/
|
|
137
|
+
getTimelineByLanguage(params: IGdeltApiBaseParams): Promise<ITimelineBreakdownResponse>;
|
|
138
|
+
/**
|
|
139
|
+
* Gets a timeline of news coverage volume broken down by source country that matches the query
|
|
140
|
+
* @param params - The API parameters
|
|
141
|
+
* @returns A promise that resolves to the timeline breakdown response
|
|
142
|
+
*/
|
|
143
|
+
getTimelineByCountry(params: IGdeltApiBaseParams): Promise<ITimelineBreakdownResponse>;
|
|
144
|
+
/**
|
|
145
|
+
* Gets a timeline of average tone of news coverage that matches the query
|
|
146
|
+
* @param params - The API parameters
|
|
147
|
+
* @returns A promise that resolves to the timeline response
|
|
148
|
+
*/
|
|
149
|
+
getTimelineTone(params: IGdeltApiBaseParams): Promise<ITimelineResponse>;
|
|
150
|
+
/**
|
|
151
|
+
* Gets a timeline of average tone of news coverage that matches the query (simplified overload)
|
|
152
|
+
* @param query - The search query string
|
|
153
|
+
* @param options - Optional parameters
|
|
154
|
+
* @returns A promise that resolves to the timeline response
|
|
155
|
+
*/
|
|
156
|
+
getTimelineTone(query: string | ComplexQuery, options?: Partial<IGdeltApiBaseParams>): Promise<ITimelineResponse>;
|
|
157
|
+
/**
|
|
158
|
+
* Gets a tone chart of news coverage that matches the query
|
|
159
|
+
* @param params - The API parameters
|
|
160
|
+
* @returns A promise that resolves to the tone chart response
|
|
161
|
+
*/
|
|
162
|
+
getToneChart(params: IGdeltApiBaseParams): Promise<IToneChartResponse>;
|
|
163
|
+
/**
|
|
164
|
+
* Gets a tone chart of news coverage that matches the query (simplified overload)
|
|
165
|
+
* @param query - The search query string
|
|
166
|
+
* @param options - Optional parameters
|
|
167
|
+
* @returns A promise that resolves to the tone chart response
|
|
168
|
+
*/
|
|
169
|
+
getToneChart(query: string | ComplexQuery, options?: Partial<IGdeltApiBaseParams>): Promise<IToneChartResponse>;
|
|
170
|
+
/**
|
|
171
|
+
* Gets a word cloud of image tags that match the query
|
|
172
|
+
* @param params - The API parameters
|
|
173
|
+
* @returns A promise that resolves to the word cloud response
|
|
174
|
+
*/
|
|
175
|
+
getImageTagCloud(params: IGdeltApiBaseParams): Promise<IWordCloudResponse>;
|
|
176
|
+
/**
|
|
177
|
+
* Gets a word cloud of image web tags that match the query
|
|
178
|
+
* @param params - The API parameters
|
|
179
|
+
* @returns A promise that resolves to the word cloud response
|
|
180
|
+
*/
|
|
181
|
+
getImageWebTagCloud(params: IGdeltApiBaseParams): Promise<IWordCloudResponse>;
|
|
182
|
+
/**
|
|
183
|
+
* Creates a timespan parameter for the API
|
|
184
|
+
* @param value - The timespan value
|
|
185
|
+
* @param unit - The timespan unit
|
|
186
|
+
* @returns The timespan string
|
|
187
|
+
*/
|
|
188
|
+
createTimespan(value: number, unit: ETimespanUnit): string;
|
|
189
|
+
/**
|
|
190
|
+
* Creates a timespan parameter with enhanced validation
|
|
191
|
+
* @param value - The timespan value
|
|
192
|
+
* @param unit - The enhanced timespan unit
|
|
193
|
+
* @returns The timespan string
|
|
194
|
+
*/
|
|
195
|
+
createTimespan(value: number, unit: TimespanUnitType): TimespanString;
|
|
196
|
+
/**
|
|
197
|
+
* Create a new query builder for constructing complex queries
|
|
198
|
+
*/
|
|
199
|
+
query(): QueryBuilder;
|
|
200
|
+
/**
|
|
201
|
+
* Create a specialized query builder for article searches
|
|
202
|
+
*/
|
|
203
|
+
articleQuery(): ArticleQueryBuilder;
|
|
204
|
+
/**
|
|
205
|
+
* Create a specialized query builder for image searches
|
|
206
|
+
*/
|
|
207
|
+
imageQuery(): ImageQueryBuilder;
|
|
208
|
+
/**
|
|
209
|
+
* Validate query string format and complexity
|
|
210
|
+
*/
|
|
211
|
+
validateQuery(query: string): {
|
|
212
|
+
valid: boolean;
|
|
213
|
+
errors: string[];
|
|
214
|
+
};
|
|
215
|
+
/**
|
|
216
|
+
* Get suggested optimizations for a query
|
|
217
|
+
*/
|
|
218
|
+
getQueryOptimizations(query: string): string[];
|
|
219
|
+
/**
|
|
220
|
+
* Enhanced parameter validation using new type guards
|
|
221
|
+
*/
|
|
222
|
+
private _validateEnhancedParams;
|
|
223
|
+
/**
|
|
224
|
+
* Enhanced response validation and transformation
|
|
225
|
+
*/
|
|
226
|
+
private _transformAndValidateResponse;
|
|
227
|
+
}
|
|
228
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|