Stránkovanie výsledkov API

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

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

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

Pre podrobný popis parametrov vyhľadávania pozri GET /v1/search.