openapi: 3.1.0
info:
  title: Zagreb Gradski atlas API
  version: 1.4.0
  description: |
    Javni HTTP API Gradskog atlasesa. Podaci: Grad Zagreb, Otvorena dozvola (OD).
    Kôd: MIT. Rate limit po IP (vidi `/api/katalog` → `rateLimit`).
  contact:
    name: Zagreb Gradski atlas
    url: https://zg-atlas.lakehouse.hr/vodic#kontakt
  license:
    name: MIT (kôd) · Otvorena dozvola OD (podaci)
servers:
  - url: https://zg-atlas.lakehouse.hr
    description: Produkcija
  - url: http://127.0.0.1:3200
    description: Lokalni razvoj
tags:
  - name: meta
  - name: geo
  - name: pretraga
  - name: energija
paths:
  /api/katalog:
    get:
      tags: [meta]
      summary: Katalog skupova (DCAT-nalik)
      operationId: getKatalog
      responses:
        "200":
          description: Katalog + version, openapi, rateLimit, api[], dataset[]
          content:
            application/json:
              schema:
                type: object
                required: [version, openapi, rateLimit, api, dataset]
                properties:
                  version: { type: string, example: "1.4.0" }
                  openapi: { type: string, format: uri }
                  rateLimit: { type: object }
                  api: { type: array, items: { type: object } }
                  dataset: { type: array, items: { type: object } }
  /api/zdravlje:
    get:
      tags: [meta]
      summary: Operativno stanje ingesta
      operationId: getZdravlje
      responses:
        "200":
          description: Bez tajni; nije rate-limitiran
  /api/trazi:
    get:
      tags: [pretraga]
      summary: Pretraga četvrti, MO i objekata
      operationId: getTrazi
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string, minLength: 2 }
          example: ljekarna
        - name: cetvrt
          in: query
          schema: { type: string }
          example: maksimir
      responses:
        "200":
          description: { pogoci: [...] }
  /api/sloj/{sifra}:
    get:
      tags: [geo]
      summary: GeoJSON ili CSV sloja
      operationId: getSloj
      parameters:
        - name: sifra
          in: path
          required: true
          schema: { type: string }
          example: prometnice
        - name: format
          in: query
          schema: { type: string, enum: [csv, download] }
        - name: bbox
          in: query
          description: w,s,e,n — za gtfs_rute, bic_staze, ulice, pjesacke_zone
          schema: { type: string }
          example: "15.95,45.80,16.00,45.82"
      responses:
        "200":
          description: FeatureCollection ili CSV
        "404":
          description: Nepoznat sloj
  /api/tablica/{sifra}:
    get:
      tags: [geo]
      summary: Tablični skup
      operationId: getTablica
      parameters:
        - name: sifra
          in: path
          required: true
          schema: { type: string }
        - name: format
          in: query
          schema: { type: string, enum: [csv] }
      responses:
        "200":
          description: JSON ili CSV
  /api/blizina:
    get:
      tags: [geo]
      summary: Točke u krugu
      operationId: getBlizina
      parameters:
        - name: lon
          in: query
          required: true
          schema: { type: number }
          example: 15.98
        - name: lat
          in: query
          required: true
          schema: { type: number }
          example: 45.81
        - name: m
          in: query
          schema: { type: integer, minimum: 80, maximum: 2000, default: 400 }
        - name: n
          in: query
          schema: { type: integer, minimum: 1, maximum: 40, default: 8 }
        - name: osim
          in: query
          schema: { type: string }
      responses:
        "200":
          description: { lon, lat, metara, objekti }
        "400":
          description: Neispravne koordinate
  /api/presjek:
    get:
      tags: [geo]
      summary: Presjek zatvaranja i staza/zona
      operationId: getPresjek
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: { presjeci }
  /api/izvoz/cetvrt/{slug}:
    get:
      tags: [geo]
      summary: Izvoz dosjea četvrti
      operationId: izvozCetvrt
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          example: maksimir
        - name: format
          in: query
          schema: { type: string, enum: [csv, geojson], default: csv }
      responses:
        "200":
          description: CSV ili GeoJSON
        "404":
          description: Nepoznata četvrt
  /api/izvoz/energija/{id}:
    get:
      tags: [energija]
      summary: CSV mjesečne potrošnje ISGE objekta
      operationId: izvozEnergija
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: CSV
        "404":
          description: Nepoznat objekt
  /api/podloga/ortofoto/{z}/{x}/{y}:
    get:
      tags: [geo]
      summary: XYZ ortofoto pločica (Zagreb)
      operationId: getOrtofoto
      parameters:
        - name: z
          in: path
          required: true
          schema: { type: integer, minimum: 8, maximum: 19 }
        - name: x
          in: path
          required: true
          schema: { type: integer }
        - name: y
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: image/jpeg (prazna 1×1 izvan Zagreba)
components:
  responses:
    RateLimited:
      description: 429 Previše zahtjeva
      headers:
        Retry-After:
          schema: { type: integer }