# alex9smith/gdelt-doc-api architecture

> Architecture diagram of the GitHub repository alex9smith/gdelt-doc-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alex9smith/gdelt-doc-api
- Repository: https://github.com/alex9smith/gdelt-doc-api

## Overview

gdeltdoc is a Python client for small-scale querying of the GDELT 2.0 Doc API. Users construct Filters, then call article_search or timeline_search; the client sends the encoded query, handles the response, and returns a pandas DataFrame. The library also provides near/repeat query helpers and supports article lists plus five timeline modes. Source excerpts show the request, response processing, and error handling; filter date formatting is supported by the source index, while unsampled implementation details are not expanded.

Main entry points: [`gdeltdoc/api_client.py`](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/api_client.py) (GDELT client), [`gdeltdoc/filters.py`](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/filters.py) (Filter builder), [`gdeltdoc/_version.py`](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/_version.py) (Client version), [`gdeltdoc/validation.py`](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/validation.py) (Tone validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query client"]
  node_client["GDELT client<br/>[api_client.py]"]
  node_article["Article search<br/>[api_client.py]"]
  node_timeline["Timeline search<br/>[api_client.py]"]
  node_version["Client version<br/>[_version.py]"]
end

subgraph group_filters["Query filters"]
  node_filter["Filter builder<br/>[filters.py]"]
  node_proximity["Near/repeat helpers<br/>[filters.py]"]
  node_validation["Tone validation<br/>[validation.py]"]
  node_dates["Date formatting<br/>[helpers.py]"]
end

subgraph group_response["Response handling"]
  node_error_map["HTTP error mapping<br/>[errors.py]"]
  node_json_parser["JSON parser<br/>[helpers.py]"]
end

node_user(("Python user"))
node_gdelt["GDELT Doc API"]
node_dataframe[("Pandas DataFrame")]

node_user -->|"builds filters"| node_filter
node_user -->|"searches articles"| node_article
node_user -->|"searches timeline"| node_timeline
node_article -->|"queries ArtList"| node_client
node_timeline -->|"queries mode"| node_client
node_client -->|"reads query string"| node_filter
node_filter -->|"validates tone"| node_validation
node_filter -->|"formats dates"| node_dates
node_proximity -->|"supplies expressions"| node_filter
node_client -->|"sets user agent"| node_version
node_client -->|"sends HTTP query"| node_gdelt
node_gdelt -->|"returns response"| node_client
node_client -->|"checks response"| node_error_map
node_client -->|"parses content"| node_json_parser
node_article -->|"returns articles"| node_dataframe
node_timeline -->|"returns timeline"| node_dataframe

click node_client "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/api_client.py"
click node_article "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/api_client.py"
click node_timeline "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/api_client.py"
click node_version "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/_version.py"
click node_filter "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/filters.py"
click node_proximity "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/filters.py"
click node_validation "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/validation.py"
click node_dates "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/helpers.py"
click node_error_map "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/errors.py"
click node_json_parser "https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/helpers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_article,node_timeline,node_version,node_user toneBlue
class node_filter,node_proximity,node_validation,node_dates,node_dataframe toneAmber
class node_error_map,node_json_parser,node_gdelt toneMint
```

## Components

### Query client

- [GDELT client](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/api_client.py): `gdeltdoc/api_client.py`
- [Article search](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/api_client.py): `gdeltdoc/api_client.py`
- [Timeline search](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/api_client.py): `gdeltdoc/api_client.py`
- [Client version](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/_version.py): `gdeltdoc/_version.py`

### Query filters

- [Filter builder](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/filters.py): `gdeltdoc/filters.py`
- [Near/repeat helpers](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/filters.py): `gdeltdoc/filters.py`
- [Tone validation](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/validation.py): `gdeltdoc/validation.py`
- [Date formatting](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/helpers.py): `gdeltdoc/helpers.py`

### Response handling

- [HTTP error mapping](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/errors.py): `gdeltdoc/errors.py`
- [JSON parser](https://github.com/alex9smith/gdelt-doc-api/blob/main/gdeltdoc/helpers.py): `gdeltdoc/helpers.py`

### Other components

- **Python user**
- **GDELT Doc API**
- **Pandas DataFrame**

## Connections

- Python user → Filter builder: builds filters (evidence: `README.md`)
- Python user → Article search: searches articles (evidence: `README.md`)
- Python user → Timeline search: searches timeline (evidence: `README.md`)
- Article search → GDELT client: queries ArtList (evidence: `gdeltdoc/api_client.py`)
- Timeline search → GDELT client: queries mode (evidence: `gdeltdoc/api_client.py`)
- GDELT client → Filter builder: reads query string (evidence: `gdeltdoc/api_client.py`)
- Filter builder → Tone validation: validates tone (evidence: `gdeltdoc/filters.py`)
- Filter builder → Date formatting: formats dates (evidence: `gdeltdoc/filters.py`)
- Near/repeat helpers → Filter builder: supplies expressions (evidence: `README.md`)
- GDELT client → Client version: sets user agent (evidence: `gdeltdoc/api_client.py`)
- GDELT client → GDELT Doc API: sends HTTP query (evidence: `gdeltdoc/api_client.py`)
- GDELT Doc API → GDELT client: returns response (evidence: `gdeltdoc/api_client.py`)
- GDELT client → HTTP error mapping: checks response (evidence: `gdeltdoc/api_client.py`)
- GDELT client → JSON parser: parses content (evidence: `gdeltdoc/api_client.py`)
- Article search → Pandas DataFrame: returns articles (evidence: `gdeltdoc/api_client.py`)
- Timeline search → Pandas DataFrame: returns timeline (evidence: `gdeltdoc/api_client.py`)