v1 · viešas API

Apklausų API dokumentacija

Partnerių API leidžia gauti Speju apklausas, jų rezultatus ir registruoti lankytojų balsus savo svetainėje. Atsakymai — JSON, CORS įjungtas visiems domenams.

Bazinis URL

https://speju.com/api/public/v1

Autentifikacija

Antraštė x-api-key arba Authorization: Bearer

Limitai

Grąžinamos X-RateLimit-* antraštės

Greitas startas

curl -H "x-api-key: JŪSŲ_RAKTAS" \
  "https://speju.com/api/public/v1/polls?limit=5&category=rinkimai"

Endpoint'ai

GET/polls120 užklausų / min.

Visų aktyvių apklausų sąrašas, rikiuojamas pagal publikavimo datą.

Query parametrai

category(string)— Filtras pagal kategoriją (pvz. politika, rinkimai)

tag(string)— Filtras pagal žymą (pvz. meru-vilnius)

municipality(string)— Savivaldybės slug (atitinka žymą meru-{slug})

search(string)— Paieška apklausos klausime

limit(integer)— 1–100, numatyta 50

offset(integer)— Puslapiavimo poslinkis

includeResults(boolean)— false — negrąžinti rezultatų (greičiau)

Atsakymas

{
  "api": "speju",
  "version": "v1",
  "count": 1,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id": "uuid",
      "slug": "ar-balsuotumete-uz-dabartini-kauno-mera",
      "question": "Ar balsuotumėte už dabartinį Kauno merą?",
      "description": "Kontekstas apie apklausą",
      "category": "rinkimai",
      "type": "binary",
      "image": "https://speju.com/...jpg",
      "options": [
        { "id": "0", "label": "Taip" },
        { "id": "1", "label": "Ne" }
      ],
      "results": {
        "totalVotes": 123,
        "options": [
          { "optionId": "0", "label": "Taip", "votes": 80, "percent": 65 },
          { "optionId": "1", "label": "Ne", "votes": 43, "percent": 35 }
        ]
      },
      "publishedAt": "2026-05-01T09:00:00Z",
      "closesAt": null,
      "status": "open",
      "tags": ["rinkimai", "meru-kaunas"],
      "person": null,
      "municipality": { "slug": "kaunas", "name": "Kaunas" },
      "spejuUrl": "https://speju.com/apklausa/..."
    }
  ]
}

GET/polls/{slug}120 užklausų / min.

Vienos apklausos duomenys. Vietoje slug galima naudoti ir apklausos UUID.

Atsakymas

{
  "api": "speju",
  "version": "v1",
  "data": { /* toks pat objektas kaip sąraše */ }
}

GET/polls/{slug}/results240 užklausų / min.

Tik balsavimo rezultatai — patogu dažnam atnaujinimui.

Atsakymas

{
  "api": "speju",
  "version": "v1",
  "pollId": "uuid",
  "slug": "...",
  "results": {
    "totalVotes": 123,
    "options": [
      { "optionId": "0", "label": "Taip", "votes": 80, "percent": 65 },
      { "optionId": "1", "label": "Ne", "votes": 43, "percent": 35 }
    ]
  }
}

POST/polls/{slug}/votes60 užklausų / min.

Balsavimas. Balsas anoniminis, susiejamas su lankytojo IP maiša. Pakartotinis balsas pakeičia ankstesnį.

Užklausos kūnas

{
  "optionId": "0"
}

Atsakymas

{
  "api": "speju",
  "version": "v1",
  "pollId": "uuid",
  "slug": "...",
  "changed": false,
  "results": {
    "totalVotes": 124,
    "options": [
      { "optionId": "0", "label": "Taip", "votes": 81, "percent": 65 },
      { "optionId": "1", "label": "Ne", "votes": 43, "percent": 35 }
    ]
  }
}

Klaidų kodai

400Netinkamas JSON arba neteisingas optionId

401Trūksta arba neteisingas x-api-key

404Apklausa nerasta

409Apklausa uždaryta arba pasibaigusi

429Viršytas užklausų limitas

500Serverio klaida

Pastabos

optionId — indeksas eilutės pavidalu („0“, „1“, …), atitinkantis options masyvo tvarką.
Dvinarėse apklausose „0“ = Taip, „1“ = Ne.
Procentai suapvalinami taip, kad suma visada būtų 100.
Balsai iš partnerių svetainių žymimi šaltiniu, todėl juos galima atskirti nuo Speju balsų.
API raktą išduoda Speju komanda; jį saugokite tik serverio pusėje.