{
 "openapi": "3.1.0",
 "info": {
  "title": "PolskieAdresy.pl API",
  "version": "1.0.0",
  "description": "Wyszukiwanie adresów, kodów pocztowych i kodów TERYT w Polsce. Dane: PRG (GUGiK), TERYT (GUS), Wikidata.",
  "contact": {
   "url": "https://polskieadresy.pl/api/"
  }
 },
 "servers": [
  {
   "url": "https://polskieadresy.pl"
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   }
  }
 },
 "security": [
  {},
  {
   "apiKey": []
  }
 ],
 "paths": {
  "/api/v1/szukaj": {
   "get": {
    "operationId": "szukaj",
    "summary": "Wyszukiwanie i autouzupełnianie adresów",
    "description": "Pełnotekstowe wyszukiwanie w trakcie pisania. Rozpoznaje numer budynku, kod pocztowy, skróty (ul., al.) i poprawia literówki. Zwraca adresy, ulice, miejscowości lub kody pocztowe.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "Zapytanie, np. „Marszałkowska 10 Warszawa”, „00-590”, „Nowa Wieś gm. Łomianki”",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1–50, domyślnie 10",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "typ",
      "in": "query",
      "required": false,
      "description": "Ogranicz do: miejscowosc | ulica",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/geokoduj": {
   "get": {
    "operationId": "geokoduj",
    "summary": "Geokodowanie i walidacja adresu",
    "description": "Dopasowuje „brudny” adres do rejestru PRG i zwraca najlepszy wynik z oceną pewności (score 0–1) oraz statusem: dopasowano | niska_pewnosc | czesciowe | nie_znaleziono.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "Adres w dowolnej postaci",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   },
   "post": {
    "operationId": "geokodujBatch",
    "summary": "Geokodowanie wsadowe (do 1000 adresów)",
    "description": "Body JSON: {\"adresy\": [\"adres 1\", \"adres 2\", …]}. Każdy adres liczy się jako jedno zapytanie w limicie.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "adresy": {
          "type": "array",
          "maxItems": 1000,
          "items": {
           "type": "string"
          }
         }
        },
        "required": [
         "adresy"
        ]
       }
      }
     }
    }
   }
  },
  "/api/v1/odwrotne": {
   "get": {
    "operationId": "odwrotne",
    "summary": "Geokodowanie odwrotne (współrzędne → adres)",
    "description": "Najbliższe punkty adresowe do podanych współrzędnych WGS84 wraz z odległością w metrach.",
    "parameters": [
     {
      "name": "lat",
      "in": "query",
      "required": true,
      "description": "Szerokość geograficzna",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": true,
      "description": "Długość geograficzna",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "radius",
      "in": "query",
      "required": false,
      "description": "Promień w metrach, 1–5000, domyślnie 500",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1–50, domyślnie 1",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/kod-dla-adresu": {
   "get": {
    "operationId": "kodDlaAdresu",
    "summary": "Kod pocztowy dla adresu",
    "description": "Zwraca kod pocztowy dla dokładnego adresu podanego w polach.",
    "parameters": [
     {
      "name": "miejscowosc",
      "in": "query",
      "required": true,
      "description": "Nazwa miejscowości",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "ulica",
      "in": "query",
      "required": false,
      "description": "Nazwa ulicy (pomiń dla miejscowości bez ulic)",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "nr",
      "in": "query",
      "required": true,
      "description": "Numer budynku",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "simc",
      "in": "query",
      "required": false,
      "description": "SIMC miejscowości — rozstrzyga niejednoznaczne nazwy",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/kod-pocztowy/{kod}": {
   "get": {
    "operationId": "kodPocztowy",
    "summary": "Ulice i miejscowości dla kodu pocztowego",
    "description": "Miejscowości, ulice i zakresy numerów przypisane do kodu pocztowego.",
    "parameters": [
     {
      "name": "kod",
      "in": "path",
      "required": true,
      "description": "Kod w formacie XX-XXX",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/adres/{id}": {
   "get": {
    "operationId": "adres",
    "summary": "Szczegóły adresu",
    "description": "Pełne dane adresu po identyfikatorze serwisu. Alternatywnie /api/v1/adres?prg={uuid} — po identyfikatorze PRG.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "ID adresu",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/miejscowosci": {
   "get": {
    "operationId": "miejscowosci",
    "summary": "Autouzupełnianie miejscowości",
    "description": "Miejscowości pasujące do prefiksu nazwy, posortowane wg wielkości.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "Początek nazwy",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1–50",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/miejscowosc/{simc}": {
   "get": {
    "operationId": "miejscowosc",
    "summary": "Miejscowość wg SIMC",
    "description": "Dane miejscowości z kodami pocztowymi, ludnością i odnośnikami do Wikidata.",
    "parameters": [
     {
      "name": "simc",
      "in": "path",
      "required": true,
      "description": "7-cyfrowy kod SIMC",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/ulice": {
   "get": {
    "operationId": "ulice",
    "summary": "Autouzupełnianie ulic w miejscowości",
    "description": "Ulice danej miejscowości pasujące do prefiksu nazwy.",
    "parameters": [
     {
      "name": "simc",
      "in": "query",
      "required": true,
      "description": "SIMC miejscowości",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Początek nazwy ulicy",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1–500, domyślnie 20",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/ulica/{id}": {
   "get": {
    "operationId": "ulica",
    "summary": "Ulica z listą adresów",
    "description": "Wszystkie numery budynków ulicy z kodami pocztowymi i współrzędnymi.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "ID ulicy (pole id z wyników)",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/teryt/{kod}": {
   "get": {
    "operationId": "teryt",
    "summary": "Dekodowanie kodu TERYT",
    "description": "Rozpoznaje: 2 cyfry — województwo, 4 — powiat, 7 cyfr — SIMC miejscowości lub TERC gminy, SIMC+ULIC (12 cyfr) — ulica.",
    "parameters": [
     {
      "name": "kod",
      "in": "path",
      "required": true,
      "description": "Kod TERYT",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/dzialka": {
   "get": {
    "operationId": "dzialka",
    "summary": "Działka ewidencyjna w punkcie",
    "description": "Identyfikator działki ewidencyjnej (ULDK GUGiK) dla współrzędnych.",
    "parameters": [
     {
      "name": "lat",
      "in": "query",
      "required": true,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": true,
      "description": "",
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/adres/{id}?pelne=1": {
   "get": {
    "operationId": "adresPelne",
    "summary": "Adres z obwodem wyborczym, cenami mieszkań i szkołami",
    "description": "Jak /adres/{id}, plus obwód głosowania i okręgi, mediany cen mieszkań (budynek, ulica, miejscowość, gmina) i 5 najbliższych szkół.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "ID adresu",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/wybory": {
   "get": {
    "operationId": "wybory",
    "summary": "Obwód głosowania i okręgi wyborcze dla adresu",
    "description": "Lokal wyborczy (obwód PKW, wybory 2025) oraz okręg do Sejmu i Senatu (2023). Adres przez adres_id albo współrzędne.",
    "parameters": [
     {
      "name": "adres_id",
      "in": "query",
      "required": false,
      "description": "ID adresu",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/obwod-glosowania/{teryt-nr}": {
   "get": {
    "operationId": "obwod",
    "summary": "Obwód głosowania",
    "description": "Siedziba komisji i opis granic obwodu, np. 146510-38.",
    "parameters": [
     {
      "name": "teryt-nr",
      "in": "path",
      "required": true,
      "description": "Kod gminy PKW i numer obwodu",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/szkoly": {
   "get": {
    "operationId": "szkoly",
    "summary": "Szkoły i przedszkola",
    "description": "Placówki w pobliżu punktu (z odległością), w miejscowości (simc) lub gminie (terc). Filtr typ, np. „przedszkole”, „podstawowa”, „liceum”.",
    "parameters": [
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "radius",
      "in": "query",
      "required": false,
      "description": "metry, domyślnie 2000",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "simc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "terc",
      "in": "query",
      "required": false,
      "description": "7 cyfr",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "typ",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "do 200",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/szkola/{rspo}": {
   "get": {
    "operationId": "szkola",
    "summary": "Szkoła wg numeru RSPO",
    "description": "Adres, typ, liczba uczniów, oddziałów i nauczycieli, organ prowadzący, położenie.",
    "parameters": [
     {
      "name": "rspo",
      "in": "path",
      "required": true,
      "description": "Numer RSPO",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/ceny/mieszkania": {
   "get": {
    "operationId": "ceny",
    "summary": "Ceny transakcyjne mieszkań",
    "description": "Mediana i kwartyle zł/m², liczba transakcji i trend półroczny z Rejestru Cen Nieruchomości (ostatnie 24 miesiące, min. 5 transakcji). Dla adresu (adres_id lub lat/lon — zwraca budynek, ulicę, miejscowość, gminę) albo dla simc, ulica_id, terc, kod.",
    "parameters": [
     {
      "name": "adres_id",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "simc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "ulica_id",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "terc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kod",
      "in": "query",
      "required": false,
      "description": "XX-XXX",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/ceny/domy": {
   "get": {
    "operationId": "cenyDomy",
    "summary": "Ceny transakcyjne domów",
    "description": "Mediana ceny domu (grunt zabudowany budynkiem mieszkalnym) oraz zł/m² powierzchni użytkowej; dla adresu (adres_id, lat/lon), miejscowości (simc), gminy lub powiatu (terc).",
    "parameters": [
     {
      "name": "adres_id",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "simc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "terc",
      "in": "query",
      "required": false,
      "description": "7 cyfr (gmina) lub 4 (powiat)",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/ceny/dzialki": {
   "get": {
    "operationId": "cenyDzialki",
    "summary": "Ceny transakcyjne działek",
    "description": "Mediana zł/m² działek niezabudowanych: budowlanych (domyślnie) lub rolnych i leśnych (rodzaj=rolne). Parametry jak w /ceny/domy.",
    "parameters": [
     {
      "name": "rodzaj",
      "in": "query",
      "required": false,
      "description": "budowlane | rolne",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "simc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "terc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "adres_id",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/gmina/{terc}": {
   "get": {
    "operationId": "gmina",
    "summary": "Gmina: statystyki GUS i ceny",
    "description": "Ludność, powierzchnia, gęstość, struktura wieku, migracje, przyrost naturalny, bezrobocie, dochody na mieszkańca, mieszkania, podmioty REGON (GUS BDL) oraz mediany cen mieszkań, domów i działek.",
    "parameters": [
     {
      "name": "terc",
      "in": "path",
      "required": true,
      "description": "7-cyfrowy kod TERC",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/teryt/zmiany": {
   "get": {
    "operationId": "terytZmiany",
    "summary": "Historia zmian TERYT",
    "description": "Zmiany w rejestrze TERYT od 1999 r. (GUS): nowe i zniesione jednostki, zmiany nazw i rodzajów miejscowości, ulice. Filtry: kod (SIMC/TERC/SIMC+ULIC — zmiany danego obiektu, także jako następcy), rok, rejestr. Także /api/v1/teryt/{kod}/zmiany. Dla kodu usuniętego z rejestru /api/v1/teryt/{kod} zwraca następcę.",
    "parameters": [
     {
      "name": "kod",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "rok",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "rejestr",
      "in": "query",
      "required": false,
      "description": "TERC | SIMC | ULIC",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "do 5000, domyślnie 200",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/normalizuj/plik": {
   "post": {
    "operationId": "normalizujPlik",
    "summary": "Normalizacja pliku CSV/XLSX",
    "description": "Prześlij plik (multipart, pole \"plik\") lub surowy CSV w body. Kolumny rozpoznawane automatycznie albo wskazane parametrami kolumna_adres / kolumna_ulica, kolumna_numer, kolumna_kod, kolumna_miejscowosc (nazwa lub numer kolumny od 1). Zwraca plik (format=csv|xlsx) albo JSON (format=json) z dodanymi kolumnami: status, pewność, adres znormalizowany, kod, TERYT, współrzędne. Każdy wiersz liczy się jako zapytanie; bez klucza do 200 wierszy.",
    "parameters": [
     {
      "name": "format",
      "in": "query",
      "required": false,
      "description": "csv | xlsx | json",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kolumna_adres",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kolumna_ulica",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kolumna_numer",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kolumna_kod",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kolumna_miejscowosc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "adresy": {
          "type": "array",
          "maxItems": 1000,
          "items": {
           "type": "string"
          }
         }
        },
        "required": [
         "adresy"
        ]
       }
      }
     }
    }
   }
  },
  "/api/v1/komunikacja": {
   "get": {
    "operationId": "komunikacja",
    "summary": "Komunikacja publiczna przy adresie",
    "description": "Najbliższe przystanki (zgrupowane perony) z liniami, liczbą odjazdów w dzień roboczy i godzinami pierwszego/ostatniego odjazdu, odległość do przystanku i stacji kolejowej oraz ocena dostępności komunikacyjnej. Rozkłady GTFS miast i kolei; w innych miejscowościach przystanki z BDOT10k (bez rozkładu).",
    "parameters": [
     {
      "name": "adres_id",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "radius",
      "in": "query",
      "required": false,
      "description": "100–2000 m, domyślnie 800",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/zabudowa": {
   "get": {
    "operationId": "zabudowa",
    "summary": "Struktura zabudowy",
    "description": "Udział adresów w budynkach jednorodzinnych, wielorodzinnych i innych, średnia i maksymalna liczba kondygnacji, budynki w budowie — dla ulicy, miejscowości lub gminy (BDOT10k). Dla pojedynczego adresu pole budynek jest w /api/v1/adres/{id}.",
    "parameters": [
     {
      "name": "simc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "ulica_id",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "terc",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/porownaj": {
   "get": {
    "operationId": "porownaj",
    "summary": "Porównanie gmin",
    "description": "Pełne metryki dla wielu gmin naraz (do 10): ludność, demografia, bezrobocie, dochody, REGON, mieszkania, nowe adresy wg lat, ceny mieszkań/domów/działek, szkoły, adresy, odległość do morza.",
    "parameters": [
     {
      "name": "terc",
      "in": "query",
      "required": true,
      "description": "kody TERC po przecinku, np. 1261011,0264011",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/rankingi/gminy/{wskaznik}": {
   "get": {
    "operationId": "rankingi",
    "summary": "Ranking gmin",
    "description": "Gminy uszeregowane wg wskaźnika (lista: /api/v1/rankingi/gminy). Filtry: województwo (kod 2-cyfrowy lub nazwa), rodzaj gminy, kolejność.",
    "parameters": [
     {
      "name": "wskaznik",
      "in": "path",
      "required": true,
      "description": "np. dochody, bezrobocie, cena_m2_mieszkania",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "woj",
      "in": "query",
      "required": false,
      "description": "np. 12 lub malopolskie",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "typ",
      "in": "query",
      "required": false,
      "description": "miejskie | wiejskie | miejsko-wiejskie",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kolejnosc",
      "in": "query",
      "required": false,
      "description": "malejaco | rosnaco",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "do 3000",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/gminy": {
   "get": {
    "operationId": "gminy",
    "summary": "Wyszukiwanie gmin",
    "description": "Autouzupełnianie nazw gmin (całych gmin, z kodem TERC) — np. do porównywarki.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  },
  "/api/v1/status": {
   "get": {
    "operationId": "status",
    "summary": "Stan danych",
    "description": "Data danych PRG i TERYT oraz liczby rekordów.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Błędne parametry"
     },
     "429": {
      "description": "Limit zapytań"
     }
    }
   }
  }
 }
}