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 ```

标签：CAMEO, columns, filters, FIPS, GDELT, Google Earth, ISO 8601, JSON配置, KML, Mutation, operators, Python工具包, URL解析, YAML配置, 事件数据, 元数据提取, 冲突事件, 可视化, 命令控制, 国家编码, 国际事件, 地理数据, 子命令, 并行处理, 批量处理, 数据增强, 数据导出, 数据采集, 数据预览, 时间处理, 查找表, 模板生成, 自定义过滤, 规则过滤, 进程保护