Kody Pocztowe PL

What is Kody Pocztowe PL?

Kody Pocztowe PL ("Polish Postal Codes") turns the official spispna.pdf register published by Polish Post into a structured, searchable database. It parses roughly 115,000 postal codes — covering cities, streets, house numbers, communities, counties, and voivodeships — and gives you an admin panel, a public-facing search widget, and a token-protected REST API to query that data from your own applications.

Feature Overview

Installation

Kody Pocztowe PL ships with a one-click web installer — there is no Composer step and no manual SQL to run by hand.

Login & Security

Access to the admin panel is protected by a session-based login system, with every state-changing request guarded by a CSRF token and every database query built with PDO prepared statements.

Dashboard & Database Status

The dashboard is the first screen after login. It shows database connection status, your license plan, the loaded PDF version, and a per-table breakdown of how many records are stored.

Each table row shows whether it is Filled or Empty, along with its record count, so you can see at a glance which parts of the register still need to be loaded.

PDF Parser

The parser reads the official spispna.pdf register page by page and writes the extracted records into MySQL (or a downloadable CSV file).

Loading the Source File

You can either upload a PDF from disk or let the app download it from a URL — by default the official Polish Post address, configurable in Configuration if it ever changes. After loading, the app automatically detects the file's version (month and year of release).

Parsing Options

Parsing targets either the MySQL database or a CSV export, and you can choose which of the 4 parts to process in a single run. Progress is streamed live in the parsing log, with a Stop button to halt after the current page.

Quarterly Updates

Polish Post publishes a new PNA register roughly every three months. To refresh your data: upload the new PDF, choose Clear tables before loading (or Keep if you only want to append new entries), and start parsing again.

Index Optimization

After a full import, use the Optimize Indexes button in Configuration. It runs ANALYZE + OPTIMIZE TABLE across all four tables, defragmenting the index tree and refreshing the query optimizer's statistics.

Search Engine & Public Widget

Once data is loaded, records can be searched from the admin panel — and optionally exposed to the public as a standalone page or an embeddable widget.

Each result row shows the postal code, city, street and house-number range, district (gmina), county (powiat), and voivodeship. Results are paginated — the number of rows per page is configurable in Configuration.

Public Search & Embeddable Widget

Enabling public access to the search engine in Configuration exposes a search page that works without any login — ready to be shared directly with customers or embedded on your own website via a ready-made <iframe> snippet generated on the same settings page.

Statistics & Charts

The Statistics page gives a quick overview of how the search engine and API are being used, plus a breakdown of your loaded data.

REST API Documentation

The JSON REST API lets external applications look up postal codes programmatically. It requires a valid API token (Pro plan or higher) and responds over a single endpoint, api/index.php.

Authentication

Pass your token in one of two ways:

Authorization: Bearer YOUR_TOKEN_HERE

GET /api/index.php?action=lookup&token=YOUR_TOKEN_HERE&pna=00-001

The header method is recommended for production use since URL-embedded tokens can end up in server access logs. The URL parameter is convenient for quick tests or integrations (e.g. an embedded iframe) where setting custom headers isn't practical.

Lookup Endpoint

A single action=lookup endpoint accepts one of three mutually-exclusive search parameters:

The search term must be at least 2 characters long.

Response Format

Success (HTTP 200):

{
    "success": true,
    "data": {
        "total": 42,
        "page": 1,
        "per_page": 10,
        "results": [ { "pna": "00-001", "city": "Warszawa", "street": "..." } ]
    }
}

Error (HTTP 400 / 401 / 403 / 429):

{
    "success": false,
    "message": "Nieprawidłowy lub brak tokenu autoryzacyjnego."
}

HTTP Status Codes

Managing API Tokens

Every API call is authenticated with a token created and managed from the API Tokens page in the admin panel.

System Requirements

Kody Pocztowe PL is a self-hosted application — install it on any standard PHP/MySQL hosting account.

License Comparison

Kody Pocztowe PL is licensed per domain, with three tiers that unlock progressively more of the application.

Frequently Asked Questions

Common questions about deploying and using Kody Pocztowe PL.

How often do I need to update the postal code data?

Polish Post publishes a new spispna.pdf register about every three months. Re-run the parser with the new file whenever a new release is available — the app can detect the loaded PDF's version automatically.

Do I need Composer or any external libraries?

No. The application has zero Composer dependencies and ships as a single self-contained folder — upload it, run the installer, and you're done.

Can I embed the search widget on my own website?

Yes, on the Pro plan or higher. Enable public search in Configuration and copy the generated <iframe> embed code onto your site.

What happens if I leave install.php on the server?

The Configuration page will keep showing a security warning until it's deleted, since a reachable installer could be used to overwrite your existing data. Delete it (or use the in-app button) right after setup.

Can I run this on multiple domains?

Yes — licensing is per domain. The Basic plan covers 1 domain, Pro covers 5, and Developer is unlimited.

Is the REST API rate-limited?

Yes. Each API token can have its own hourly and daily request limits, plus an optional IP whitelist, configured from the API Tokens page.