GeoMemo Dispatch

Authentication

Send your key in the X-Api-Key header. Authorization: Bearer <key> and the apiKey query parameter also work; the header keeps keys out of logs. Keys start with gmd_live_. We store only a hash, so a lost key is replaced, not recovered.

curl https://dispatch.geomemo.ai/v1/top-headlines -H "X-Api-Key: gmd_live_..."

Moving from newsapi.org

Change https://newsapi.org/v2 to https://dispatch.geomemo.ai/v1 and swap the key. The three endpoints, their main parameters and the article fields match. The differences:

• description and content both hold our summary. We never return a slice of the article text.
• top-headlines accepts any publisher country code, not only us, plus region.
• sortBy=popularity maps to our score.
• Extra fields sit in article.geomemo. Ignore it and your code runs unchanged.

GET/v1/everything

Search every article we serve. Your plan sets how far back you can go.

curl -G https://dispatch.geomemo.ai/v1/everything \
  -H "X-Api-Key: $GEOMEMO_KEY" \
  --data-urlencode 'q="grain corridor" OR "Black Sea shipping"' \
  -d from=2026-09-20 -d relevance=geo -d collapse=true -d sortBy=score

import os, requests

r = requests.get("https://dispatch.geomemo.ai/v1/everything",
    headers={"X-Api-Key": os.environ["GEOMEMO_KEY"]},
    params={"q": '"grain corridor" OR "Black Sea shipping"',
            "from": "2026-09-20", "relevance": "geo",
            "collapse": "true", "sortBy": "score"})
for a in r.json()["articles"]:
    print(a["geomemo"]["titleEn"], a["geomemo"]["language"], a["url"])

const params = new URLSearchParams({
  q: '"grain corridor" OR "Black Sea shipping"',
  from: "2026-09-20", relevance: "geo", collapse: "true", sortBy: "score" });
const res = await fetch(`https://dispatch.geomemo.ai/v1/everything?${params}`,
  { headers: { "X-Api-Key": process.env.GEOMEMO_KEY } });
const data = await res.json();

GET/v1/top-headlines

The highest-scoring geopolitically relevant stories of the last 48 hours, one article per story, highest score first. Filter by country (publisher country), region, category, language, sources or q. For more than 48 hours of a region, use /everything with region and relevance=geo.

curl -G https://dispatch.geomemo.ai/v1/top-headlines -H "X-Api-Key: $GEOMEMO_KEY" \
  --data-urlencode region="Middle East" -d pageSize=5

GET/v1/sources

Publications we collect from, with id, name, url, language, country, region, type and articles in the last 30 days. Filter by category, language, country or region. Also at /v1/top-headlines/sources for newsapi.org clients. The same list is browsable on the sources page.

{ "status": "ok", "sources": [ { "id": "example-dawn-com", "name": "Example Dawn",
  "description": null, "url": "https://example.com", "category": null,
  "language": "en", "country": "PK",
  "geomemo": { "domain": "example.com", "region": "South Asia", "type": "news", "articles30d": 1840 } } ] }

GET/v1/storiesGrowth, Business

One row per story: the lead article, how many articles and outlets covered it, in which languages, and when it was first and last seen. Filter by from (default three days ago), to, category, region, country and minSources; sortBy is size (default), recency or score (significance and popularity are accepted as aliases). Use /v1/stories/{id} for every article in a story.

{ "status": "ok", "stories": [ { "id": 551873, "size": 12, "sourceCount": 9,
  "languages": ["el", "en", "zh", "tr"], "firstSeen": "2026-09-27T06:40:00Z",
  "lastSeen": "2026-09-27T19:02:00Z", "maxScore": 68,
  "lead": { /* article object */ } } ] }

GET/v1/reference/{categories | regions | languages | countries}

The allowed values for filters, with article counts. These calls do not count against your quota, and neither does /v1/usage, which returns your plan, limits and what is left.

The article object

Never returned: article text, the publisher’s own description, author email or social handles, embeddings, or internal status values. There is no article-level sentiment field, because we do not compute one.

Categories and regions

Pass category names exactly as written. /v1/reference/categories returns the live list with counts.

Errors

{ "status": "error", "code": "rateLimited",
  "message": "Starter allows 50,000 requests a month; resets 2026-10-01T00:00:00Z." }

Rate limits

Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds, UTC). Limits apply per account, shared across its keys. Monthly quotas reset at 00:00 UTC on the first of the month; daily ones at 00:00 UTC. At the limit you get HTTP 429 until the window resets; we do not bill overage. See pricingfor each plan’s numbers.

Client libraries

Official Python and JavaScript clients are planned for launch week, on GitHub under an MIT licence. Any newsapi.org client library also works by changing its base URL.

Using the data

Show the publisher’s name and link with every article. Do not use the API to fetch, store or republish the articles themselves. Summaries are written by our models and can be wrong; do not present them as the publisher’s words. Full rules are in the terms.