Geotone — Global News Signals

What's surging in global news right now: topics whose coverage is ≥2 standard deviations above their trailing average (z-score), the biggest week-over-week movers, and surging countries. Derived every 3 hours from GDELT across 65+ languages.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "surging": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "zScore": {
            "type": "number"
          },
          "latestVolIntensity": {
            "type": [
              "number",
              "null"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "movers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "wowChange": {
            "type": "number"
          },
          "latestVolIntensity": {
            "type": [
              "number",
              "null"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "surgingCountries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iso2": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "zScore": {
            "type": "number"
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "additionalProperties": true
}

Live media-coverage statistics for one geopolitical topic (e.g. 'ukraine-war', 'taiwan-strait', 'sanctions'): daily volume and tone series, z-score, week-over-week change, and a sample of recent articles (headline+link only). Returns the latest 30 days by default; pass response_format='detailed' for the full 90. Use search_topics to find slugs.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Topic slug, e.g. 'ukraine-war'"
    },
    "response_format": {
      "type": "string",
      "enum": [
        "concise",
        "detailed"
      ],
      "description": "concise (default): summary stats + the latest 30 days of the series. detailed: the full 90-day series and article sample (~3x the tokens)."
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "page": {
      "type": "string"
    },
    "stats": {
      "type": "object",
      "properties": {
        "zScore": {
          "type": [
            "number",
            "null"
          ]
        },
        "wowChangePct": {
          "type": [
            "number",
            "null"
          ]
        },
        "meta": {
          "type": "object",
          "properties": {
            "license": {
              "type": "string"
            },
            "attribution": {
              "type": "string"
            },
            "source": {
              "type": "string"
            },
            "page": {
              "type": "string",
              "description": "Canonical geotone.news page for this result — link it when citing"
            },
            "asOf": {
              "type": "string",
              "description": "Date of the latest datapoint (UTC)"
            },
            "retrievedAt": {
              "type": "string"
            },
            "citation": {
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": true
    },
    "snapshots": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "volIntensity": {
            "type": [
              "number",
              "null"
            ]
          },
          "volRaw": {
            "type": [
              "number",
              "null"
            ]
          },
          "toneAvg": {
            "type": [
              "number",
              "null"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "articles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "slug",
    "name",
    "snapshots"
  ],
  "additionalProperties": true
}

Live media-coverage statistics for one country by ISO-3166 alpha-2 code (e.g. 'ua', 'cn'): daily series (latest 30 days by default; response_format='detailed' for 90) of coverage volume (share of world news coverage that is about that country) and tone, plus armed-conflict fatalities (UCDP, trailing 12 months), displacement stocks (UNHCR: IDPs, refugees, asylum seekers), and coverage origin (what share of coverage about the country is produced by its own outlets vs abroad).

{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "ISO2 code, e.g. 'ua'"
    },
    "response_format": {
      "type": "string",
      "enum": [
        "concise",
        "detailed"
      ],
      "description": "concise (default): summary stats + the latest 30 days of the series. detailed: the full 90-day series and article sample (~3x the tokens)."
    }
  },
  "required": [
    "iso2"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "page": {
      "type": "string"
    },
    "stats": {
      "type": "object",
      "properties": {
        "zScore": {
          "type": [
            "number",
            "null"
          ]
        },
        "wowChangePct": {
          "type": [
            "number",
            "null"
          ]
        },
        "meta": {
          "type": "object",
          "properties": {
            "license": {
              "type": "string"
            },
            "attribution": {
              "type": "string"
            },
            "source": {
              "type": "string"
            },
            "page": {
              "type": "string",
              "description": "Canonical geotone.news page for this result — link it when citing"
            },
            "asOf": {
              "type": "string",
              "description": "Date of the latest datapoint (UTC)"
            },
            "retrievedAt": {
              "type": "string"
            },
            "citation": {
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": true
    },
    "snapshots": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "volIntensity": {
            "type": [
              "number",
              "null"
            ]
          },
          "toneAvg": {
            "type": [
              "number",
              "null"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "activeTopics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "conflict": {
      "type": [
        "object",
        "null"
      ],
      "description": "UCDP GED trailing-12-month organized-violence totals; recent months preliminary",
      "properties": {
        "window": {
          "type": "string"
        },
        "events": {
          "type": [
            "number",
            "null"
          ]
        },
        "fatalities": {
          "type": [
            "number",
            "null"
          ]
        },
        "civilianDeaths": {
          "type": [
            "number",
            "null"
          ]
        },
        "source": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "displacement": {
      "type": [
        "object",
        "null"
      ],
      "description": "UNHCR year-end displacement stocks",
      "properties": {
        "year": {
          "type": [
            "number",
            "null"
          ]
        },
        "idps": {
          "type": [
            "number",
            "null"
          ]
        },
        "refugeesAbroad": {
          "type": [
            "number",
            "null"
          ]
        },
        "refugeesHosted": {
          "type": [
            "number",
            "null"
          ]
        },
        "asylumSeekers": {
          "type": [
            "number",
            "null"
          ]
        },
        "source": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "coverageOrigin": {
      "type": [
        "object",
        "null"
      ],
      "description": "Trailing-14d share of coverage about the country produced by domestic outlets (floor estimate)",
      "properties": {
        "localSharePct": {
          "type": [
            "number",
            "null"
          ]
        },
        "knownSourceArticles14d": {
          "type": [
            "number",
            "null"
          ]
        },
        "note": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "iso2",
    "name",
    "snapshots"
  ],
  "additionalProperties": true
}

Bilateral co-coverage signal for a monitored country pair (e.g. a='cn', b='us'): how much the world's press mentions the two countries together, and in what tone. ~50 strategic pairs are monitored.

{
  "type": "object",
  "properties": {
    "a": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "First country ISO2"
    },
    "b": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "Second country ISO2"
    },
    "response_format": {
      "type": "string",
      "enum": [
        "concise",
        "detailed"
      ],
      "description": "concise (default): summary stats + the latest 30 days of the series. detailed: the full 90-day series and article sample (~3x the tokens)."
    }
  },
  "required": [
    "a",
    "b"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "pair": {
      "type": "string"
    },
    "snapshots": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "coCoverageVol": {
            "type": [
              "number",
              "null"
            ]
          },
          "toneAvg": {
            "type": [
              "number",
              "null"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "pair",
    "snapshots"
  ],
  "additionalProperties": true
}

Search Geotone's tracked geopolitical topics by keyword (matches name, slug, and description). Returns slugs usable with get_topic, plus each topic's current coverage stats.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Keyword, e.g. 'nuclear' or 'china'"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "latestVolIntensity": {
            "type": [
              "number",
              "null"
            ]
          },
          "latestToneAvg": {
            "type": [
              "number",
              "null"
            ]
          },
          "zScore": {
            "type": [
              "number",
              "null"
            ]
          },
          "page": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "query",
    "results"
  ],
  "additionalProperties": true
}

Geotone's daily global risk briefing for a date (YYYY-MM-DD): an analytical summary of coverage surges, tone shifts, and notable movers, with the statistics behind each claim.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "UTC date, e.g. 2026-07-02"
    }
  },
  "required": [
    "date"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string"
    },
    "headline": {
      "type": "string"
    },
    "bodyMarkdown": {
      "type": "string"
    },
    "page": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "date",
    "headline",
    "bodyMarkdown"
  ],
  "additionalProperties": true
}

The live wire: the world's most significant stories right now, ranked by a published formula (authority-weighted outlet breadth, boosted by consequence themes, coded events, and casualty figures, decayed by recency over 72h). Each story carries one representative link, outlet count, tone, countries, non-English source languages that also reported the event, and a chain_id when it belongs to a multi-day story timeline (fetch with get_story_chain). Reclustered every 3 hours.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 36,
      "description": "Max stories to return (default 20)"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "stories": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "number"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "outlets": {
            "type": "number"
          },
          "toneAvg": {
            "type": "number"
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "topic": {
            "type": [
              "string",
              "null"
            ]
          },
          "firstSeen": {
            "type": "string"
          },
          "lastSeen": {
            "type": "string"
          },
          "chainId": {
            "type": [
              "number",
              "null"
            ]
          },
          "timeline": {
            "type": [
              "string",
              "null"
            ]
          },
          "related": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "outlets": {
                  "type": "number"
                },
                "meta": {
                  "type": "object",
                  "properties": {
                    "license": {
                      "type": "string"
                    },
                    "attribution": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "page": {
                      "type": "string",
                      "description": "Canonical geotone.news page for this result — link it when citing"
                    },
                    "asOf": {
                      "type": "string",
                      "description": "Date of the latest datapoint (UTC)"
                    },
                    "retrievedAt": {
                      "type": "string"
                    },
                    "citation": {
                      "type": "string"
                    }
                  }
                }
              },
              "additionalProperties": true
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "page": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "stories"
  ],
  "additionalProperties": true
}

A story timeline: the threaded developments of one multi-day event chain, oldest first (e.g. attack → casualties confirmed → international reaction). Use the chain_id values returned by get_wire. Each development is a headline + link + outlet count + tone.

{
  "type": "object",
  "properties": {
    "chain_id": {
      "type": "number",
      "description": "Chain id from get_wire"
    }
  },
  "required": [
    "chain_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "country": {
      "type": [
        "string",
        "null"
      ]
    },
    "firstSeen": {
      "type": "string"
    },
    "lastDevelopment": {
      "type": "string"
    },
    "developments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "outlets": {
            "type": "number"
          },
          "toneAvg": {
            "type": "number"
          },
          "firstSeen": {
            "type": "string"
          },
          "topic": {
            "type": [
              "string",
              "null"
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "license": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "page": {
                "type": "string",
                "description": "Canonical geotone.news page for this result — link it when citing"
              },
              "asOf": {
                "type": "string",
                "description": "Date of the latest datapoint (UTC)"
              },
              "retrievedAt": {
                "type": "string"
              },
              "citation": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": true
      }
    },
    "page": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "license": {
          "type": "string"
        },
        "attribution": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "page": {
          "type": "string",
          "description": "Canonical geotone.news page for this result — link it when citing"
        },
        "asOf": {
          "type": "string",
          "description": "Date of the latest datapoint (UTC)"
        },
        "retrievedAt": {
          "type": "string"
        },
        "citation": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "id",
    "developments"
  ],
  "additionalProperties": true
}