News Topics APIOrganize the story. Preserve the context.

Separate subjects from developing events

A subject such as public transport can remain useful for years. A particular rail disruption is an event with a time and place. Keep both, but give them different roles. A reader looking for transport policy should not have to navigate an unstructured list of individual incidents.

Use a primary topic to explain the central editorial subject and secondary topics for substantial additional coverage. An incidental mention of a company or politician should not automatically determine the story’s category. Write this distinction into the newsroom’s examples.

Give editors a vocabulary they can maintain

Start with a clear hierarchy and readable scope notes. A broad category can support navigation while a narrower concept improves retrieval. Avoid creating a new permanent topic every time a headline introduces a new phrase.

For established news vocabularies, examine the concept definitions and mappings before adopting labels. Check the applicable terms and your editorial needs. A taxonomy can provide a common starting point, but the way your publication assigns and displays topics still needs its own policy.

Keep publication and event time separate

A report can describe an event that happened before publication, and it may receive a correction afterward. Preserve these distinctions so an archive does not mistake an updated story for a newly occurring event. Use an explicit time zone when recording a timestamp.

Store source identity and story identity as separate fields. Syndicated copies, translations, and follow-up reports may share a subject without being the same document. A topic count should explain whether it measures documents, unique stories, or clusters of related coverage.

Design for corrections and retrieval

A correction can change a named entity, a location, or the central topic. Keep a version history for assignments when those changes affect reader-facing navigation or analytics. Make it possible to withdraw a label without losing the record of why it appeared.

Test retrieval with reader questions, not only isolated documents. Ask whether someone can find the background to a developing event, distinguish opinion from reporting when that metadata exists, and move from one article to a useful subject archive.

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.

{
  "story_id": "example-report",
  "topic_ids": [
    "transport.rail",
    "public-policy"
  ],
  "place_ids": [
    "example-region"
  ],
  "source_id": "example-publisher",
  "content_type": "reporting"
}

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

Questions about News Topics API