# Mapa Oświatowa

> Największa interaktywna baza polskich placówek oświatowych — ponad 59 000 szkół, przedszkoli, żłobków i uczelni wyższych na jednej mapie. Dane z publicznych rejestrów RSPO, rejestru żłobków MRPiPS, RADON oraz OpenStreetMap.

Serwis: https://mapaoswiatowa.pl
Publiczne API (bez klucza, tylko GET): https://api.mapaoswiatowa.pl

## O Serwisie

Mapa Oświatowa to kompleksowe, bezpłatne narzędzie do wyszukiwania i porównywania placówek edukacyjnych w Polsce. Serwis oferuje:
- Bazę ponad 59 000 placówek oświatowych z pełną weryfikacją danych
- Pokrycie wszystkich 16 województw Polski
- Dane z ponad 9 000 miast i miejscowości
- Interaktywną mapę z clusteringiem i zaawansowanymi filtrami (20+ kryteriów)
- Szczegółowe statystyki dla każdego regionu i typu placówki

## Typy Placówek

Wartości pola `type` w API (dokładnie te ciągi, wielkimi literami — inna wartość zwraca błąd 400):

| `type` | Znaczenie | Slug w URL serwisu |
|---|---|---|
| `NURSERY` | Żłobki i kluby dziecięce (opieka do lat 3) | `zlobki` |
| `PRESCHOOL` | Przedszkola, punkty przedszkolne (3–6 lat) | `przedszkola` |
| `PRIMARY_SCHOOL` | Szkoły podstawowe (klasy 1–8) | `szkoly-podstawowe` |
| `SECONDARY_SCHOOL` | Szkoły średnie — licea, technika, szkoły branżowe | `szkoly-srednie` |
| `POST_SECONDARY` | Szkoły policealne (ISCED 4) | `szkoly-policealne` |
| `HIGHER_EDUCATION` | Uczelnie wyższe | `uczelnie` |
| `CONTINUING_EDUCATION` | Kształcenie ustawiczne i zawodowe | `ksztalcenie-ustawiczne` |
| `SCHOOL_COMPLEX` | Zespoły szkół i placówek oświatowych | `zespoly-szkol` |

Uwaga: przedszkole to `PRESCHOOL`, **nie** `KINDERGARTEN`. `KINDERGARTEN` jest wartością pola `subtype`.

Wartości pola `subtype` (opcjonalne doprecyzowanie typu):
- Żłobek: `CHILDRENS_CLUB` (klub dziecięcy)
- Przedszkole: `KINDERGARTEN`, `PRESCHOOL_POINT`, `PRESCHOOL_TEAM`
- Szkoła podstawowa: `ARTISTIC`, `SPECIAL_NEEDS`
- Szkoła średnia: `GENERAL_SECONDARY` (liceum), `TECHNICAL_SECONDARY` (technikum), `VOCATIONAL_1`, `VOCATIONAL_2` (szkoły branżowe I i II stopnia)
- Uczelnia: `UNIVERSITY`, `POLYTECHNIC`, `ACADEMY`
- Kształcenie ustawiczne: `VOCATIONAL_CENTER`, `SKILLS_CENTER`

## Dane Geograficzne

System edukacji w Polsce organizowany jest według 16 województw. Slug województwa (parametr `voivodeship` w API i segment URL) to nazwa bez polskich znaków:
`dolnoslaskie`, `kujawsko-pomorskie`, `lubelskie`, `lubuskie`, `lodzkie`, `malopolskie`, `mazowieckie`, `opolskie`, `podkarpackie`, `podlaskie`, `pomorskie`, `slaskie`, `swietokrzyskie`, `warminsko-mazurskie`, `wielkopolskie`, `zachodniopomorskie`.

Największe skupisko placówek znajduje się w województwach mazowieckim, śląskim i wielkopolskim.

Placówki są przypisane do miejscowości (`localityId` / `citySlug`), gminy (`municipality`), powiatu (`county`) i województwa. Kilka miejscowości w Polsce nosi tę samą nazwę (np. Czyżowice w śląskim i w lubelskim) — jeśli odpowiedź musi być jednoznaczna, filtruj po `cityId` (identyfikator miejscowości), a nie po `city`.

## Źródła Danych

