REST API · Public key auth

Location context, structured as data.

Resolve a place, request a structured briefing for its geographic bounds, and render the result in your own interface. Use the API for custom layouts, native apps, dashboards, and data products.

Get an API key View endpoints →

POST /api/areas/resolve-and-summary

200 OK

{
  "date": "2026-09-01",
  "window_days": 7,
  "search_area": {
    "total_matches": 12,
    "cells": [/* matched areas */]
  },
  "area_summary": {
    "language": "en",
    "trend_summary": "Recent destination context...",
    "context_blocks": [
      {
        "context_type": "news",
        "title": "News",
        "paragraph": "Source-linked briefing text..."
      }
    ],
    "source_urls": ["https://example.com/source"]
  },
  "timing": { "endpoint_total_ms": 184.2 }
}

What you get

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

Area summaries

POST /api/areas/resolve-and-summary

Structured destination context for resolved geographic bounds. Returns matched areas and an area summary containing source-linked context blocks.

bounds center coordinates date window_days language

Event stream

POST /api/areas/events

Search normalized events intersecting a GeoJSON polygon over a date range, with optional category, source, and event-type filters.

geometry_geojson category date_from date_to 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 accepts resolved geographic bounds and returns matched areas plus structured context ready to display.

Response fields

date string

Snapshot date used for the briefing, formatted as YYYY-MM-DD.

window_days integer

Number of days included in the requested context window.

search_area object

Resolved search result containing matched geographic cells, counts, resolution, and truncation state.

area_summary object

The assembled briefing, including summary text, sources, context blocks, language, and availability metadata.

area_summary.context_blocks array

Ordered list of signal blocks. Each block exposes context_type, title, paragraph, priority, and its own source URLs.

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

A news block may also include image_url (string, optional) — a representative image from the highest-priority contributing source, when one is available — and image_caption (string, optional), a short caption naming that same source's own headline/summary, since the image doesn't necessarily correspond to the block's dominant topic. weather/upcoming_events blocks never include either.

area_summary.source_urls array

Source URLs retained for evidence and attribution.

timing object

Server-side timing measurements for resolution, cache lookup, assembly, and total request time.

POST /api/areas/resolve-and-summary

{
  "west": -9.2298,
  "south": 38.6914,
  "east": -9.0863,
  "north": 38.7968,
  "lat": 38.7078,
  "lon": -9.1366,
  "date": "2026-09-01",
  "window_days": 7,
  "lang": "en",
  "location_phrase": "Lisbon, Portugal"
}

Resolve the place first

Use geocoding to obtain the bounding box and center coordinates required by the briefing request.

GET /api/geocoding/search?q=Lisbon&lang=en&limit=1

Authentication

Pass your public key as an HTTP header on briefing and event requests. Demo keys (mn_demo_public_*) are limited to their configured preview destinations.

X-PlaceBrief-Public-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 enables runtime access for your configured integration. Demo keys remain limited to their approved preview destinations.

Resolve the destination

Call geocoding search to obtain the destination bounds, center coordinates, display name, and optional geometry.

Request and render the briefing

POST the resolved bounds, date, and options, then render area_summary.context_blocks in your own interface.

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

// 1. Resolve the destination
const [place] = await fetch(
  `/api/geocoding/search?q=${encodeURIComponent(destination)}&lang=en&limit=1`
).then(res => res.json());

const [south, north, west, east] =
  place.boundingbox.map(Number);

// 2. Request the briefing
const res = await fetch(
  '/api/areas/resolve-and-summary', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-PlaceBrief-Public-Key': 'mn_live_xxxxx'
    },
    body: JSON.stringify({
      west, south, east, north,
      lat: Number(place.lat),
      lon: Number(place.lon),
      date: '2026-09-01', window_days: 7,
      lang: 'en', location_phrase: place.display_name
    })
  }
);

const data = await res.json();

// 3. Render the structured context
for (const block of data.area_summary.context_blocks) {
  renderBlock(block.context_type, block.paragraph);
}