README.md

---
title: GDELT Engine
emoji: 🌍
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# GDELT Engine

High-performance Go API for processing GDELT (Global Database of Events, Language, and Tone) data.

## Features

- **Timestamp-triggered processing** - Submit timestamps via API
- **Parallel processing** - Up to 24 timestamps concurrently
- **Streaming downloads** - Memory-efficient file processing
- **Structural validation** - Validates GDELT timestamp format

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | API info |
| `/health` | GET | Health check |
| `/stats` | GET | Database statistics |
| `/process` | POST | Submit timestamps for processing |
| `/status/{ts}` | GET | Check timestamp status |
| `/timestamps` | GET | List all timestamps |

## Usage

### Submit Timestamps

```bash
curl -X POST https://subham9126-goworker.hf.space/process \
  -H "Content-Type: application/json" \
  -d '{"timestamps": ["20260128171500", "20260128173000"]}'
```

### Check Status

```bash
curl https://subham9126-goworker.hf.space/status/20260128171500
```

## Timestamp Format

- 14 characters: `YYYYMMDDHHmmss`
- Minutes must be: `00`, `15`, `30`, or `45`
- Cannot be in the future

## Environment Variables

Set these as **Secrets** in Space settings:

| Variable | Description |
|----------|-------------|
| `MONGO_URI` | MongoDB connection string (required) |
| `DATABASE_NAME` | Database name (default: gdelt) |