Skip to main content
The PositiveEventsService provides geocoded positive news events from GDELT filtered for uplifting content, used exclusively by the Happy Monitor variant.

​
Base Path

/api/positive-events/v1

​
Endpoints

​
ListPositiveGeoEvents

Retrieves geocoded positive news events from GDELT GEO API with sentiment filtering. HTTP Method: GET Path: /api/positive-events/v1/list-positive-geo-events

​
Request Parameters

​
hours
number
default:"24"
Time window in hours (1-72)
​
min_tone
number
default:"5.0"
Minimum positive tone threshold (0-10, higher = more positive)
​
categories
string
Comma-separated categories: science, conservation, humanitarian, progress, achievement
​
region
string
Geographic filter: global, americas, europe, asia, africa, oceania

​
Response Fields

​
events
array
Array of positive geo-events
​
total_count
number
Total positive events
​
average_tone
number
Average tone across all events

​
Example Request

curl "https://happy.worldmonitor.app/api/positive-events/v1/list-positive-geo-events?hours=24&min_tone=7&categories=science,conservation"

​
Example Response

{
  "events": [
    {
      "event_id": "GDELT-20240301-12345",
      "date": "2024-03-01T10:30:00Z",
      "title": "Scientists discover breakthrough in renewable energy storage",
      "source_url": "https://example.com/renewable-breakthrough",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "country": "US",
      "location_name": "San Francisco",
      "tone": 8.2,
      "goldstein_scale": 7.5,
      "category": "science",
      "themes": ["SCIENCE_BREAKTHROUGH", "ENV_RENEWABLE"]
    }
  ],
  "total_count": 1,
  "average_tone": 8.2
}

​
Positive Content Filtering

Events are classified as positive using:
  1. GDELT Tone: Average tone > 5.0 (configurable via min_tone)
  2. Goldstein Scale: Cooperative/positive events (> 0)
  3. Theme filtering: Includes positive themes, excludes conflict/disaster themes
  4. Keyword exclusion: Filters out negation keywords (“disaster”, “crisis”, “war”, etc.)

​
Positive Categories

CategoryGDELT ThemesExamples
scienceSCIENCE_BREAKTHROUGH, RESEARCHMedical advances, space exploration
conservationENV_CONSERVATION, ENV_RENEWABLEWildlife protection, reforestation
humanitarianHUMANITARIAN_AID, CHARITYDisaster relief, community support
progressDEVELOPMENT, INFRASTRUCTUREPoverty reduction, education access
achievementSPORT, CULTURE, INNOVATIONRecords broken, cultural milestones

​
Use Cases

Power the Happy Monitor variant with uplifting stories to counter negative news bias.
Monitor long-term global improvements in health, education, poverty, and environmental metrics.
Display positive news in waiting rooms, public spaces, or mental health applications.
Analyze positive news coverage patterns by region, topic, and time for media studies.

​
Happy Monitor Integration

Positive events are displayed on the Happy Monitor variant at happy.worldmonitor.app with:
  • Warm theme: Cream background (#FAFAF5) for a calming aesthetic
  • Progress charts: Long-term trends in global health, poverty, renewable energy
  • Hero cards: Featured positive breakthroughs with large visuals
  • TV Mode: Shift+T for full-screen positive news rotation
The Happy Monitor variant uses a multi-layer filtering system to exclude negative content, even if GDELT tone is positive (e.g., “war ends” has positive tone but mentions war).
GDELT tone is calculated from news article text sentiment and may not perfectly align with human perception of “positive” news.

Build docs developers (and LLMs) love

Get started for freeTalk to us