- Rejestr Szkół i Placówek Oświatowych (RSPO) — szkoły i przedszkola, identyfikator w polu `rspo`. Z otwartego eksportu CSV rejestru pochodzą też pola o zatrudnieniu specjalistów (`employsSpeechTherapist`, `employsPsychologist`, `employsPedagogue`), językach nauczanych (`languages`), terenach sportowych (`sportsFacilities`) i kategorii uczniów (`forAdults`)
- Rejestr Żłobków i Klubów Dziecięcych (MRPiPS) — żłobki i kluby dziecięce, identyfikator w polu `nurseryRegistryId` (np. `9199/Z`); żłobki **nie mają** numeru RSPO
- RAD-on (OPI PIB) — uczelnie wyższe, identyfikator w polu `radonId` (UUID rejestru). Zwraca go wyłącznie `GET /api/institutions/{id}` i służy tylko do złączenia z danymi RAD-on — nie jest numerem, który cokolwiek by znaczyło dla czytelnika
- OpenStreetMap — dane geolokalizacyjne, godziny otwarcia, kontakty; licencja **ODbL 1.0** (https://www.openstreetmap.org/copyright)
- Państwowy Rejestr Nazw Geograficznych (PRNG, GUGiK) — środek miejscowości (`lat` / `lng` w `GET /api/cities/{slug}`) oraz odmiana jej nazwy (`nameGenitive`, `nameAdjective`); licencja **CC BY 4.0**. Wymagana formuła: „Wykorzystano/opracowano na podstawie materiałów państwowego zasobu geodezyjnego i kartograficznego"
- Bank Danych Lokalnych GUS (BDL) — ludność miejscowości według Narodowego Spisu Powszechnego 2021 (stan na 31.03.2021) i szeregi oświatowe 2008–2024 na poziomie miejscowości, województwa i kraju: pola `population`, `educationStats` i `educationBenchmarks` w `GET /api/cities/{slug}`, `education` w `GET /api/voivodeships/{slug}` oraz `cityPopulation` w `GET /api/institutions/{id}`; licencja **CC BY 4.0**
- System Informacji Oświatowej (SIO, MEN) — liczby uczniów, oddziałów i nauczycieli na placówkę oraz miejsca w przedszkolach, migawka na 30 września: pola `sioStats` i `sioAvailability` w `GET /api/institutions/{id}`, `sioPupils` w `/nearby`, `sioStats` w `GET /api/cities/{slug}`, skalary `sio*` w `GET /api/statistics` i blok `occupancy` w `GET /api/statistics/fees`; wykaz na licencji **CC BY 4.0**, arkusz przedszkolny (miejsca/przyjęci) jako zbiór otwarty **CC0**. Osobny zbiór SIO „liczba uczniów wg zawodów szkolnictwa branżowego" (dane.gov.pl, zbiór 1617, **CC0**) zasila krajowe trendy zawodów: `GET /api/statistics/vocational-trends` i stronę `/zawody`
- Zgłoszenia użytkowników (weryfikowane przed publikacją)

## API

Baza: `https://api.mapaoswiatowa.pl`. Wszystkie endpointy poniżej to `GET`, bez uwierzytelniania, odpowiedzi w JSON (UTF-8). Limit: 120 zapytań na minutę z jednego adresu IP. Parametry z polskimi znakami należy zakodować (`Czy%C5%BCowice`).

Maszynowy opis tej samej powierzchni: `https://mapaoswiatowa.pl/openapi.json` (OpenAPI 3.1 — ścieżki, parametry i zamknięte słowniki). Punkt wejścia do odkrycia API: `https://mapaoswiatowa.pl/.well-known/api-catalog` (RFC 9727), z relacjami do specyfikacji, dokumentacji (`https://mapaoswiatowa.pl/dla-deweloperow`) i endpointu statusu (`https://api.mapaoswiatowa.pl/health`). Ten sam katalog jest też pod `https://api.mapaoswiatowa.pl/.well-known/api-catalog`.

### Wyszukiwanie i geokodowanie

- `GET /api/locations/search?q={fraza}` — jedyny sposób zamiany nazwy miejscowości na współrzędne. Zwraca `results[]` z wpisami typu `city` (pola: `id` — to `cityId`, `label`, `slug`, `voivodeship`, `count`, `lat`, `lng`), `district`, `institution` oraz `postalCode` (gdy zapytanie zaczyna się od cyfry). Minimum 2 znaki, dopasowanie po początku nazwy.
- `GET /api/locations/reverse?lat={lat}&lng={lng}` — najbliższa miejscowość dla podanych współrzędnych.

### Placówki

- `GET /api/institutions` — paginowana lista placówek, bez danych kontaktowych i bez `description` (patrz niżej). Filtry: `type`, `excludeType`, `subtype`, `voivodeship` (slug), `powiat` (slug powiatu — podawaj razem z `voivodeship`, slug jest unikalny tylko w województwie), `gmina` (slug gminy — podawaj razem z `voivodeship` i `powiat`, slug jest unikalny tylko w powiecie), `city` (nazwa, dopasowanie zawierające), `cityId` (dokładne, zalecane), `search` (nazwa placówki), `isPublic`, `wheelchairAccessible`, `fee`, `canteen`, `hasBoarding`, `religion`, `operatorType`, `pedagogy`, `schoolType`, `employsSpeechTherapist`, `employsPsychologist`, `employsPedagogue`, `language` (jedna wartość, np. `niemiecki` — placówki nauczające tego języka), `higherEducationProfile` (`ACADEMIC`/`VOCATIONAL`), `supervisoryBody`, `patron`, `minYear`, `maxYear`, `minMonthlyFee`, `maxMonthlyFee`, `minLat`+`maxLat`+`minLng`+`maxLng` (prostokąt), `promoted=true`. Sortowanie: `sortBy=name|views|monthlyFee`. Stronicowanie: `page` (od 1), `limit` (1–100, domyślnie 20). Odpowiedź: `{ institutions: [...], pagination: { page, limit, total, pages } }`.
- `GET /api/institutions/nearby?lat={lat}&lng={lng}&radius={km}` — placówki w promieniu od punktu, posortowane rosnąco po odległości, z polem `distance` w kilometrach. `radius` 1–100 km (domyślnie 20), `limit` 1–50 (domyślnie 25). `type` przyjmuje tu listę rozdzieloną przecinkami (`type=NURSERY,PRESCHOOL`), obsługiwany jest też `subtype`. Odpowiedź: `{ institutions: [...], promoted: [...] }` — `promoted` to wpisy płatne w promieniu 50 km, wyłączone z `institutions`; nie mieszaj ich z wynikami merytorycznymi. Tu również nie ma danych kontaktowych ani `description`. Wiersze niosą też `forAdults` (patrz reguły pól RSPO niżej).
- `GET /api/institutions/{id}` — pełny profil placówki (50+ pól, zdjęcia, zawody w technikach, placówki podrzędne zespołu szkół w `childInstitutions`, a dla placówki członkowskiej — jej zespół w `parentInstitution` i pozostałe placówki tego zespołu w `siblingInstitutions`). Jako `{id}` zadziała numeryczne `id`, `slug`, numer RSPO w formacie slugu oraz `nurseryRegistryId` żłobka (np. `9199/Z`, zakodowane jako `9199%2FZ`). Sama liczba jest czytana jako `id`, nie jako numer RSPO — zakresy obu się pokrywają, więc żeby zapytać o numer RSPO, dodaj `?by=rspo` (np. `/api/institutions/3021?by=rspo`); inna wartość `by` to HTTP 400. Jeśli placówka została znaleziona pod starym adresem, odpowiedź zawiera `redirectSlug` z aktualnym slugiem. Nieistniejąca placówka: HTTP 410. Pole `staticMapUrl` to gotowy adres miniatury mapy na naszym CDN-ie — może być `null` i nie gwarantuje, że render już istnieje; gdy go brakuje, wygeneruje go `GET /api/static-map/{id}` (przekierowanie 302 pod ten sam adres).
- `GET /api/institutions/popular` — najczęściej oglądane placówki.

Najważniejsze pola placówki: `id`, `name`, `slug`, `type`, `subtype`, `isPublic`, `street`, `houseNumber`, `postalCode`, `city`, `citySlug`, `district`, `municipality`, `county`, `voivodeship`, `voivodeshipSlug`, `latitude`, `longitude`, `website`, `description` (tylko w profilu pojedynczej placówki), `openingHours`, `capacity`, `studentCount`, `minAge`, `maxAge`, `fee`, `monthlyFee`, `hourlyFee`, `dailyMealFee`, `canteen`, `hasBoarding`, `wheelchairAccessible`, `pedagogy`, `religion`, `patron`, `operator`, `operatorType`, `schoolTypes`, `iscedLevel`, `employsSpeechTherapist`, `employsPsychologist`, `employsPedagogue`, `languages`, `sportsFacilities`, `forAdults`, `rspo`, `nurseryRegistryId`, `regon`, `nip`, `startDate`, `updatedAt`.

**Trzy pola mają zamknięty słownik** — wartość spoza listy nie zwróci błędu, tylko zostanie zignorowana jako filtr:

- `operatorType` — organ prowadzący, czyli **kto** prowadzi placówkę: `gmina`, `miasto`, `powiat`, `samorzad_woj`, `minister`, `cuw` (te sześć pochodzi ze słownika `typPodmiotu` rejestru RSPO) oraz `fundacja`, `stowarzyszenie`, `koscielna`, `spolka`, `osoba_fizyczna`. To **nie jest** podział na placówki publiczne i niepubliczne — do tego służy `isPublic`, wypełnione dla ~90% placówek, podczas gdy `operatorType` dla ~59%. RSPO nie mapuje dziś form niepublicznych, więc dla większości placówek prywatnych pole jest `null` — to „rejestr nie podaje", nigdy „prowadzi ją gmina".
- `religion` — wyznanie placówki wyznaniowej: `katolicka`, `chrzescijanska`, `ewangelicka`, `luteranska`, `prawoslawna`, `zydowska`, `muzulmanska`, `inne_wyznanie`. `null` znaczy „placówka nie jest wyznaniowa"; nie ma osobnej wartości „świecka".
- `pedagogy` — pedagogika alternatywna: `montessori`, `waldorf`, `reggio_emilia`, `freinet`, `democratic`, `ib`, `dalton`, `korczak`. `null` to szkoła bez pedagogiki alternatywnej. Szkoła leśna **nie jest** tu wartością — to `forest` w `schoolTypes`.

Dane kontaktowe — `phone`, `mobile`, `fax`, `email` oraz profile społecznościowe `facebook`, `instagram`, `youtube`, `tiktok` — zwraca wyłącznie `GET /api/institutions/{id}`, po jednej placówce na zapytanie. Listy (`/api/institutions`, `/api/institutions/nearby`) ich nie zawierają, żeby nie służyły do masowego pobierania kontaktów. Osobno, i z innego powodu, listy nie niosą `description`: to jedyne pole z dowolnym tekstem obok samych enumów i liczb, więc po kompresji waży więcej niż cała reszta wiersza. Opis zwraca `GET /api/institutions/{id}`.

Adresy e-mail placówek pochodzą z rejestrów publicznych (RSPO, rejestr żłobków) i są przeznaczone do kontaktu w sprawach danej placówki, nie do wysyłki marketingowej.

Zdjęcia w `assets` (`background`, `gallery`, `logo`) mają pole `attribution`: `null` dla zdjęć przesłanych przez placówki i administratora, a dla zdjęć z Wikimedia Commons obiekt z `author`, `authorUrl`, `license` (np. `CC BY-SA 4.0`), `licenseUrl`, `sourceUrl` (strona pliku) i `sourceName`. Kto wykorzystuje takie zdjęcie dalej, zachowuje warunki jego licencji i podaje autora.

**Statystyki SIO placówki.** `GET /api/institutions/{id}` zwraca też `sioStats` — dane Systemu Informacji Oświatowej za najnowszy rok szkolny: `schoolYear` (np. `"2025/2026"`), `pupils`, `pupilsFemale`, `classes`, `teachersHeadcount`, `teacherFte` (liczba z dwoma miejscami po przecinku), `capacity` i `enrolled` (miejsca i przyjęte dzieci w wychowaniu przedszkolnym) — oraz `sioAvailability` (`reported` / `not-reported` / `out-of-scope`). Pięć reguł interpretacji:

1. **`null` znaczy „nie zgłoszono", nigdy zero** — z jednym wyjątkiem: `capacity`/`enrolled` miewają prawdziwe zera.
2. **`capacity`/`enrolled` na szkole podstawowej opisują jej oddział przedszkolny („zerówkę"), nie całą szkołę** — arkusz przedszkolny SIO wykazuje je pod RSPO ~6 600 szkół podstawowych obok ~15 100 przedszkoli; nigdy nie interpretuj ich jako pojemności szkoły. Na przedszkolu to miejsca całej placówki, a `pupils` liczy tam wychowanków (dzieci), nie uczniów.
3. **Żłobki i uczelnie nigdy nie mają danych SIO** (`sioAvailability: "out-of-scope"`) — SIO obejmuje tylko placówki MEN; braku nie wolno interpretować jako zera dzieci ani zaniedbania placówki.
4. **W zespole szkół uczniowie są wykazywani przy szkołach członkowskich, a nauczyciele przy zespole** — nigdy nie dziel uczniów przez nauczycieli na poziomie jednej placówki i nie sumuj zespołu z jego szkołami (`childInstitutions[].sioPupils` niesie uczniów per szkoła członkowska).
5. **`sioStats` to inne źródło niż `studentCount`/`capacity`** (te pochodzą z RSPO/OSM/zgłoszeń i nie są uzgadniane z SIO) — różnicy między nimi nie należy zestawiać jako sprzeczności; przy cytowaniu preferuj `sioStats` z rokiem szkolnym.

Listy niosą co najwyżej `sioPupils` + `sioSchoolYear` (`/nearby`); pełny obiekt `sioStats` zwraca tylko `GET /api/institutions/{id}`.

**Pola z otwartego CSV RSPO.** `employsSpeechTherapist` / `employsPsychologist` / `employsPedagogue` (logopeda, psycholog, pedagog), `languages` (języki obce nauczane, np. `["angielski", "niemiecki"]`), `sportsFacilities` (tereny sportowe) i `forAdults` (kategoria uczniów). Trzy reguły interpretacji:

1. **Booleany `employs*` są w rejestrze wypełnione w 100%** — `false` to prawdziwe „nie zatrudnia", nie brak danych; `null` znaczy tylko, że placówka nie podlega RSPO (żłobki, uczelnie).
2. **Pusta lista `languages`/`sportsFacilities` znaczy „nie zgłoszono", nigdy „brak"** — tereny sportowe wykazuje tylko ~23% placówek.
3. **`forAdults`**: `true` = kategoria „Dorośli" (np. licea dla dorosłych), `false` = „Dzieci lub młodzież", `null` = „Bez kategorii" w rejestrze (realna kategoria, nie luka).

### Miasta, województwa, statystyki

- `GET /api/cities?voivodeship={slug}&limit={n}` — miejscowości z liczbą placówek, malejąco. Wiersze niosą też `countySlug` i `countyIsCity` (miasto na prawach powiatu — jego URL powiatowy tylko przekierowuje), a odpowiedź szczegółowa niżej dodatkowo `municipalitySlug` (niepusty wyłącznie dla gmin wiejskich i miejsko-wiejskich — gmina miejska nie ma własnej strony), `municipalityKind` i `siblingLocalities[]` (pozostałe miejscowości tej samej gminy z liczbą placówek).
- `GET /api/cities/{slug}` — szczegóły miejscowości: statystyki, rozbicie na typy, `rmCode` (rodzaj miejscowości wprost z rejestru TERYT SIMC, kolumna `RM`), odmiana nazwy z PRNG (`nameGenitive` — „Czyżowic", `nameAdjective` — „czyżowicki") oraz `lat` / `lng`. **`lat` / `lng` to środek miejscowości z PRNG** (punkt główny wsi lub miasta, dokładność ~30 m), a nie średnia współrzędnych placówek; tam, gdzie PRNG nie zna miejscowości, jest to średnia — cztery miejscowości w kraju. Nie jest to współrzędna żadnej placówki. Odpowiedź niesie też **`population`** — ludność według NSP 2021, stan na 31.03.2021 (pola `total`, `male`, `female`, `agePre` — wiek przedprodukcyjny 0–17, `ageWorking`, `agePost`, `asOf`, `viaStatisticalLocality`): `null` oznacza, że GUS nie publikuje danych dla tej miejscowości (~190 przypadków); `viaStatisticalLocality: true` — że liczby dotyczą miejscowości statystycznej, w której skład ta miejscowość wchodzi. Oraz **`educationStats[]`** — szeregi GUS per rok (2008–2024): `preschools`, `preschoolChildren`, `preschoolSections`, `primarySchools`, `primaryPupils`, `primarySections`; `null` w kolumnie to „brak informacji" w sprawozdaniu GUS — **nigdy nie interpretuj go jako zera ani jako braku szkoły**. GUS liczy jednostki sprawozdawcze wg lokalizacji, a ten serwis wpisy rejestrowe — obu liczb nie należy zestawiać jako sprzeczności. Do tego **`educationBenchmarks`** — średnia liczebność oddziału na tle regionu i kraju: dla `primaryClassSize` (uczniowie na oddział w szkołach podstawowych) i `preschoolGroupSize` (dzieci na oddział wychowania przedszkolnego) obiekt `{ year, voivodeship, poland }`, liczony z **oficjalnych szeregów GUS BDL na poziomie województwa i Polski** — nigdy z sumowania miejscowości: suma miejscowości przekracza oficjalne wartości krajowe o 11–13% i pochodzi z innego uniwersum agregacji, więc obu nie należy zestawiać jako sprzeczności. Wartości zaokrąglone do jednego miejsca po przecinku, za najświeższy rok, w którym oba poziomy raportują; `null`, gdy danych brak.
  Kody: `00` część miejscowości · `01` wieś · `02` kolonia · `03` przysiółek · `04` osada · `05` osada leśna · `06` osiedle · `07` schronisko turystyczne · `95` dzielnica m.st. Warszawy · `96` miasto · `98` delegatura · `99` część miasta.
  Pole bywa `null` dla miejscowości, której nie udało się dopasować do rejestru — wtedy rodzaju nie znamy i nie należy go zgadywać.
  Odpowiedź niesie też **`sioStats`** — agregaty SIO dla miejscowości za najnowszy rok szkolny: `schoolYear`, `reportingInstitutions`, `pupils`, `pupilsFemale`, `classes`, `avgClassSize` (z sum parowanych — wierszy niosących i uczniów, i oddziały), `teachersHeadcount`, `teacherFte`, `preschoolCapacity`, `preschoolEnrolled` (sumy miejsc/przyjętych liczone wyłącznie po placówkach typu `PRESCHOOL` — oddziały przedszkolne przy szkołach podstawowych nie wchodzą do tych sum); `null`, gdy żadna placówka miejscowości nie raportuje. To **inne uniwersum pomiaru niż `educationStats`** (GUS liczy jednostki sprawozdawcze wg lokalizacji za rok 2024, SIO wpisy rejestrowe na 30.09) — obu nie należy zestawiać jako sprzeczności. Sumy są bezpieczne względem zespołów szkół (każda liczba jest wykazana dokładnie raz), ale uczniów przez etaty nie wolno dzielić — zespół może leżeć w innej miejscowości niż jego szkoły.
- `GET /api/divisions/{woj}` — powiaty województwa: `slug`, `name` (nazwa rejestrowa — dla powiatów ziemskich przymiotnik pisany małą literą, np. „bolesławiecki"), `terytCode` (4 cyfry TERC), `isCityCounty`, `citySlug` (dla miasta na prawach powiatu — slug miejscowości, do której URL powiatu przekierowuje), `institutionCount`, `municipalityCount`, `localityCount`. Liczby miejscowości dotyczą wyłącznie miejscowości z placówkami w tym serwisie (~19% pełnego rejestru SIMC), nigdy wszystkich miejscowości jednostki.
- `GET /api/divisions/{woj}/{powiat}` — szczegóły powiatu: `totals` (placówki wg typu), `operatorMix` (organy prowadzące z rejestru, wartości z zamkniętego słownika `operatorType` opisanego wyżej; `operatorType: null` to „rejestr nie podaje"), `municipalities[]` z rozbiciem na miejscowości, `nearbyCounties[]`, `educationStats[]` (oficjalne serie oświatowe GUS BDL dla powiatu, 2008+, `null` w kolumnie = „brak informacji", nigdy zero; CC BY 4.0), `educationBenchmarks` (średnia liczebność klasy/grupy dla województwa i Polski z tego samego rocznika), `teacherStats[]` (nauczyciele wg stopnia awansu z SIO — zbiór 811, lata 2020–2025; `fte` to etaty przeliczeniowe; stopnie sprzed i po reformie 2022 to różne systemy; CC BY 4.0), `lat`/`lng` (średnia centroidów PRNG miejscowości — wyłącznie do centrowania mapy). Miasto na prawach powiatu (66 jednostek, `POW ≥ 61` w kodzie TERC) zwraca `{ "redirect": { "slug": … } }` — jego strona to `/miasta/{slug}`. Gmina miejska w `municipalities[]` niesie `redirect` z tego samego powodu. Powiat pytany pod złym województwem → 404.
- `GET /api/divisions/{woj}/{powiat}/{gmina}` — szczegóły gminy: `municipality` (z `kind`: `miejska`/`wiejska`/`miejsko-wiejska`, dekodowane z ostatniej cyfry kodu TERC), `totals`, `localities[]` (wszystkie miejscowości gminy z placówkami, z `isSeat` — heurystyka imiennika, brak trafienia nie oznacza braku siedziby), `seat`, `nearbyMunicipalities[]`, `educationStats[]` i `educationBenchmarks` (jak na powiecie, ale z poziomu gminy — oficjalne agregaty GUS, nigdy suma miejscowości), `indicators[]` (wskaźniki GUS BDL: dzieci i miejsca w żłobkach na 1000 dzieci do lat 3, dzieci objęte wychowaniem przedszkolnym na 1000 dzieci 3–6 lat, współczynniki skolaryzacji brutto/netto dla szkół podstawowych w %; roczniki wskaźników się różnią; CC BY 4.0). Gmina miejska zwraca `{ "redirect": { "slug": … } }` — jej strona to strona miasta.
- `GET /api/voivodeships/{slug}` — statystyki województwa, rozbicie na typy, 10 największych miast. Odpowiedź niesie też **`education[]`** — oficjalne szeregi GUS BDL dla województwa per rok, 2008–2024: `preschools`, `preschoolChildren`, `preschoolSections`, `primarySchools`, `primaryPupils`, `primarySections` — `null` to „brak informacji”, nigdy zero ani brak szkoły; absolwentów nie serwujemy — oraz `localitiesWithPreschoolChildren` / `localitiesWithPrimaryPupils`, liczbę miejscowości województwa, w których dzieci korzystały z wychowania przedszkolnego / uczniowie uczyli się w szkole podstawowej. To zliczenie po pełnym zbiorze miejscowościowym BDL, nigdy suma wartości; licznik przedszkolny za 2016 niesie ogólnokrajową zapaść sprawozdawczą na poziomie miejscowości — to nie jest fala zamknięć.
- `GET /api/statistics` — agregaty ogólnokrajowe: liczba wg typu, subtypu, województwa, top 10 miast, publiczne vs prywatne. Odpowiedź niesie też skalary **`sio*`** — krajowe sumy SIO za najnowszy rok szkolny (`sioSchoolYear`, `sioReportingInstitutions`, `sioPupils`, `sioPupilsFemale`, `sioClasses`, `sioAvgClassSize`, `sioTeachersHeadcount`, `sioTeacherFte`, `sioPreschoolCapacity`, `sioPreschoolEnrolled` — dwie ostatnie liczone wyłącznie po placówkach typu `PRESCHOOL`, spójnie z blokiem `occupancy` w `/fees`). SIO obejmuje wyłącznie placówki MEN — ~6 900 żłobków i ~500 uczelni nie raportuje — więc tych sum nie należy dzielić przez liczby rejestrowe wyżej ani zestawiać z nimi jako sprzeczności.
- `GET /api/statistics/fees?type=NURSERY|PRESCHOOL&cityId={id}&voivodeship={slug}` — statystyki opłat. Gdy w mieście jest za mało danych, zakres automatycznie rozszerza się do województwa, a potem do kraju — pole `scope` w odpowiedzi mówi, jakiego obszaru faktycznie dotyczy wynik. Dla `type=PRESCHOOL` odpowiedź niesie też **`occupancy`** — miejsca vs przyjęci wg SIO (`scope`, `schoolYear`, `institutions`, `capacity`, `enrolled`, `occupancyRate`), z **własnym** rozszerzaniem zakresu: pokrycie obłożenia jest znacznie szersze niż pokrycie cen, więc `occupancy.scope` bywa węższy niż `scope` opłat. Dla `type=NURSERY` zawsze `occupancy: null` — żłobki nie raportują do SIO.
- `GET /api/patrons/search?q=` i `GET /api/patrons/top` — patroni szkół z liczbą placówek; `/top` zwraca też `slug` strony patrona.
- `GET /api/patrons/{slug}` — patron po slugu (`{ patron, count, slug }`); 404 dla patrona z mniej niż 10 placówkami.
- `GET /api/patrons/stats` — statystyki patronów: liczba placówek z patronem, top 10, najczęstszy patron wg typu placówki, podział na kategorie i płeć (klasyfikacja automatyczna, pole `classifiedAt` mówi kiedy).
- `GET /api/vocational/professions` — zawody nauczane w technikach i szkołach branżowych.
- `GET /api/statistics/vocational-trends` — krajowe trendy zawodów szkolnictwa branżowego z SIO (zbiór 1617): `years[]`, `latestYear`, `previousYear` oraz `professions[]` (nazwa, branża z klasyfikacji 2025/26, seria per rok szkolny: `pupils`, `pupilsFemale`, `firstYearPupils`, `youthWorkers`, `graduates`, `schools`) i `schoolTypes[]` (sumy per typ szkoły). Reguły interpretacji: `null` znaczy „nie opublikowano dla tego rocznika", nigdy zero; `firstYearPupils` liczy klasę I oraz sem. I szkół policealnych (rocznik 2018/2019 nie ma podziału na klasy — tam zawsze `null`); absolwenci roku N pochodzą z pliku rocznika N+1, więc najnowszy rok ma `null`; `pupilsFemale` to dolne oszacowanie (część wierszy źródła nie wykazuje dziewcząt); reforma klasyfikacji z 2019 r. zmieniła nazwy i listę zawodów, więc porównania przez granicę 2018/19→2019/20 bywają zerwane; to **inne uniwersum pomiaru** niż liczby rejestrowe placówek — nie dzielić jednych przez drugie. To nie to samo, co `/api/vocational/professions` (autocomplete zawodów przypisanych placówkom z RSPO).
- `GET /api/statistics/demographic-forecast` — prognoza ludności GUS na lata 2023–2060 (scenariusz główny/średni, dane z 2024-07-12, CC BY 4.0) w edukacyjnych grupach wieku: `poland[]` i `voivodeships[]` (`terytCode`, `name`, `slug` oraz `years[]`: `year`, `age0_2` żłobek, `age3_6` przedszkole, `age7_14` szkoła podstawowa, `age15_19` szkoły ponadpodstawowe, `total`), lata 2022–2060. Reguły interpretacji: rok 2022 (`empiricalYear`) to **dane rzeczywiste**, prognoza właściwa zaczyna się od 2023; każda wartość to ludność mieszkająca na danym terenie w stanie na 31 XII, **nie uczniowie zapisani do szkół** — nie dzielić przez liczby uczniów z SIO ani GUS BDL (inne uniwersum pomiaru); wartości wojewódzkie to dokładne sumy 380 serii powiatowych. Pole `history[]` to historyczne oficjalne szeregi ogólnopolskie GUS BDL (dzieci w wychowaniu przedszkolnym i uczniowie szkół podstawowych, 2008–2024), gdzie `null` znaczy „brak informacji", nigdy zero. Przy cytowaniu podaj: GUS, Prognoza ludności na lata 2023–2060, scenariusz główny, dane z 2024-07-12, CC BY 4.0.
- `GET /api/statistics/specialists` — zatrudnienie specjalistów z otwartego eksportu CSV RSPO: `registryAsOf` (stan rejestru — data ostatniego importu), `national`, `byVoivodeship[]` (z `name` i `slug`), `byType[]`, `byUrbanRural[]` i `languages[]` (pełna lista, liczona per placówka). Reguły interpretacji: pola o specjalistach są w rejestrze wypełnione w 100% w obrębie RSPO, więc `reporting` to placówki objęte rejestrem, a `null` przy placówce znaczy „poza rejestrem" (żłobki, uczelnie), nigdy „nie zatrudnia"; odsetki licz **zawsze od `reporting`**, nigdy od pełnej liczby wpisów; to odsetek **placówek**, nie uczniów — rejestr nie niesie wymiaru etatu, więc nie odpowiada na pytanie o liczbę uczniów na psychologa ani o spełnianie standardów z art. 42d Karty Nauczyciela; suma `byVoivodeship` jest minimalnie mniejsza niż `national` (placówki bez przypisanej miejscowości).

### Czego nie używać

`GET /api/points` istnieje wyłącznie na potrzeby renderowania mapy. Zwraca kilkaset kilobajtów tablic `[id, lat, lng, indeks_typu, indeks_subtypu]` — bez nazw, z typami zakodowanymi jako liczby. Bliźniaczy `GET /api/points/binary` zwraca ten sam zbiór w formacie binarnym dla samej mapy — zignoruj go. Do odpowiadania na pytania używaj `/api/institutions` lub `/api/institutions/nearby`.

## Wersje Markdown Stron

Strony serwisu odpowiadają wersją Markdown, jeśli żądanie niesie nagłówek `Accept: text/markdown`. Bez tego nagłówka odpowiedzią jest HTML — adres jest ten sam, nie ma osobnych URL-i z rozszerzeniem `.md`.

    curl -H "Accept: text/markdown" https://mapaoswiatowa.pl/szkola/{slug}

Obsługiwane są: strona główna (`/`), placówki (`/szkola/{slug}`), miejscowości (`/miasta/{citySlug}`) i wpisy bloga (`/blog/{slug}`). Pozostałe adresy zwracają HTML niezależnie od nagłówka.

Odpowiedź ma `Content-Type: text/markdown; charset=utf-8` i budowę: frontmatter YAML (`title`, `description`, `image`, `url`) → treść → dane strukturalne JSON-LD w bloku kodu. Nagłówek `x-markdown-tokens` niesie szacunkową liczbę tokenów, a `Link: …; rel="canonical"` — adres wersji HTML, który należy podawać przy cytowaniu.

Wersje Markdown niosą te same dane i te same zastrzeżenia interpretacyjne co strony HTML. Do zapytań filtrowanych i masowych nadal właściwe jest API opisane niżej — Markdown służy do czytania pojedynczej strony, nie do pobierania zbiorów.

## Przykładowe Zapytania

**Szkoła podstawowa w konkretnej miejscowości** — jedno zapytanie:

    GET https://api.mapaoswiatowa.pl/api/institutions?city=Czy%C5%BCowice&type=PRIMARY_SCHOOL

Gdy nazwa miejscowości powtarza się w Polsce, ustal najpierw `cityId` przez `/api/locations/search?q=Czyżowice` (wynik typu `city` zawiera `id` i województwo) i zapytaj `?cityId=20912&type=PRIMARY_SCHOOL`.

**Żłobki w promieniu 10 km od miejscowości** — dwa kroki, bo API nie geokoduje nazw samodzielnie:

1. `GET https://api.mapaoswiatowa.pl/api/locations/search?q=Czy%C5%BCowice` → z wyniku typu `city` weź `lat` i `lng`
2. `GET https://api.mapaoswiatowa.pl/api/institutions/nearby?lat=49.9828&lng=18.4088&radius=10&type=NURSERY&limit=50`

Wyniki są posortowane po `distance` (km). Kluby dziecięce mają `subtype: "CHILDRENS_CLUB"` — jeśli pytanie dotyczy wyłącznie żłobków w wąskim sensie, odfiltruj je po stronie odpowiedzi.

**Prywatne przedszkole z podjazdem dla wózków w mieście:**

    GET https://api.mapaoswiatowa.pl/api/institutions?cityId=20912&type=PRESCHOOL&isPublic=false&wheelchairAccessible=true

**Technika w województwie, posortowane po popularności:**

    GET https://api.mapaoswiatowa.pl/api/institutions?voivodeship=slaskie&subtype=TECHNICAL_SECONDARY&sortBy=views&limit=20

## Cytowanie i Linkowanie

Adresy stron budowane są ze slugów zwracanych przez API:
- Placówka: `https://mapaoswiatowa.pl/szkola/{slug}`
- Miasto: `https://mapaoswiatowa.pl/miasta/{citySlug}`
- Województwo: `https://mapaoswiatowa.pl/wojewodztwa/{voivodeshipSlug}`
- Kategoria: `https://mapaoswiatowa.pl/kategoria/{slug-typu}` (patrz tabela typów placówek)

Pola pochodzące z OpenStreetMap (m.in. `openingHours`, `wheelchairAccessible`, profile społecznościowe, a dla placówek bez żadnego identyfikatora rejestrowego — `rspo`, `nurseryRegistryId`, `radonId` — cały wpis) są objęte licencją ODbL 1.0: przy dalszym wykorzystaniu trzeba podać OpenStreetMap jako źródło i wskazać licencję. Pozostałe dane pochodzą z rejestrów publicznych.

Pola miejscowości pochodzące z PRNG (`lat`, `lng`, `nameGenitive`, `nameAdjective`) są na licencji CC BY 4.0 — wymagają wskazania źródła, ale **nie** narzucają share-alike jak ODbL. Przy dalszym wykorzystaniu należy podać PRNG oraz formułę o państwowym zasobie geodezyjnym i kartograficznym. Pola `population`, `educationStats` i `educationBenchmarks` miejscowości, `education` województwa oraz `cityPopulation` placówki pochodzą z Banku Danych Lokalnych GUS i również są objęte licencją CC BY 4.0 — przy dalszym wykorzystaniu podaj GUS BDL jako źródło; liczby NSP niosą stan na 31.03.2021, szeregi oświatowe rok, którego dotyczą.

Pola SIO (`sioStats` placówki i miejscowości, `sioPupils` w listach, skalary `sio*` statystyk, `occupancy` opłat) pochodzą z otwartych danych Systemu Informacji Oświatowej na dane.gov.pl: wykaz placówek na licencji **CC BY 4.0** — przy dalszym wykorzystaniu podaj „MEN, System Informacji Oświatowej" oraz rok szkolny (stan na 30 września) — a miejsca/przyjęci w przedszkolach oraz zbiór o zawodach (`/api/statistics/vocational-trends`) jako zbiory otwarte **CC0**.

Pole `updatedAt` placówki mówi, kiedy dane były ostatnio odświeżane — warto podać tę datę przy cytowaniu opłat i liczby uczniów. Opłaty (`monthlyFee`) pochodzą z rejestrów i zgłoszeń i mogą być nieaktualne w stosunku do cennika placówki; kontakt telefoniczny pozostaje rozstrzygający. Liczbę uczniów cytuj z `sioStats` (z rokiem szkolnym), nie z `studentCount`.

Preferencje dotyczące wykorzystania treści są zadeklarowane maszynowo w `https://mapaoswiatowa.pl/robots.txt` oraz `https://api.mapaoswiatowa.pl/robots.txt` w formacie Content Signals (contentsignals.org): `search=yes, ai-input=yes, ai-train=no`. Czytanie serwisu i cytowanie go w odpowiedziach asystentów jest wprost mile widziane; nie wyrażamy natomiast zgody na wykorzystanie treści do trenowania modeli — atrybucja wymagana przez licencje źródłowe (ODbL 1.0, CC BY 4.0) nie przetrwałaby takiego użycia. Pełne warunki: https://mapaoswiatowa.pl/regulamin

## Strony

- [Strona główna](/): Wyszukiwarka, kategorie, wyróżnione placówki, statystyki
- [Mapa](/mapa): Interaktywna mapa z clusteringiem, filtrami wg typu/województwa/dostępności i wyszukiwarką
- [Statystyki](/statystyki): Wykresy i dane zbiorcze — rozkład wg województw, typów, wzrost rok do roku, top 10 miast
- [Zawody](/zawody): Popularność zawodów szkolnictwa branżowego — rankingi wzrostów i spadków naboru, trendy 2018/19–obecnie, podział na branże i typy szkół
- [Demografia](/statystyki/demografia): Prognoza liczby dzieci w wieku żłobkowym, przedszkolnym i szkolnym do 2060 r. — kraj i 16 województw (prognoza GUS, scenariusz główny) oraz historyczne liczby uczniów i przedszkolaków od 2008 r.
- [Specjaliści w szkołach](/statystyki/specjalisci): Psycholog, pedagog i logopeda w placówkach — odsetki wg województw, typów placówek i miast/wsi, języki nauczane, dane RSPO z datą stanu rejestru
- [Kategorie](/kategoria/szkoly-podstawowe): Przeglądanie placówek wg 8 typów
- [Miasta](/miasta): Dedykowane strony miast ze statystykami i listą placówek
- [Województwa](/wojewodztwa): Przeglądanie placówek wg 16 regionów
- [Porównywarka](/porownaj): Zestawienie kilku placówek obok siebie
- [Patroni](/patroni): Przeglądanie szkół wg patrona
- [Pomoce edukacyjne](/pomoce-edukacyjne): Kalkulatory i quizy — punkty rekrutacyjne do szkoły średniej, koszty przedszkola, Aktywny Rodzic, dobór pedagogiki
- [Blog](/blog): Artykuły o edukacji — porady dla rodziców, prawo oświatowe
- [Dla deweloperów](/dla-deweloperow): Dokumentacja publicznego API — endpointy, słowniki, limity, licencje i zasady cytowania
- [Kontakt](/kontakt): Formularz kontaktowy i FAQ

## Kontekst Edukacyjny

Polski system edukacji obejmuje:
- Opiekę nad dziećmi do lat 3 (żłobki i kluby dziecięce — rejestr MRPiPS, nie RSPO)
- Edukację przedszkolną (przedszkola, punkty przedszkolne, 3–6 lat)
- Edukację podstawową (8 lat nauki, klasy 1–8)
- Edukację średnią (licea 4 lata, technika 5 lat, szkoły branżowe I i II stopnia)
- Edukację policealną
- Szkolnictwo wyższe (uniwersytety, politechniki, akademie)

Większość placówek to szkoły publiczne finansowane ze środków samorządowych lub państwowych. W segmencie żłobków i przedszkoli rośnie udział placówek niepublicznych.

## Optional

- [Polityka prywatności](/polityka-prywatnosci): Zasady przetwarzania danych (RODO)
- [Regulamin](/regulamin): Warunki korzystania z serwisu
- [Zgłoś placówkę](/zgloszenie/dodaj): Formularz dodawania nowej placówki