# Segmentation API

The segmentation endpoint aggregates matching reviews by a field and returns counts instead of the reviews themselves - a quick way to see top sites, languages, or the rating distribution for a query.

## Endpoint

`GET`

```bash
https://api.webz.io/reviewSeg
```

`/seg_api/reviews` is an alias of the same endpoint.

## Example

Top languages for reviews of a product:

```bash
https://api.webz.io/reviewSeg?token=YOUR_TOKEN&q="acme blender"&field=language
```

```json
{
  "segmentation": [
    { "language": "english", "num_docs": 812 },
    { "language": "spanish", "num_docs": 120 }
  ],
  "requestsLeft": 988,
  "totalResults": 6,
  "moreResultsAvailable": 0,
  "next": "/reviewSeg?token=YOUR_TOKEN&ts=1751536320000&q=%22acme+blender%22&field=language&from=6"
}
```

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `token` | string | - | Your API token |
| `q` | string | `""` | Same query syntax as search - see [Query Syntax](reviews-api-query-syntax) |
| `field` | string | - | Field to aggregate by - see below |
| `ts` | integer | 3 days ago | Start of the window, Unix milliseconds. Reaches back at most 31 days |
| `from` | integer | `0` | Offset into the buckets; each page returns up to 10 |

## Aggregation fields

`item.site`, `item.site_suffix`, `item.site_full`, `item.site_type`, `item.country`, `item.published`, `author`, `published`, `language`, `site_category`, `rating`

Any other field returns `400 Invalid field`.

`published` and `item.published` return 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.
- Each request costs 1 credit.