# N-gram API
> Generate n-grams from text, with frequency counts — entirely locally. The ngrams endpoint breaks text into contiguous sequences of n tokens and returns each distinct n-gram with how often it occurs, ranked by frequency: word n-grams (unigrams, bigrams, trigrams and beyond) for phrase and collocation analysis, or character n-grams (shingles) for fuzzy matching, language detection and indexing. The range endpoint produces every size from a minimum to a maximum in a single call (for example 1–3 grams), which is exactly what you need to build feature vectors. Choose word or character mode, whether to lower-case first, and a top-N limit to keep only the most frequent. Word tokenization is Unicode-aware and keeps internal apostrophes and hyphens (don't, well-known) as single tokens. Everything runs locally and deterministically, so it is fast and private. Ideal for text mining and NLP feature extraction, language modelling and autocomplete, search indexing and shingling, plagiarism and similarity detection, and keyword and collocation analysis. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This produces n-grams and counts; for extractive summaries and keywords use a summarize API and for grapheme/character counting use a text-segmentation API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/ngram-api/..."
```

## Pricing
- **Free** (Free) — 2,635 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 12,150 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 172,500 calls/Mo, 20 req/s
- **Mega** ($62/Mo) — 905,000 calls/Mo, 50 req/s

## Endpoints

### N-gram

#### `GET /v1/ngrams` — Generate n-grams

**Parameters:**
- `text` (query, required, string) — The text Example: `the cat sat on the cat`
- `n` (query, optional, string) — The n-gram size (default 2) Example: `2`
- `mode` (query, optional, string) — 'word' (default) or 'char'
- `lowercase` (query, optional, string) — lower-case first (default true)
- `top` (query, optional, string) — keep only the N most frequent

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ngram-api/v1/ngrams?text=the+cat+sat+on+the+cat&n=2"
```

**Response:**
```json
{
    "data": {
        "n": 2,
        "mode": "word",
        "total": 5,
        "ngrams": [
            {
                "gram": "the cat",
                "count": 2
            },
            {
                "gram": "cat sat",
                "count": 1
            },
            {
                "gram": "sat on",
                "count": 1
            },
            {
                "gram": "on the",
                "count": 1
            }
        ],
        "unique": 4,
        "token_count": 6
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:03.312Z",
        "request_id": "91f9306e-c691-4cd4-86d2-e61215ff944b"
    },
    "status": "ok",
    "message": "Generate n-grams",
    "success": true
}
```

#### `GET /v1/range` — N-grams for a range of sizes

**Parameters:**
- `text` (query, required, string) — The text Example: `one two three four`
- `min` (query, optional, string) — Smallest size (default 1) Example: `1`
- `max` (query, optional, string) — Largest size (default 3) Example: `3`
- `mode` (query, optional, string) — 'word' or 'char'
- `lowercase` (query, optional, string) — default true
- `top` (query, optional, string) — top-N per size

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ngram-api/v1/range?text=one+two+three+four&min=1&max=3"
```

**Response:**
```json
{
    "data": {
        "max": 3,
        "min": 1,
        "mode": "word",
        "sizes": {
            "1": {
                "total": 4,
                "ngrams": [
                    {
                        "gram": "one",
                        "count": 1
                    },
                    {
                        "gram": "two",
                        "count": 1
                    },
                    {
                        "gram": "three",
                        "count": 1
                    },
                    {
                        "gram": "four",
                        "count": 1
                    }
                ],
                "unique": 4
            },
            "2": {
                "total": 3,
                "ngrams": [
                    {
                        "gram": "one two",
                        "count": 1
                    },
                    {
                        "gram": "two three",
                        "count": 1
                    },
                    {
                        "gram": "three four",
                        "count": 1
                    }
                ],
                "unique": 3
            },
            "3": {
                "total": 2,
                "ngrams": [
                    {
                        "gram": "one two three",
                        "count": 1
                    },
                    {
                        "gram": "two three four",
    
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ngram-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "N-gram API",
        "notes": "Word mode joins tokens with a space; character mode uses Unicode code points with no separator. Ties in frequency are ordered by first appearance. Ideal for text mining, language modelling, autocomplete, plagiarism and similarity features. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/ngrams",
                "params": {
                    "n": "the n-gram size (default 2)",
                    "top": "keep only the N most frequent (default all)",
                    "mode": "'word' (default) or 'char'",
                    "text": "the text (required)",
                    "lowercase": "lower-case first (default true)"
                },
                "returns": "the ranked n-grams with counts"
            },
            {
                "path": "/v1/range",
                "params": {
                    "max": "largest size (default 3)",
                    "min": "smallest size (default 1)",
                    "top": "top-N per size",
                    "mode": "'word' or 'char'",
                    "text": "the text (required)",
                    "lowercase": "default true"
                },
                "returns": "n-grams grouped by size"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Genera
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/ngram-api
OpenAPI spec: https://www.oanor.com/api/ngram-api/openapi.json