gdelt-client 0.1.0__tar.gz

gdelt_client-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: BobMerkus

gdelt_client-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,32 @@
+name: Run linting and type checking
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  unit-test:
+    name: python
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install the project
+        run: uv sync --locked --dev
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Run ruff lint
+        run: uv run ruff check .
+
+      - name: Run mypy
+        run: uv run mypy ./src --cache-dir .mypy_cache

gdelt_client-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: release-main
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Update project version
+        run: |
+          # Strip 'v' prefix from tag if present
+          VERSION="${TAG#v}"
+
+          # Validate semantic version format
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$ ]]; then
+            echo "Error: Invalid semantic version format: $VERSION"
+            exit 1
+          fi
+
+          sed -i "s/^version = [\"'].*[\"']/version = \"$VERSION\"/" pyproject.toml
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

gdelt_client-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Run unit tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  unit-test:
+    name: python
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --locked --dev
+
+      - name: Run unit tests
+        run: uv run pytest tests --cov=src/gdelt_client --cov-report=xml --cov-report=term-missing -m "not integration"

gdelt_client-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit tests / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.idea/
+
+# IDE and local testing
+.vscode/
+example.py

gdelt_client-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13.2

gdelt_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## 1.12.0
+
+Raise custom errors when the GDELT API returns a non-200 status code (#66)
+
+## 1.11.0
+
+Allow datetimes to be passed to `start_date` and `end_date` (#63)
+
+## 1.10.3
+
+Handle empty API responses in timeline search (#62)
+
+## 1.10.2
+
+Fix `Unpack` type hint for older Python versions (#60)
+
+## 1.10.1
+
+Add workaround for domain bug to filter docstring (#54)
+Handle 0 results in timeline search (#55)
+
+## 1.10.0
+
+Add support for `tone` and `tone_absolute` filters (#51)
+Fix type hints in filters (#50)
+
+## 1.9.0
+
+Fix JSONDecodeError when loading bad responses from the API (#47)
+
+## 1.8.0
+
+Add multiple nears (#31)(#45)
+
+## 1.7.0
+
+Add the ability to filter based on 3 letter language (#38)
+
+## 1.6.0
+
+Only support Python 3.10 and above (#39)
+Format all files with prettier (#40)
+Update package dependencies (#41)
+
+## 1.5.0
+
+Provide user agent in requests to the API (#22)
+
+## 1.4.0
+
+Validate `timespan` filter parameter to make sure it's an allowed value
+Catch API errors when a query string is invalid and return them to the user
+
+## 1.3.3
+
+Fix a bug in `multi_repeat` which meant any filter using `OR` would fail
+
+## 1.3.2
+
+Fix a bug in `multi_repeat` which caused a bad response from the API which could not be parsed
+
+## 1.3.1
+
+Fix bug when only the first of the filter conditions (eg. keyword, near, etc.) was used
+
+## 1.3.0
+
+Recursively load the JSON response to remove improper characters
+
+## 1.2.0
+
+Add support for filtering by timespan instead of start and end date
+
+## 1.1.0
+
+Adds support for multiple repeat filters
+
+## 1.0.0
+
+First version released

gdelt_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bob Merkus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gdelt_client-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: gdelt-client
+Version: 0.1.0
+Summary: A client for the GDELT 2.0 API
+Author-email: Bob Merkus <bob.merkus@gmail.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: geopandas>=1.1.2
+Requires-Dist: pandas>=3.0.0
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+# GDELT 2.0 API Client
+
+A Python client to fetch data from the [GDELT 2.0 API](https://gdeltproject.org/).
+
+This client supports both the DOC API for article search and timelines, as well as direct access to GDELT's raw event data files (events, mentions, and GKG). This allows for simpler, small-scale analysis of news coverage and events data without having to deal with the complexities of downloading and managing the raw files from S3, or working with the BigQuery export.
+
+The implementation has been forked from [gdeltdoc](https://github.com/alex9smith/gdelt-doc-api).
+
+## Installation
+
+`gdelt-client` is on [PyPi](https://pypi.org/project/gdelt-client/) and is installed through pip:
+
+```bash
+pip install gdelt-client
+```
+
+## Use
+
+### DOC API - Article Search & Timelines
+
+Search for news articles and get timeline data via the GDELT DOC API.
+
+```python
+from gdelt_client import GdeltClient, Filters
+
+f = Filters(
+    keyword="climate change",
+    start_date="2020-05-10",
+    end_date="2020-05-11"
+)
+
+gd = GdeltClient()
+
+# Search for articles matching the filters
+articles = gd.article_search(f)
+
+# Get a timeline of coverage volume
+timeline = gd.timeline_search("timelinevol", f)
+```
+
+**Async example:**
+
+```python
+import asyncio
+from gdelt_client import GdeltClient, Filters
+
+async def main():
+    f = Filters(keyword="climate change", start_date="2020-05-10", end_date="2020-05-11")
+
+    # Use async context manager to properly cleanup resources
+    async with GdeltClient() as gd:
+        # Async article search
+        articles = await gd.aarticle_search(f)
+
+        # Async timeline search
+        timeline = await gd.atimeline_search("timelinevol", f)
+
+asyncio.run(main())
+```
+
+### Raw Data Downloads - Events, Mentions & GKG
+
+Download and parse GDELT's raw data files directly. Returns data with CAMEO code descriptions for events.
+
+```python
+from gdelt_client import GdeltClient, GdeltTable, OutputFormat
+
+gd = GdeltClient()
+
+# Download events for a single date
+events = gd.search(
+    date="2020-05-10",
+    table=GdeltTable.EVENTS,
+    output=OutputFormat.DATAFRAME
+)
+
+# Download mentions for a date range with full 15-min coverage
+mentions = gd.search(
+    date=["2020-05-10", "2020-05-11"],
+    table=GdeltTable.MENTIONS,
+    coverage=True  # Download all 15-minute intervals
+)
+
+# Get GeoDataFrame with geometry for mapping
+geo_events = gd.search(
+    date="2020-05-10",
+    table=GdeltTable.EVENTS,
+    output=OutputFormat.GEODATAFRAME
+)
+
+# View table schema
+schema = gd.schema(GdeltTable.EVENTS)
+```
+
+**Async example** (downloads files concurrently for better performance):
+
+```python
+import asyncio
+from gdelt_client import GdeltClient, GdeltTable
+
+async def main():
+    # Use async context manager to properly cleanup resources
+    async with GdeltClient() as gd:
+        # Async search with concurrent file downloads
+        events = await gd.asearch(
+            date=["2020-05-10", "2020-05-11"],
+            table=GdeltTable.EVENTS,
+            coverage=True
+        )
+    print(events[:5])
+    print(f"Total records {len(events)}")
+asyncio.run(main())
+```
+
+**Available tables:** `EVENTS`, `MENTIONS`, `GKG`  
+**Available output formats:** `DATAFRAME`, `JSON`, `CSV`, `GEODATAFRAME`
+
+### Article List
+
+The `article_search()` method (and async `aarticle_search()`) generates a list of news articles that match the filters. Returns a pandas DataFrame with columns: `url`, `url_mobile`, `title`, `seendate`, `socialimage`, `domain`, `language`, `sourcecountry`.
+
+### Timeline Search
+
+The `timeline_search()` method (and async `atimeline_search()`) supports 5 modes:
+
+- `timelinevol` - Timeline of coverage volume as a percentage of all monitored articles
+- `timelinevolraw` - Timeline with actual article counts instead of percentages
+- `timelinelang` - Coverage broken down by language (each language as a column)
+- `timelinesourcecountry` - Coverage broken down by source country (each country as a column)
+- `timelinetone` - Average tone of articles over time (see [GDELT docs](https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/) for tone metric details)
+
+All modes return a pandas DataFrame with a `datetime` column and data columns.
+
+### Filters
+
+The search query passed to the API is constructed from a `gdelt_client.Filters` object.
+
+```python
+from gdelt_client import Filters, near, repeat
+
+f = Filters(
+    start_date = "2020-05-01",
+    end_date = "2020-05-02",
+    num_records = 250,
+    keyword = "climate change",
+    domain = ["bbc.co.uk", "nytimes.com"],
+    country = ["UK", "US"],
+    theme = "GENERAL_HEALTH",
+    near = near(10, "airline", "carbon"),
+    repeat = repeat(5, "planet")
+)
+```
+
+Filters for `keyword`, `domain`, `domain_exact`, `country`, `language` and `theme` can be passed either as a single string or as a list of strings. If a list is passed, the values in the list are wrappeed in a boolean OR.
+
+You must pass either `start_date` and `end_date`, or `timespan`
+
+- `start_date` - The start date for the filter in YYYY-MM-DD format or as a datetime object in UTC time.
+  Passing a datetime allows you to specify a time down to seconds granularity. The API officially only supports the most recent 3 months of articles. Making a request for an earlier date range may still return data, but it's not guaranteed.
+- `end_date` - The end date for the filter in YYYY-MM-DD format or as a datetime object in UTC time.
+- `timespan` - A timespan to search for, relative to the time of the request. Must match one of the API's timespan formats - https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/
+- `num_records` - The number of records to return. Only used in article list mode and can be up to 250.
+- `keyword` - Return articles containing the exact phrase `keyword` within the article text.
+- `domain` - Return articles from the specified domain. Does not require an exact match so passing "cnn.com" will match articles from `cnn.com`, `subdomain.cnn.com` and `notactuallycnn.com`.
+- `domain_exact` - Similar to `domain`, but requires an exact match.
+- `country` - Return articles published in a country or list of countries, formatted as the FIPS 2 letter country code.
+- `language` - Return articles published in the given language, formatted as the ISO 639 language code.
+- `theme` - Return articles that cover one of GDELT's GKG Themes. A full list of themes can be found [here](http://data.gdeltproject.org/api/v2/guides/LOOKUP-GKGTHEMES.TXT)
+- `near` - Return articles containing words close to each other in the text. Use `near()` to construct. eg. `near = near(5, "airline", "climate")`, or `multi_near()` if you want to use multiple restrictions eg. `multi_near([(5, "airline", "crisis"), (10, "airline", "climate", "change")], method="AND")` finds "airline" and "crisis" within 5 words, and "airline", "climate", and "change" within 10 words
+- `repeat` - Return articles containing a single word repeated at least a number of times. Use `repeat()` to construct. eg. `repeat =repeat(3, "environment")`, or `multi_repeat()` if you want to use multiple restrictions eg. `repeat = multi_repeat([(2, "airline"), (3, "airport")], "AND")`
+- `tone` - Return articles above or below a particular tone score (ie more positive or more negative than a certain threshold). To use, specify either a greater than or less than sign and a positive or negative number (either an integer or floating point number). To find fairly positive articles, use `tone=">5"` or to search for fairly negative articles, use `tone="<-5"`
+- tone_absolute - The same as `tone` but ignores the positive/negative sign and lets you search for high emotion or low emotion articles, regardless of whether they were happy or sad in tone
+
+## Attribution
+
+The JSON schema data files in this package (`src/gdelt_client/data/schemas/`) are based on schemas from [gdeltPyR](https://github.com/linwoodc3/gdeltPyR), which is licensed under the GNU General Public License v3.0.
+
+## Developing gdelt-client
+
+PRs & issues are very welcome!
+
+### Setup
+
+It's recommended to use a virtual environment for development. Set one up with [uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+```
+uv sync
+```
+
+Tests for this package use `pytest`. Run them with
+
+```
+uv run pytest tests --cov=src/gdelt_client --cov-report=xml --cov-report=term-missing
+```
+
+If your PR adds a new feature or helper, please also add some tests
+
+### Publishing
+
+There's a bit of automation set up to help publish a new version of the package to PyPI,
+
+1. Make sure the version string has been updated since the last release. This package follows semantic versioning.
+2. Create a new release in the Github UI, using the new version as the release name
+3. Watch as the `publish.yml` Github action builds the package and pushes it to PyPI