REST API · Public key auth

Location context, structured as data.

Query events, sentiment scores, plain-language summaries, and map tiles for any place on earth. Use the API when the widget isn't enough — for custom layouts, dashboards, or data pipelines.

Get an API key View endpoints →

GET /api/areas/resolve-and-summary

200 OK

{
  "place":         "New York, United States",
  "area_id":       "87259a6dfffffff",
  "score":         1.2,
  "sentiment":     "moderate",
  "context_blocks": [
    {
      "type":     "gkg",
      "priority": 10,
      "label":    "Area signal",
      "body":     "42 events indexed
               over 7 days."
    },
    {
      "type":     "news",
      "priority": 20,
      "label":    "News",
      "body":     "No security alerts.
               Transit events ongoing."
    },
    {
      "type":     "weather",
      "priority": 30,
      "label":    "Weather",
      "body":     "Partly cloudy, 18 °C."
    }
  ],
  "events_count":  42,
  "window_days":   7,
  "language":      "en",
  "updated_at":    "2026-04-25T06:00Z"
}

What you get

Four surfaces, one key. From plain-language summaries to raw event data to renderable map tiles.

Area summaries

GET /api/areas/resolve-and-summary

Plain-language context for any bounding box or place name. Returns a Goldstein score, sentiment label, and structured context blocks (GKG signal, news, weather) — ready to render directly in your UI.

place name bounding box H3 cell id window_days language

Event stream

GET /api/events

Filterable feed of raw events ingested from GDELT, RSS feeds, and curated sources. Each event carries a precise geographic location, timestamp, Goldstein score, and category tag.

bbox category since until limit

Map tiles

GET /api/tiles/{z}/{x}/{y}

MVT vector tiles and PNG sentiment heatmaps for embedding into your own map. Each tile encodes H3 cell data — score, event count, category breakdown — compatible with Mapbox and MapLibre.

MVT vector PNG heatmap Mapbox-compatible

Trend data

GET /api/stats/timeseries

Score history per H3 cell for rendering sparklines, trend charts, and historical comparisons. Returns daily aggregated counts and score averages across a configurable window.

window_days daily buckets score averages

Response structure

The resolve-and-summary endpoint is the primary surface — it resolves any place name and returns structured context ready to display.

Response fields

place string

Resolved canonical place name, e.g. "New York, United States"

area_id string

H3 cell identifier at resolution 7, e.g. "87259a6dfffffff"

score float

Goldstein scale score: < −3 adverse (red) · −3 to +3 moderate (yellow) · > +3 positive (green)

sentiment string

"adverse" | "moderate" | "positive" — derived from the score bucket

context_blocks array

Ordered list of signal blocks, each with a type and body text. Render in priority order.

gkg priority 10 — area signal summary from GDELT GKG

news priority 20 — news event digest from RSS and crawled sources

weather priority 30 — current conditions plain text

events_count integer

Number of events aggregated in this response

updated_at ISO 8601

Timestamp of the most recent data refresh

GET /api/areas/resolve-and-summary

# Query parameters
place         = "Paris"
window_days   = 7
lang          = "en"

# Or by coordinates
lat           = 48.8566
lon           = 2.3522
window_days   = 7
lang          = "fr"

# Authentication
X-PlaceBrief-Key: mn_live_xxxxx

Sentiment scale

score < −3 Adverse — notable disruptions or conflict

−3 to +3 Moderate — mixed or neutral conditions

score > +3 Positive — stable, favorable conditions

Authentication

Pass your API key as an HTTP header on every request. Public demo keys (mn_demo_public_*) work without authentication for testing.

X-PlaceBrief-Key: mn_live_xxxxx

Use the API directly

When you need the data without the widget UI — for custom rendering, mobile apps, or internal tools.

A live key unlocks credit-funded runtime access and your allowed domains. The demo keys work instantly for local testing.

Call resolve-and-summary

Send the place name (or lat/lon) and your desired window. The API handles geocoding, aggregation, and translation.

Render context_blocks in order

Iterate the array sorted by priority. Each block has a type, label, and body — render however your product needs.

When to use the API vs the widget

Widget when you want a styled, self-contained iframe with no render work

API when you control the layout, need raw data, or build for a native app

fetch example — JavaScript

// Get context for any destination
const res = await fetch(`/api/areas/resolve-and-summary
  ?place=${destination}
  &window_days=7
  &lang=en`, {
  headers: {
    'X-PlaceBrief-Key': 'mn_live_xxxxx'
  }
});

const data = await res.json();

// Render in sentiment color
const badge = data.sentiment; // "moderate"

// Render context blocks in priority order
for (const block of data.context_blocks) {
  renderBlock(block.type, block.body);
}