Skip to main content

​
Choosing a surface

  • Events — structured incidents: actors, event category/subcategory, fatalities, Goldstein scale, and event-level metrics.
  • Stories — clustered narratives with top article evidence; best for discovery of emerging topics.
  • Summaries (/events/summary, /stories/summary) — dashboard totals and trend charts. Drill down into Events or Stories afterwards, but not with the same filters: a summary accepts a smaller parameter set than its list sibling, and the ones it drops are listed in the endpoint index.
  • Entities — people and organizations, with linked Stories/Events. Resolve a name first via GET /api/v2/search.
  • Energy — GEM assets and owners; resolve an owner, then pull its cross-tracker portfolio.
  • Facilities — the unified physical-asset directory (energy assets + ports + AI data centers); filter by type/class/near, or pivot from an owner_entity_id to its whole portfolio.

​
Defaults worth adopting

  • Use limit=10 for exploratory / API Arena requests, then raise it when you need more rows.
  • Use sort=significance for monitoring and dashboards; sort=recent when freshness matters more than importance.
  • Use plain-English geography in apps, e.g. country=United States.
  • When writing code, pass parameters through your HTTP client’s params / URLSearchParams rather than hand-building URLs — clients encode United States correctly, and the API decodes both %20 and +.
  • Omit dates on /events or /stories and you get a rolling 7-day window. Other families differ — the declared default is on each days parameter in the API reference. Explicit date_start/date_end filter by event or story date and the window must be 30 days or less.
  • Start broad, then narrow with geography, category, subcategory, date windows, and semantic search.
  • search is true semantic retrieval on list endpoints only: v2 embeds the query, applies the structured filters as the candidate set, and ranks by cosine similarity. Summary endpoints do not accept search.
  • Discover admin1 values per-country via /api/v2/geo/admin1?country=... before using them.
  • Treat inline top_articles as an evidence preview; use /api/v2/stories/{story_id}/articles for the full paginated source list.
Metric filters use canonical response-field names, and each metric is published by only some event families — a _min/_max pair on a metric the family does not carry narrows to nothing. The per-metric family scope, and every filterable field, are in the metric reference.

​
Country, region, or continent monitoring

For a fixed window rather than a rolling one, swap days for an explicit pair — 30 days or less:

​
Infrastructure events

Use CAMEO+ category=INFRASTRUCTURE as the canonical pattern:
For high-propagation infrastructure incidents:
For high-significance Events across families:

​
Semantic event search

​
Protests today or recently

For a current list:
For a daily dashboard trend:

​
New data center projects in Asia

Use Stories first because this is a narrative discovery task. Keep article_count_min=1 for emerging-project discovery; raise it only when you want more source volume.
Then use Events if you need structured infrastructure event records:

​
Fatal conflict monitoring

​
Admin1 drilldown

​
Bounding box drilldown

When country or admin1 is too coarse — straits, ports, basins, border zones, custom viewports — filter directly on Event coordinates with bbox=lat_min,lon_min,lat_max,lon_max:
Combine with country when you want events in a specific area of a specific country:

​
Story articles

Story list and detail responses return only the top 3 inline articles. Use the articles endpoint for the full source set:

​
Resolve an entity, then fan out

GET /api/v2/search?q=<name>&universe=all is the fuzzy “find the entity” step — start there with a name, pick the best entity_id, then call the surfaces you need with that shared id (profile, exposure, filings, screening). See Finding an entity.