Country Topics APIKeep place, language, and subject connected.

Ask what the place is doing in the story

A report may be published in one country, describe an event in another, and discuss policy affecting several others. A single country field cannot explain those relationships. Define the role of each place reference before deciding how it should appear in navigation.

Keep source location, event location, and geographic subject separate when they matter to the reader. Do not infer the audience or identity of the author from the language alone. A multilingual document can discuss a place without being produced there.

Use identifiers with a stated scheme

A normalized geographic identifier helps join records, but the scheme and version should remain visible. Preserve the source label alongside the normalized value, especially where names differ by language or editorial style.

An identifier is a technical reference, not a substitute for explaining the geographic scope. Regions, territories, cities, and cross-border areas may need different levels of detail. Choose the resolution that serves the retrieval task rather than forcing every reference into a country bucket.

Preserve ambiguity and historical context

A name can refer to more than one place, and place references can change meaning across time or context. Use surrounding evidence to resolve them and keep an explicit review state when the text does not support a confident choice.

When the document describes a historical event, retain the event’s context and the source’s wording. Avoid silently rewriting an old record to match a current label if doing so changes its meaning. A mapping can support modern retrieval while preserving the original account.

Evaluate across languages and sources

Test geographic assignments with local-language examples and people familiar with the relevant context. Check whether short names, abbreviations, or translated institutions create systematic errors. A global average can hide a poor result for a smaller language collection.

Design country archives around useful questions. Readers may want regional background, cross-border comparisons, or reporting about a specific event. Make the role and granularity of geographic labels visible so the archive explains why an article appears there.

An illustrative record

This example highlights fields worth discussing when you design your own contract. Define their meanings, allowed values, and review rules before an application relies on them.

{
  "place_reference": "example-region",
  "place_role": "event_location",
  "source_label": "Example Region",
  "language": "en",
  "topic_ids": [
    "public-policy"
  ]
}

Illustrative schema and example values; adapt them to your data and review process.

Questions about Country Topics API