# Stránkovanie

`GET /v1/search` používa cursor stránkovanie. Každá odpoveď obsahuje najviac `limit` výsledkov (predvolene 10, maximum 50).

Jeden dopyt vráti naprieč stránkami najviac **250 výsledkov**. Endpoint slúži na vyhľadávanie, nie na hromadný export.

## Ako funguje cursor stránkovanie

Keď existujú ďalšie výsledky, odpoveď obsahuje pole `next_cursor` s hodnotou (nie `null`). Tento cursor pošlite späť ako parameter `cursor` v nasledujúcom requeste. API vráti ďalšiu stránku výsledkov pre rovnaký dopyt.

Keď je `next_cursor` rovný `null`, ďalšia stránka neexistuje. To ešte neznamená, že máte všetky zhody: ak je na poslednej stránke `truncated: true`, zhôd je viac ako 250 a treba spresniť dopyt.

**Dôležité:** Cursor je platný 15 minút od jeho vytvorenia. Po uplynutí tohto času vráti API chybu `invalid_request` s popisom "Expired cursor". Stačí zopakovať pôvodný dopyt od začiatku.

Cursor tiež viaže na konkrétne parametre `q`, `country`, `prefer`, `entity_type` a `limit`. Ak zmeníte ktorýkoľvek z nich, musíte začať nové stránkovanie bez cursora.

## JavaScript príklad

```js
async function fetchAllResults(query, country = "sk") {
  const base = "https://api.subjekt.sk/v1/search";
  let cursor = null;
  const allResults = [];

  do {
    const params = new URLSearchParams({ q: query, country, limit: "50" });
    if (cursor) params.set("cursor", cursor);

    const res = await fetch(`${base}?${params}`);
    if (!res.ok) {
      const err = await res.json();
      throw new Error(`API chyba: ${err.code} — ${err.message}`);
    }

    const data = await res.json();
    if (data.truncated) throw new Error("Viac ako 250 zhôd, spresnite dopyt");
    allResults.push(...data.results);
    cursor = data.next_cursor;
  } while (cursor !== null);

  return allResults;
}

// Použitie
const firmy = await fetchAllResults("tesla");
console.log(`Celkom: ${firmy.length} výsledkov`);
```

## Python príklad

```python
import requests

def fetch_all_results(query: str, country: str = "sk") -> list:
    base = "https://api.subjekt.sk/v1/search"
    cursor = None
    all_results = []

    while True:
        params = {"q": query, "country": country, "limit": 50}
        if cursor:
            params["cursor"] = cursor

        r = requests.get(base, params=params, timeout=10)
        r.raise_for_status()
        data = r.json()
        if data.get("truncated"):
            raise ValueError("Viac ako 250 zhôd, spresnite dopyt")

        all_results.extend(data["results"])
        cursor = data.get("next_cursor")

        if cursor is None:
            break

    return all_results

# Použitie
firmy = fetch_all_results("tesla")
print(f"Celkom: {len(firmy)} výsledkov")
```

## Zhrnutie

| Správanie | Detail |
|---|---|
| Maximálny `limit` | 50 výsledkov na stránku |
| Predvolený `limit` | 10 výsledkov na stránku |
| Expirácia cursora | 15 minút |
| Koniec výsledkov | `next_cursor` je `null` |
| Maximálny offset | 250 výsledkov; pri ďalších zhodách `truncated: true` |

Pre podrobný popis parametrov vyhľadávania pozri [GET /v1/search](./api/search.md).