# Izvori geografskih podataka

Ovaj direktorijum sadrži razvojne snimke podataka od kojih se generiše kompaktan,
statički SVG model za interaktivnu mapu. Aplikacija ne poziva kartografske servise
u runtime-u.

## Granice Srbije (ADM2)

- Fajl: `serbia-municipalities-geoboundaries.geojson`
- Izvor: [geoBoundaries gbOpen API — SRB/ADM2](https://www.geoboundaries.org/api/current/gbOpen/SRB/ADM2/)
- Obim lokalnog snimka: 145 poligona iz pojednostavljenog GeoJSON izdanja;
  agregatni poligon Beograda se pri generisanju zamenjuje gradskim opštinama ispod,
  pa u konačni nacionalni sloj ulaze 144 ostala `SRB/ADM2` poligona.
- Metapodaci korišćenog izdanja navode OpenStreetMap/Wambacher kao izvor,
  ODbL 1.0 kao licencu granica, referentnu godinu 2017. i geoBoundaries build 2023.
- Ovaj skup određuje obim i geometriju prikaza; nije zamena za službenu katastarsku
  ili pravnu granicu.

U ovom ADM2 skupu Beograd je jedan agregatni poligon. Generator ga ne prikazuje kao
jednu oblast, već ga zamenjuje sa 17 gradskih opština iz zasebnog OSM snimka.

Pri objavljivanju prikaza zadržati atribuciju: **geoBoundaries; © OpenStreetMap
contributors, ODbL 1.0**. Videti i [OpenStreetMap copyright and
license](https://www.openstreetmap.org/copyright).

## Gradske opštine Beograda

- Snimak: `belgrade-city-municipalities-overpass.json`
- Reprodukovan upit: `belgrade-city-municipalities.overpass`
- Izvor: OpenStreetMap preko
  [Overpass API-ja](https://overpass-api.de/api/interpreter).
- OSM timestamp: `2026-09-04T06:57:33Z`.
- SHA-256 snimka:
  `ee6a2d622c04c5140e977776838ee4ffef3e28ca9fd477fce9c3673f0fd1860f`.
- Licenca: [Open Data Commons Open Database License
  1.0](https://opendatacommons.org/licenses/odbl/1-0/); atribucija **©
  OpenStreetMap contributors** je obavezna.

Upit bira tačno 17 verzionisanih OSM administrativnih relacija:

```overpass
[out:json][timeout:180];
rel(id:2027114,2223784,3059654,3059655,3065610,3065611,3065612,3085424,3085749,3085750,5731335,5892891,6930224,7727516,7728561,7737268,7737269);
out body geom;
```

Relacije predstavljaju Barajevo, Voždovac, Vračar, Grocku, Zvezdaru, Zemun,
Lazarevac, Mladenovac, Novi Beograd, Obrenovac, Palilulu, Rakovicu, Savski venac,
Sopot, Stari grad, Surčin i Čukaricu. U nacionalnom sloju one zamenjuju jedan
agregatni `SRB/ADM2` poligon Beograda, pa Srbija van `XKX` dodatka ima 161 oblast
(`144 + 17`).

Ovaj OSM snimak je otvoren i pogodan za razvojni prikaz, ali **nije službena,
katastarska niti pravno merodavna granica**. Sirovi snimak, upit, timestamp i hash
čuvaju se radi ponovljivosti; za službeni prikaz i dalje je potreban verifikovan
RGZ/RPJ izvor sa eksplicitnim pravom redistribucije.

## Kosovo i Metohija — privremeni otvoreni izvor (ADM2)

- Fajl: `kosovo-municipalities-geoboundaries.geojson`
- Sačuvani metapodaci: `kosovo-municipalities-geoboundaries-meta.json`
- Izvor: [geoBoundaries gbOpen API — XKX/ADM2](https://www.geoboundaries.org/api/current/gbOpen/XKX/ADM2/)
- Obim lokalnog pojednostavljenog snimka: 38 poligona; referentna godina 2017,
  izvor OpenStreetMap/Wambacher, geoBoundaries build 12. decembar 2023.
- Licenca koju navodi sačuvani geoBoundaries odgovor: [Creative Commons
  Attribution-ShareAlike 2.0](https://creativecommons.org/licenses/by-sa/2.0/).

Ovaj otvoreni skup se spaja sa 144 ostala `SRB/ADM2` poligona i 17 gradskih
opština Beograda pre zajedničke projekcije, tako da nacionalni SVG obuhvata i
Kosovo i Metohiju. Kombinovani razvojni model ima 199 oblasti (`144 + 17 + 38`),
a generator proverava jedinstvene ID-jeve/slugove i južni geografski obuhvat.

Ovo je **privremeni, neslužbeni fallback**, nije katastarski niti pravno precizan
izvor i ne sme se predstavljati kao „100% tačna“ ili službena granica. Generator
namerno izoluje ulazni GeoJSON, pa se geometrija može zameniti verifikovanim
RGZ/RZS izvorom bez promene ugovora koji koriste UI komponente. Pri objavljivanju
zadržati atribuciju **geoBoundaries; OpenStreetMap/Wambacher contributors; CC
BY-SA 2.0** i proveriti kompatibilnost svih obaveza kombinovanih izvora.

## Nazivi i šifre opština

- Fajl: `serbia-municipalities-rzs.json`
- Izvor: zvanični portal [Otvoreni podaci opština Srbije](https://opstine.data.gov.rs/)
  / Republički zavod za statistiku.
- Lokalna polja: `idjezik`, `MBOPS`, `nOPS`, `IDNSTJ`.
- Generator koristi samo službenu šifru `MBOPS` i naziv `nOPS`; ne koristi ovaj
  fajl kao izvor granica.

Za XKX geometrije generator koristi RZS naziv i `MBOPS` samo kada se red direktno
mapira na istu opštinu. Novije/podeljene oblasti bez odgovarajućeg reda dobijaju
stabilan `XKX:` ID i eksplicitno mapiran srpski latinični naziv za prikaz; ti ručno
mapirani nazivi se ne predstavljaju kao zaseban službeni izvor.

Tačan URL JSON endpointa nije sačuvan uz ovaj razvojni snimak, pa ga treba
zabeležiti pre sledećeg produkcionog osvežavanja umesto nagađanja endpointa.

## Statističke oblasti (NSTJ 3)

- Fajl: `serbia-regions-rzs.json`
- Izvor: Republički zavod za statistiku, skup `NSTJ`, latinično izdanje
  (`idjezik=2`).
- Endpoint:
  `https://opendata.stat.gov.rs/data/WcfJsonRestService.Service1.svc/dataset/NSTJ/2/json`
- Datum razvojnog preuzimanja: 4. septembar 2026.
- Lokalna polja: `IDNSTJ`, `nNSTJ`, `nivo` i `idjezik`.

Generator koristi 30 zapisa nivoa NSTJ 3 za službene nazive i grupisanje opština
u prvi nivo interaktivne mape. Granice oblasti nisu poseban izvor geometrije:
prikaz je tačna unija postojećih opštinskih SVG putanja, pa između nivoa ne nastaju
vizuelne praznine ili preklapanja. Pri ponovnoj upotrebi RZS podataka navesti izvor,
datum preuzimanja i sve izvršene izmene.

## Naselja opštine Surčin

- Fajl: `surcin-settlements-overpass.json`
- Reprodukovan upit: `surcin-settlements.overpass`
- Izvor: OpenStreetMap preko Overpass API-ja.
- OSM timestamp u lokalnom odgovoru: `2026-09-03T11:33:06Z`.
- Licenca: [Open Data Commons Open Database License
  1.0](https://opendatacommons.org/licenses/odbl/1-0/); atribucija **©
  OpenStreetMap contributors** je obavezna.

Snimak sadrži tačno sedam administrativnih relacija naselja: Bečmen, Boljevci,
Dobanovci, Jakovo, Petrovčić, Progar i Surčin. `surcin-settlements-overpass-meta.json`
je pomoćni snimak tagova/centara; generator koristi puni odgovor sa geometrijom.

## Granice naselja van Surčina — nacionalni OSM snimak

- Fajlovi: `serbia-settlement-tags-osm.json`,
  `serbia-settlement-boundaries-osm.json.gz` i odgovarajući `-meta.json`.
- Izvor: [OpenStreetMap, javni VK Maps Overpass servis](https://maps.mail.ru/osm/tools/overpass/api/interpreter).
- OSM stanje: `2026-09-05T20:15:02Z`; svi upiti geometrije koriste isti datum.
- Snimak sadrži 4.721 administrativnu relaciju sa `ref:RS:naselje`. Generator
  povezuje naselja isključivo preko ove šifre i RZS polja `MBNAS`.
- Licenca: [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/), uz atribuciju
  **© OpenStreetMap contributors**. Poreklo uvoza granica opisuje
  [OSM Serbia/RGZ Import](https://wiki.openstreetmap.org/wiki/Serbia/RGZ_Import).
  OSM je otvoreni izvedeni izvor; prikaz nije službena katastarska granica.

Preuzimanje je razvojna operacija, nikada zahtev iz pregledača posetioca:

```powershell
node scripts/fetch-settlement-boundaries.mjs
```

Skripta nastavlja keširane grupe od 100 relacija u `.impeccable/review/geography`.
Konačni gzip čuva izvorne tagove i geometriju; metapodaci sadrže sve izvršene
upite i datum preuzimanja. Za novo vremensko izdanje prvo sačuvati novi snimak
tagova pod kontrolom verzija; običan ponovni prolaz obnavlja isto izdanje.

Generator spaja stvarne spoljne i unutrašnje prstenove, odbija otvorene ili
prazne granice i pojednostavljuje zajedničke OSM puteve samo jednom. Tolerancija
je 0,02 nacionalne SVG jedinice, približno 18 metara; krajnje tačke puteva ostaju
zajedničke. Oznake su površinski centroidi ili proverene unutrašnje tačke
konkavnih poligona. Za sedam surčinskih naselja ostaje prethodno proverena
geometrija. Za iscrtavanje rupa obavezan je `fillRule="evenodd"`.

## Tačke naselja iz ASK spiska

- `kosovo-places-geonames.txt.gz`: originalni `XK.txt` iz
  [dnevnog GeoNames izvoza](https://download.geonames.org/export/dump/XK.zip).
- Metapodaci: `kosovo-places-geonames-meta.json`.
- Licenca: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), atribucija
  **GeoNames**; [format i ograničenja](https://download.geonames.org/export/dump/readme.txt).

Koriste se samo stvarne WGS84 koordinate naseljenih mesta (klasa `P`). Poklapanje
zahteva isti normalizovani naziv ili zabeleženi alternativni naziv i položaj
unutar postojeće opštine. Višeznačni nazivi se ne spajaju automatski.
`kosovo-settlement-geonames-matches.json` beleži tri posebno pregledana
poklapanja sa tačnim glavnim nazivom, uz istu prostornu proveru.

`kosovo-settlement-points-osm.json` sadrži dodatni verifikovani OSM čvor grada
Severna Kosovska Mitrovica, `node/5830684024`, sa identičnim albanskim nazivom
ASK zapisa. To je stvarni čvor `place=town`, ne centroid administrativne opštine.

Tačke označavaju položaj naselja i **nisu granice**. Nema nasumičnih koordinata,
veštačkih poligona niti razmeštanja radi popunjavanja mape. Naselja bez pouzdanog
poklapanja ostaju samo u spisku. Izvorni ASK podaci ostaju neizmenjeni, a zapisi
sa doslovnim `null`, donjom crtom umesto slova ili pokvarenim mešanim kodiranjem
izostavljaju se iz prikaza. `../settlement-coverage.json` čuva njihove ID-jeve,
nepozicionirana naselja i korišćene GeoNames/OSM identifikatore.

## Nazivi naselja po opštinama

- Fajl: `serbia-settlements-rzs.json`
- Izvor: Republički zavod za statistiku, skup `SIFNAS`, latinično izdanje (`idjezik=2`).
- Endpoint: `https://opendata.stat.gov.rs/data/WcfJsonRestService.Service1.svc/dataset/SIFNAS/2/json`
- Lokalna polja: `MBNAS`, `nNAS`, `MBOPS` i `idjezik`.

Snimak se osvežava i validira komandom:

```powershell
node scripts/fetch-serbia-settlements.mjs
```

Za 38 opština na Kosovu i Metohiji koristi se i
`kosovo-settlements-ask.json`, reproducibilan snimak zvaničnih ASK PxWeb tabela
„Stanovništvo i domaćinstva po naseljima“. Njihov trenutni administrativni raspored
pokriva nove opštine koje stariji RZS šifarnik još vodi pod prethodnim roditeljem.
Snimak se osvežava komandom:

```powershell
node scripts/fetch-kosovo-settlements.mjs
```

Nazivi su informativni podaci za navigaciju. Granice naselja se prikazuju samo
gde postoji zasebno proverena geometrija; spiskovi naselja se ne predstavljaju kao
izvor poligona.

## Generisani izlaz

Pokrenuti iz korena projekta:

```powershell
node src/lib/geography-build.mjs
node src/lib/geography-check.mjs --files
```

Skripta koristi samo Node.js standardnu biblioteku, spaja OSM segmente u zatvorene
poligone, projektuje koordinate u lokalne SVG viewBox-ove, pojednostavljuje putanje
i proverava broj, jedinstvenost i integritet oblasti. Rezultat je:

`public/maps/index.json`, `districts/*.json`, `settlements/*.json`,
`location-index.json`, `settlement-coverage.json` i `manifest.json`.

Puni poligoni naselja nalaze se samo u slojevima pojedinačnih opština i učitavaju
se po potrebi. `location-index.json` sadrži zajedničku projekciju, opštinske
granice i kompaktne tačke naselja; izbor najbliže tačke je približna lokacija,
ne provera pripadnosti granici naselja. Koordinate posetioca ne šalju se izvorima.

SVG putanje mogu imati više zatvorenih pod-putanja. Potrošač treba da koristi
`fill-rule="evenodd"` (`fillRule="evenodd"` u React-u).

Fajl `serbia-municipalities-source.svg` nije izvor generisanog modela niti se
isporučuje aplikaciji. Sačuvan je samo kao razvojna referenca; pre eventualne
upotrebe treba obnoviti njegov tačan Wikimedia Commons URL i potvrditi zabeleženu
CC BY-SA 3.0 licencu.