Skip to main content
Custom Tags applies your organization’s taxonomy to news articles automatically, letting you filter and retrieve content using your own classification system rather than generic categories.
Each taxonomy is organization-specific and tied to your API key. Your classification system is not shared with or visible to other organizations.

​
Classification pipeline

Custom Tags uses a machine learning pipeline to classify articles against your taxonomy. The pipeline runs in four stages:
  1. Taxonomy ingestion — NewsCatcher’s engineering team works with you to understand your domain, tag definitions, and any additional context or examples needed for accurate classification.
  2. Model training — a large language model (LLM) is fine-tuned on your enriched taxonomy using a diverse dataset of news articles, capturing the nuances of your classification requirements.
  3. Production deployment — the classifier is integrated into the NLP pipeline and applied to all incoming articles automatically. Historical articles processed since implementation remain available.
  4. Continuous improvement — the model is monitored and retrained regularly to maintain accuracy as news trends evolve.

​
API integration

Custom Tags is available on the following endpoints:
  • /search
  • /latest_headlines
  • /authors

​
Request format

Use the custom_tags parameter to filter articles by taxonomy tag, following this pattern: 
custom_tags.<taxonomy>: "Tag1,Tag2,Tag3"
where <taxonomy> is your taxonomy name and Tag1,Tag2,Tag3 are the tags to filter by. For POST requests, you can pass tags as a comma-separated string or an array of strings. For GET requests, use a comma-separated string. 
curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "custom_tags.my_taxonomy": ["Tag1", "Tag2", "Tag3"]
  }'

​
Response format

Each article in the response includes a custom_tags field containing the matching tags from your taxonomy: 
{
  "status": "ok",
  "total_hits": 1500,
  "articles": [
    {
      "title": "Example Article Title",
      "custom_tags": {
        "my_taxonomy": ["Tag1", "Tag2"]
      }
    }
  ]
}
Custom tags in responses are always returned as an array of strings, regardless of the format used in the request.

​
Best practices

  • Use exact tag names — tag matching is case-sensitive.
  • Keep tag names unambiguous and consistent across your taxonomy to reduce misclassification.
  • Combine custom_tags with other parameters such as q, lang, and from_ to narrow results before applying tag filters.
  • Test with broader tag sets first, then narrow based on result quality.

​
See also