Segmentation API

Segmentation endpoints aggregate matching posts by a field and return counts instead of the posts themselves. Use them to see the top sites, languages, countries, or entities for a query before (or instead of) fetching content - a quick, cheap way to size up a topic.

Endpoints

GET

https://api.webz.io/seg_api/news
https://api.webz.io/seg_api/blogs
https://api.webz.io/seg_api/forums

Example

Top languages for posts mentioning bitcoin:

https://api.webz.io/seg_api/news?token=YOUR_TOKEN&q=bitcoin&field=language

{
  "segmentation": [
    {
      "language": "english",
      "num_docs": 8341
    },
    {
      "language": "spanish",
      "num_docs": 1220
    }
  ],
  "next": "/seg_api/news?ts=1751713632000&q=bitcoin&field=language&from=10",
  "total_results": 34,
  "more_results_available": 24,
  "requests_left": 988
}

Parameters

Aggregation fields

thread.site, thread.site_suffix, thread.site_full, thread.site_section, thread.site_type, thread.country, thread.url, thread.licensing_agency, author, language, site_category, sentiment, category, rating, published, locations, persons, person.positive, person.negative, person.neutral, organizations, organization.positive, organization.negative, organization.neutral, trust.bias, trust.category, trust.source.type, trading_symbol.ticker, trading_symbol.exchange

The topic field is available only on the News segmentation endpoint. The sentiment and entity fields (sentiment, persons, locations, organizations, person.*, organization.*, trading_symbol.*) also aggregate meaningfully only on news - these enrichments are only relevant to news content.

field=published returns a per-day histogram with yyyy-MM-dd keys.

Limits

• Up to 10 buckets per response; follow next (or raise from) for more.
• Up to 100 buckets in total per query.
• The window can start at most 31 days back; older ts values fall back to the 3-day default. allowNewsHistory does not apply.
• Each request costs 1 credit.