Metadata¶
Agate generates metadata at several levels.
At the Article level, Agate can generate arbitrary metadata, including classifications for subject, topics, user needs and more. Some of these are available as presets in Agate enrichment nodes. Others can be defined by the user.
At the Mention level, Agate uses a preset taxonomy to classify a number of attributes, such as the nature of the mention (is it central to the story vs. just context, etc.) and whether it is a direct quote. These taxonomies are fixed.
At the Entity level, Stylebook allows for a mix: both fixed taxonomies to identify the type of entity (ex. a politician vs. a community member, in the case of people) and arbitrary, user-assigned metadata. Connections between entities also have their own arbitrary edge labels, known as the "nature" of a connection.
Three families¶
| Family | What it describes | Where it appears | Reference |
|---|---|---|---|
| Article Meta | Story format, broad topics, concrete subject | metadata[] on articles; article-metadata filters |
Article Meta |
| Mention Meta | Editorial role of an entity in one story | Mention and hub responses; mention/entity article filters | Mention Meta |
| Entity Meta | People, organization and place types | Canonical records; mention rows; entity search filters | Entity Meta |
Discover values in your project¶
Often the best place to start is to discover the metadata values available in your project. These endpoints can help:
| You need | Endpoint | Doc |
|---|---|---|
| Metadata types and values in project data | GET …/articles/metadata/types, GET …/articles/metadata/types/{meta_type}/values |
Article Meta |
| Article search filter UI in one call | GET …/articles/facets |
Article facets |
| Mention search filter UI in one call | GET …/mentions/facets |
Mention facets |
person_type in Stylebook |
GET …/people/types |
People types |
organization_type in Stylebook |
GET …/organizations/types |
Organizations types |
location_type in Stylebook |
GET …/locations/types |
Locations types |
Article facets and Mention facets are convenience wrappers — one response with the filter values frontend applications typically need. Use the …/metadata/types routes or entity types endpoints when you need finer-grained or type-specific discovery.
Advanced metadata filtering uses meta clauses on every article-metadata filter endpoint — List and search, Semantic search, Geographic search, Geo cells, and List and search mentions. See Article Meta for grammar and transport (GET query params vs POST JSON array).
Quick filter map¶
Once you know your available metadata values, you can use them to search for articles using filters like the ones below.
| Filter parameter | Metadata page |
|---|---|
meta (repeatable on article-metadata filter endpoints) |
Article Meta |
nature (on mentions) |
Mention Meta |
person_type |
Entity Meta → People |
organization_type |
Entity Meta → Organizations |
location_type |
Entity Meta → Locations |