Situations

curl --get "https://gdeltcloud.com/api/v2/situations/$SITUATION_ID/entities" \
  --header "Authorization: Bearer $GDELT_API_KEY" \
  --data-urlencode 'limit=25' \
  --data-urlencode 'offset=25' \
  --data-urlencode "scope_version=$SCOPE_VERSION"

import os
import requests

BASE = "https://gdeltcloud.com/api/v2"
HEADERS = {"Authorization": f"Bearer {os.environ.get('GDELT_API_KEY', '')}"}
MAX_RESTARTS = 3


def fetch_page(situation_uid, offset, scope_version=None, limit=25, session=requests):
    params = {"limit": limit, "offset": offset}
    if scope_version:
        params["scope_version"] = scope_version
    return session.get(f"{BASE}/situations/{situation_uid}/entities", headers=HEADERS, params=params)


def walk_entities(situation_uid, limit=25, session=requests):
    """Every linked entity, restarting from page 0 whenever the membership scope changes."""
    offset, scope_version, restarts, collected = 0, None, 0, []
    while True:
        response = fetch_page(situation_uid, offset, scope_version, limit, session)
        if response.status_code == 409:
            # The scope changed between pages (code SITUATION_SCOPE_CHANGED). Mixing editions would
            # silently combine two memberships, so discard the partial walk, drop the version and
            # start again at offset 0.
            restarts += 1
            if restarts > MAX_RESTARTS:
                raise RuntimeError("membership kept changing; try again later")
            offset, scope_version, collected = 0, None, []
            continue
        response.raise_for_status()
        body = response.json()
        scope_version = body["scope"]["version"]
        collected.extend(body["data"])
        if not body["pagination"]["has_more"]:
            return collected
        offset += limit


if __name__ == "__main__":
    for entity in walk_entities("sit_e64ab6cc5c964749aee1"):
        print(entity["entity_id"], entity["name"])

export IDEMPOTENCY_KEY="sit-create-$(date +%s)-nepal-flood"   # store it before sending
curl -X POST 'https://gdeltcloud.com/api/v2/situations' \
  --header "Authorization: Bearer $GDELT_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data @body.json

{ "story_id": "743d7e77540a" }

{
  "success": false,
  "error": "Choose a supporting Story to seed this Situation.",
  "code": "AMBIGUOUS_EVENT_SEED",
  "details": {
    "stories": [
      { "story_id": "743d7e77540a", "story_date": "2026-08-26" },
      { "story_id": "26826d1cf2e2", "story_date": "2026-08-26" }
    ],
    "truncated": false
  }
}

import os
import uuid
import requests

BASE = "https://gdeltcloud.com/api/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"}


def create_situation(body, idempotency_key):
    """One admitted creation per key. Retry a timeout with the SAME key and body; a new body needs a NEW key."""
    return requests.post(
        f"{BASE}/situations",
        headers={**HEADERS, "Idempotency-Key": idempotency_key, "Content-Type": "application/json"},
        json=body,
        timeout=60,
    )


key = f"sit-create-{uuid.uuid4()}"  # store the key before sending, so a timeout can be retried with it
response = create_situation({"story_id": "743d7e77540a"}, key)
if response.status_code == 409 and response.json().get("code") == "AMBIGUOUS_EVENT_SEED":
    # An Event seed with several supporting Stories. Choose one explicitly — and because that is a
    # DIFFERENT body, send it under a NEW Idempotency-Key, never under `key`.
    for candidate in response.json()["details"]["stories"]:
        print(candidate["story_id"], candidate["story_date"])
    raise SystemExit("Choose one supporting Story and resend it as story_id with a new Idempotency-Key.")
print(response.status_code, response.json())