# LPT Parkirišča API

Različica 1.0.0 · Zadnja sprememba: 2. 10. 2026

API vrača trenutno zasedenost parkirišč LPT. Podatki se osvežijo približno vsakih 5 minut.

## Dostop

Za uporabo API-ja potrebujete žeton (API token). Zanj pišite na **[mak@cnj.si](mailto:mak@cnj.si)** in navedite:

- ime organizacije ali aplikacije,
- kontaktno osebo,
- ali potrebujete tudi zgodovinske podatke.

Žeton pošljite v glavi `Authorization` vsake zahteve:

```
Authorization: Bearer VAŠ_ŽETON
```

Žetona ne delite z drugimi in ga ne objavljajte v javni kodi.

## Trenutna zasedenost

```
GET https://lpt-parking.cj.si/api/v1/parking-lots
```

Primer zahteve:

```bash
curl https://lpt-parking.cj.si/api/v1/parking-lots \
  -H "Authorization: Bearer VAŠ_ŽETON"
```

Primer odgovora:

```json
{
  "updated_at": "2026-10-02T14:30:00+02:00",
  "is_stale": false,
  "parking_lots": [
    {
      "parkirisce_id": 3,
      "parkirisce": "Tivoli I",
      "dnevni": { "na_voljo": 346, "zasedeno": 341, "prosto": 5 },
      "abonenti": { "na_voljo": 6, "oddano": 29, "aktivni": 60, "prosto": 0 },
      "stevec": 341
    }
  ]
}
```

| Polje               | Opis                                                                 |
| ------------------- | -------------------------------------------------------------------- |
| `updated_at`        | Čas zadnjih podatkov.                                                |
| `is_stale`          | `true`, če podatki niso bili osveženi več kot 15 minut. |
| `parkirisce_id`     | Oznaka parkirišča.                                                   |
| `parkirisce`        | Ime parkirišča.                                                      |
| `dnevni.na_voljo`   | Mesta za dnevne uporabnike.                                          |
| `dnevni.zasedeno`   | Zasedena mesta dnevnih uporabnikov.                                  |
| `dnevni.prosto`     | Prosta mesta za dnevne uporabnike.                                   |
| `abonenti.na_voljo` | Mesta za abonente.                                                   |
| `abonenti.oddano`   | Oddani abonmaji.                                                     |
| `abonenti.aktivni`  | Aktivni abonenti.                                                    |
| `abonenti.prosto`   | Prosta mesta za abonente.                                            |
| `stevec`            | Stanje števca.                                                       |

## Zgodovinski podatki

Na voljo samo z žetonom, ki ima dostop do zgodovinskih podatkov. Dostop zahtevate na [mak@cnj.si](mailto:mak@cnj.si).

```
GET https://lpt-parking.cj.si/api/v1/history?date=LLLL-MM-DD
```

Vrne vse zapise za izbrani dan, od 00:00 do 24:00 po ljubljanskem času.

Primer zahteve:

```bash
curl "https://lpt-parking.cj.si/api/v1/history?date=2026-10-01" \
  -H "Authorization: Bearer VAŠ_ŽETON"
```

Primer odgovora:

```json
{
  "date": "2026-10-01",
  "snapshots": [
    {
      "captured_at": "2026-10-01T00:00:00+02:00",
      "parking_lots": [
        {
          "parkirisce_id": 3,
          "parkirisce": "Tivoli I",
          "dnevni": { "na_voljo": 346, "zasedeno": 120, "prosto": 226 },
          "abonenti": { "na_voljo": 6, "oddano": 29, "aktivni": 12, "prosto": 0 },
          "stevec": 120
        }
      ]
    }
  ]
}
```

Vsak zapis v `snapshots` ima enaka polja kot trenutna zasedenost.

## Časi

Vsi časi so v ljubljanskem času, v obliki ISO 8601 (npr. `2026-10-02T14:30:00+02:00`).

## Napake

| Koda  | Pomen                                             |
| ----- | ------------------------------------------------- |
| `401` | Žeton manjka, je napačen, potekel ali izklopljen. |
| `403` | Žeton nima dostopa do zgodovinskih podatkov.      |
| `422` | Napačen datum. Uporabite obliko `LLLL-MM-DD`.     |

Primer napake:

```json
{ "message": "Missing, invalid, expired or inactive API token." }
```

## Priporočila

- Podatki se osvežijo približno vsakih 5 minut, zato API ne kličite pogosteje kot enkrat na minuto.
- Odgovori vsebujejo glavo `ETag`. Če jo pošljete nazaj v glavi `If-None-Match`, dobite odgovor `304` brez vsebine, kadar se podatki niso spremenili.

## Kontakt

Za žetone, dostop do zgodovinskih podatkov in vprašanja pišite na [mak@cnj.si](mailto:mak@cnj.si).