gl0bsec/get_gdelt_data

# GDELT 数据收集器 一个用于获取、过滤、丰富和导出 [GDELT](https://www.gdeltproject.org/) 事件数据的 Python 工具包。 ## 功能 - **收集** 来自 GDELT 事件表的任意日期范围事件 - **过滤** 按国家代码、文本规则（YAML/JSON）或自定义条件 - **丰富** 附带 CAMEO 事件描述和可读的国家名称 - **提取** 从源 URL 获取文章元数据（标题、作者、描述） - **导出** 为 KML 文件供 Google Earth 使用，并带有 Goldstein 加权地标 - **转换** 日期为 ISO 8601 格式以用于可视化工具（如 Foursquare Studio 等） - 捆绑 FIPS 和 CAMEO 查找表，支持 ISO-3 到 FIPS 的转换 - 完整的命令行界面（支持子命令）或作为 Python 库使用 ## 安装 ``` pip install -r requirements.txt ``` ## 命令行使用 ``` # 为日期范围收集事件 python -m gdelt_data collect 2024-01-01 2024-01-07 -o events.parquet # 使用自定义过滤规则收集 python -m gdelt_data collect 2024-01-01 2024-01-07 -f my_filters.yaml -o events.parquet # 收集原始未过滤数据 python -m gdelt_data collect 2024-01-01 2024-01-07 --no-filter -o raw.parquet # 按国家（ FIPS 代码）过滤 python -m gdelt_data filter events.parquet ML -o mali.csv # 用事件描述和国家名称丰富数据 python -m gdelt_data enrich mali.csv -o mali_enriched.csv # 从源 URL 提取元数据 python -m gdelt_data extract-urls mali.csv -o mali_urls.csv --workers 8 # 导出为 KML（仅限负事件） python -m gdelt_data kml mali_enriched.csv -o mali.kml --max-goldstein 0 # 生成过滤规则模板 python -m gdelt_data template -o my_filters.yaml # 检查默认设置 python -m gdelt_data filters # show default filter rules python -m gdelt_data columns # show default output columns python -m gdelt_data operators # show all filter operators # 完整文档 python -m gdelt_data --help-all ``` ## Python 库使用 ### 收集、过滤、丰富、导出 ``` from datetime import datetime import pandas as pd from gdelt_data import ( collect_gdelt_data, filter_by_country, add_event_descriptions, add_country_names, to_kml, ) # 收集 collect_gdelt_data( start_date=datetime(2024, 1, 1), end_date=datetime(2024, 1, 7), output_file="events.parquet", ) # 筛选马里并丰富、导出 df = pd.read_parquet("events.parquet") mali = filter_by_country(df, "ML") mali = add_event_descriptions(mali) mali = add_country_names(mali) mali.to_csv("mali_events.csv", index=False) # 导出为 KML to_kml(mali, "mali.kml", max_goldstein=0) ``` ### 国家代码工具 GDELT 使用 FIPS 10-4 代码表示地理字段，使用 CAMEO/ISO-3 代码表示角色字段。该包会自动处理转换： ``` from gdelt_data import iso3_to_fips, fips_to_iso3, load_fips_dict iso3_to_fips("DEU") # "GM" (Germany) fips_to_iso3("GM") # "DEU" # 加载完整查找字典 fips = load_fips_dict() # {"US": "United States", "GM": "Germany", ...} ``` ### 过滤规则 过滤规则使用普通英文语法： ``` NumMentions greater than or equal 5 ActionGeo_CountryCode in [US, UK, FR] GoldsteinScale between -5 and 5 Actor1Name contains protest ActionGeo_Lat is not null _ ``` 创建模板并自定义： ``` python -m gdelt_data template -o my_filters.yaml ``` 或在 Python 中交互式构建过滤器： ``` from gdelt_data import interactive_filter_builder filters = interactive_filter_builder() ``` ### URL 元数据提取 ``` from gdelt_data import get_source_urls_with_metadata urls_df = get_source_urls_with_metadata( df, extract_metadata=True, dataF=True ) ``` ### 日期转换 ``` from gdelt_data import convert_dates_to_iso df = convert_dates_to_iso(df) # SQLDATE: 20250803 -> 2025-08-03 ``` ## 国家代码 GDELT 使用 FIPS 10-4 国家代码，**而非** ISO 字母二码。常见差异如下： | 国家 | FIPS | ISO | |---|---|---| | 德国 | GM | DE | | 澳大利亚 | AS | AU | | 瑞士 | SZ | CH | | 奥地利 | AU | AT | | 韩国 | KS | KR | | 日本 | JA | JP | 完整的 FIPS 查找表随软件包一起提供，可通过 `load_fips_dict()` 访问。 ## 项目结构 ``` gdelt_data/ # Core package collector.py # Data collection and filter engine cli.py # CLI with subcommands parsing.py # URL extraction, CAMEO parsing, dates country_codes.py # FIPS/CAMEO loaders, ISO-3 <-> FIPS enrich.py # Event descriptions, country names, filtering export.py # KML export data/ # Bundled lookup files FIPS.country.txt CAMEO.country.txt CAMEO.eventcodes.txt workflows/ # Project-specific collection scripts outputs/ # Generated data files (gitignored) report_generation/ # Original lookup tables ```

标签：GDELT, Homebrew安装, Mutation, Python, 代码示例, 可视化, 命令控制, 数据分析, 数据采集, 无后门, 逆向工具