Mapaoswiatowa

Mapa Oświatowa — publiczne API

Publiczne API serwisu Mapa Oświatowa. Wszystkie opisane niżej endpointy to GET, bez uwierzytelniania i bez klucza, odpowiedzi w JSON (UTF-8). Zasady, które…

Data & analytics#open-data

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Publiczne API serwisu Mapa Oświatowa. Wszystkie opisane niżej endpointy to GET, bez uwierzytelniania i bez klucza, odpowiedzi w JSON (UTF-8).

Zasady, które obowiązują na każdym endpoincie:

  • Limit 120 zapytań na minutę z jednego adresu IP. Po przekroczeniu API odpowiada 429 z nagłówkiem Retry-After.
  • CORS: Access-Control-Allow-Origin: *. Endpointy można wołać fetch() z przeglądarki na dowolnej domenie, bez credentials: "include" — API nie używa ciasteczek.
  • Parametry z polskimi znakami trzeba zakodować (Czyżowice → Czy%C5%BCowice).
  • null znaczy „nie zgłoszono”, nigdy zero. Dotyczy to danych SIO, szeregów GUS i pól rejestrowych — braku nie wolno interpretować jako wartości zerowej.
  • Dane kontaktowe (phone, mobile, fax, email i profile społecznościowe) zwraca wyłącznie GET /api/institutions/{id}, po jednej placówce na zapytanie. Listy ich nie zawierają, żeby nie służyły do masowego pobierania kontaktów.
  • description też zwraca tylko GET /api/institutions/{id} — nie ze względu na dane, a na wagę: to jedyne pole z dowolnym tekstem obok samych enumów i liczb, więc na liście waży więcej niż cała reszta wiersza.
  • Zespół szkół nie jest sumowany ze swoimi szkołami. W SIO uczniowie są wykazywani przy szkołach członkowskich, a nauczyciele przy zespole.

Pełny opis pól, słowników i reguł interpretacji danych: https://mapaoswiatowa.pl/dla-deweloperow oraz https://mapaoswiatowa.pl/llms.txt.

Schematy odpowiedzi opisane są słownie — API nie gwarantuje zamkniętej listy pól w obiekcie i może dodawać nowe. Zamknięte są natomiast słowniki parametrów (type, subtype, operatorType, religion, pedagogy), wyliczone w components/schemas.

Endpoints 33

Placówki

  • GETPaginowana lista placówek/api/institutionsLista placówek z filtrami, sortowaniem i stronicowaniem. Bez danych kontaktowych i bez description — te zwraca wyłącznie GET /api/institutions/{id}.…
  • GETPlacówki w promieniu od punktu/api/institutions/nearby?lat=49.9828&lng=18.4088Placówki w promieniu, domyślnie posortowane rosnąco po odległości, z polem distance w kilometrach. Bez danych kontaktowych i bez description. Odpowiedź: {…
  • GETPełny profil placówki/api/institutions/:idPonad 50 pól: adres, kontakt, opłaty, zdjęcia z atrybucją, zawody w technikach, statystyki SIO (sioStats, sioAvailability), progi punktowe rekrutacji…
  • GETNajczęściej oglądane placówki/api/institutions/popularDzienna próbka placówek z opisem i niezerową liczbą odsłon. Zestaw zmienia się raz na dobę.

Wyszukiwanie

  • GETWyszukiwarka miejscowości, dzielnic, placówek i kodów pocztowych/api/locations/search?q=CzyżowiceJedyny sposób zamiany nazwy miejscowości na współrzędne — API nie geokoduje nazw w żadnym innym endpoincie. Dopasowanie po początku nazwy. Zwraca results[] z…
  • GETNajbliższa miejscowość dla współrzędnych/api/locations/reverse?lat=49.9828&lng=18.4088Najbliższa miejscowość dla podanych współrzędnych.

Miejscowości

  • GETMiejscowości z liczbą placówek/api/citiesMiejscowości posortowane malejąco po liczbie placówek. Wiersze niosą countySlug i countyIsCity (miasto na prawach powiatu — jego URL powiatowy tylko…
  • GETSzczegóły miejscowości/api/cities/:slugStatystyki miejscowości, rozbicie na typy placówek i dane zewnętrzne: lat/lng — środek miejscowości z PRNG (punkt główny wsi lub miasta, dokładność ~30 m),…

Podziały administracyjne

  • GETWszystkie powiaty albo wszystkie gminy/api/divisions?level=powiatJednostki jednego poziomu podziału administracyjnego — dane pod stronami /powiaty i /gminy. level=powiat zwraca 380 powiatów (w tym 66 miast na prawach…
  • GETPowiaty województwa/api/divisions/:wojLista powiatów: slug, name (nazwa rejestrowa — dla powiatów ziemskich przymiotnik małą literą), terytCode (4 cyfry TERC), isCityCounty, citySlug,…
  • GETSzczegóły powiatu/api/divisions/:woj/:powiattotals (placówki wg typu), operatorMix (organy prowadzące; operatorType: null to „rejestr nie podaje”), municipalities[] z rozbiciem na miejscowości,…
  • GETSzczegóły gminy/api/divisions/:woj/:powiat/:gminamunicipality (z kind: miejska/wiejska/miejsko-wiejska), totals, localities[] (miejscowości gminy z placówkami, z isSeat — heurystyka imiennika, brak trafienia…
  • GETSzczegóły dzielnicy/api/districts/:city/:districtJedna z 51 jednostek: 18 dzielnic Warszawy (jednostki pomocnicze z ustawy warszawskiej), 18 dzielnic Krakowa (jednostki pomocnicze ze statutu miasta) i 15…
  • GETStatystyki województwa/api/voivodeships/:slugRozbicie na typy placówek, 10 największych miast oraz education[] — oficjalne szeregi GUS BDL per rok (2008–2024): preschools, preschoolChildren,…

Statystyki

  • GETAgregaty ogólnokrajowe/api/statisticsLiczby placówek wg typu, subtypu i województwa, top 10 miast, podział publiczne/prywatne oraz skalary sio* — krajowe sumy SIO za najnowszy rok szkolny…
  • GETStatystyki opłat w żłobkach i przedszkolach/api/statistics/fees?type=NURSERYGdy w mieście jest za mało danych, zakres rozszerza się automatycznie do województwa, a potem do kraju — pole scope mówi, jakiego obszaru faktycznie dotyczy…
  • GETKrajowy rozkład opłat w żłobkach/api/statistics/nursery-feesKraj w jednej odpowiedzi, w przeciwieństwie do /api/statistics/fees, które odpowiada dla wskazanego obszaru. Niesie kwartyle opłaty miesięcznej…
  • GETGdzie są miejsca w żłobkach/api/statistics/nursery-placesKraj w jednej odpowiedzi, na wzór /api/statistics/nursery-fees, ale nad drugą parą kolumn rejestru: liczbą miejsc i liczbą dzieci. Zwraca national, bySector,…
  • GETKrajowe trendy zawodów szkolnictwa branżowego/api/statistics/vocational-trendsDane SIO (dane.gov.pl, zbiór 1617, CC0): years[], latestYear, previousYear, professions[] (nazwa, branża z klasyfikacji 2025/26, seria per rok szkolny:…
  • GETPrognoza demograficzna GUS w grupach wieku edukacyjnego/api/statistics/demographic-forecastPrognoza ludności GUS na lata 2023–2060 (scenariusz główny, dane z 2024-07-12, CC BY 4.0): poland[] i voivodeships[] z seriami age0_2, age3_6, age7_14,…
  • GETZatrudnienie specjalistów i nauczane języki/api/statistics/specialistsDane z otwartego eksportu CSV RSPO: registryAsOf (stan rejestru), national, byVoivodeship[], byType[], byUrbanRural[] i languages[]. Odsetki licz zawsze od…
  • GETWyniki egzaminu ósmoklasisty i matury według województw/api/statistics/exams?exam=E8Jeden egzamin — E8 (egzamin ósmoklasisty) albo EM2023 (matura w formule od 2023 r.) — dla 16 województw: years[], voivodeships[] (terytCode, slug, name,…

Patroni

  • GETWyszukiwarka patronów/api/patrons/search?q=JanPatroni szkół z liczbą placówek.
  • GETNajpopularniejsi patroni/api/patrons/topPatroni z liczbą placówek i slug strony patrona.
  • GETStatystyki patronów/api/patrons/statsLiczba placówek z patronem, top 10, najczęstszy patron wg typu placówki, podział na kategorie i płeć. Klasyfikacja jest automatyczna — classifiedAt mówi,…
  • GETPatron po slugu/api/patrons/:slugZwraca { patron, count, slug }. Patron z mniej niż 10 placówkami nie ma własnej strony i odpowiada 404.

Kształcenie zawodowe

  • GETZawody nauczane w technikach i szkołach branżowych/api/vocational/professionsZawody przypisane placówkom w RSPO — słownik do podpowiedzi i filtrowania. To nie to samo co /api/statistics/vocational-trends, które niesie krajowe szeregi…
  • GETPełny katalog zawodów z liczbą szkół/api/vocational/professions/allCały katalog w jednej odpowiedzi (~250 pozycji), od najczęściej nauczanego. count to liczba szkół w rejestrze kształcących w zawodzie — nie zestawiaj jej z…
  • GETJeden zawód/api/vocational/professions/:slugRozwiązuje slug strony /zawody/{slug} z powrotem na zawód. branchName pochodzi z zestawień SIO i bywa null — dla ok. 9 zawodów rejestru SIO nie prowadzi…
  • GETDoradca zawodowy: zawody dobrane do odpowiedzi w wybranym obszarze/api/vocational/advisor?obszar=miejscowoscWynik doradcy Jaki zawód wybrać? — te same parametry co adres wyniku /jaki-zawod-wybrac/wynik, czytane tym samym parserem. Kandydatem jest wyłącznie zawód,…
  • GETDoradca zawodowy: szkoły uczące jednego zawodu w zasięgu i najbliższe poza nim/api/vocational/advisor/schools?obszar=miejscowosc&profession=Technik informatykSzkoły dla jednego zawodu z wyniku doradcy: parametry /api/vocational/advisor i profession (nazwa z rejestru RSPO, jak name kandydata). Odpowiedź: area…

Źródła danych

  • GETŹródła danych i ich aktualność/api/data-sourcesWszystkie źródła, z których zbudowany jest serwis, z licencją, wymaganą atrybucją i dwiema różnymi datami. refreshedAt — kiedy nasz import zapisał to źródło…

Status

  • GETStan usługi/healthSprawdza dostępność API i jego bazy danych. Endpoint statusowy wskazywany relacją status w katalogu API (/.well-known/api-catalog).

API details

Base URL
https://api.mapaoswiatowa.pl
Authentication
None declared in the description
Operations
33 operations on 33 pathsGET 33
Main resources
Statystyki 8Podziały administracyjne 6Kształcenie zawodowe 5Patroni 4Placówki 4Miejscowości 2Wyszukiwanie 2Status 1Źródła danych 1
Response formats
application/json
Description format
OpenAPI 3.1.0, API version 2026-10-28

How to test the Mapa Oświatowa — publiczne API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Mapa Oświatowa — publiczne API collection, without the publisher's secrets.
  3. Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
  4. Send a requestPick an endpoint, for example “Paginowana lista placówek” (GET /api/institutions), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Mapa Oświatowa — publiczne API?

Publiczne API serwisu Mapa Oświatowa. Wszystkie opisane niżej endpointy to GET, bez uwierzytelniania i bez klucza, odpowiedzi w JSON (UTF-8). Zasady, które… It is listed under Data & analytics and has 33 endpoints.

Who publishes the Mapa Oświatowa — publiczne API?

It is listed from Mapaoswiatowa's public API description (an OpenAPI document), not published by Mapaoswiatowa on Swastik Codes. Anyone who controls mapaoswiatowa.pl can claim the profile by adding a DNS TXT record.

What is the base URL of the Mapa Oświatowa — publiczne API?

Requests go to https://api.mapaoswiatowa.pl. Endpoint paths are added to this base URL.

How do I authenticate with the Mapa Oświatowa — publiczne API?

Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.

How many endpoints does the Mapa Oświatowa — publiczne API have?

33 operations on 33 paths (33 GET). The largest groups are Statystyki, Podziały administracyjne, Kształcenie zawodowe, Patroni.

Is forking the Mapa Oświatowa — publiczne API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.