API usage policy

Rate limits

• Keyless: 60 requests per minute per IP address. The limit is shared by every anonymous caller behind one address (NAT, VPN, a shared server) — this is the behaviour-parity contract with pacjenteo and stays unchanged.
• With an API key: the limit assigned to the key (set individually), in its own bucket — keyed traffic does not compete with anonymous traffic.
• Exceeding a limit answers HTTP 429 with a Retry-After header — please honour it instead of retrying immediately.
• GET responses carry Cache-Control: max-age=86400 and an ETag. Client-side caching is expected — the register data changes at most once a day.

Identification

Please identify yourself in at least one of these ways:

• A custom User-Agent naming your application (e.g. my-app/1.2 (+https://example.com)). Stock HTTP library user agents (axios/1, Go-http-client/1.1, python-requests) describe your library, not your application — they do not count as identification.
• An X-API-Key header with a key issued by the operator (below).

Browser-based callers are attributed automatically from the Origin/Referer headers. What exactly the server sees about your requests: GET /v1/whoami.

API keys

A key identifies your integration in the operator's traffic analytics and gives it a rate limit of its own. Apply through the application form (Polish UI — you can describe your integration in English), stating:

• the name and address of the application or company,
• a contact person,
• the approximate volume (requests/minute and per day) and which endpoints you use.

Keys are issued manually; approval is answered at the contact address you provide. A key is shown exactly once when issued — only its hash is stored, so the operator cannot recover it. Treat it like a password: never commit it to a repository or ship it in browser-visible client code. A key can be revoked at any time — requests presenting it answer 401 from that moment.

Questions, API key requests and abuse reports: [email protected].

Data and attribution

This API is a compilation of public registers. When you use the results, please state the sources — for GeoNames this is a licence requirement:

GUS TERYT (SIMC, TERC, ULIC) — localities, administrative hierarchy, streets

PRG address points (GUGiK) — address validation and geocoding

Postal codes and coordinates — GeoNames

Note: this is an unofficial treatment of public registers. The service is not a product of GUS or GUGiK and does not replace the source registers — where official certainty matters, please use the original sources.

Prohibited use

The following uses are prohibited and will get the address or key blocked:

• Bulk downloading (scraping) — systematically walking the register, grid queries (reverse geocoding on a regular grid), downloading complete lists of localities, streets or codes. The source data is publicly available — please download it from there, not through this API.
• Reselling or re-exposing the API — offering this service as your own API, as a proxy for third-party applications, or as a ready-made "connector" on no-code/low-code platforms.
• Sharing one key across unrelated products — every integration gets its own key (free of charge).
• Circumventing the limits — rotating IP addresses, spreading queries over multiple keys, clients that ignore Retry-After.
• Keystroke-by-keystroke browser autocomplete without caching — that is what Cache-Control and a local response cache are for.

Availability and changes

The service is in beta and runs best-effort — without an SLA. These rules may change; material limit changes for existing keys will be communicated through the contact recorded when the key was issued. The keyless limit (60/min/IP) will not be lowered without notice.

Contact

Questions, API key requests and abuse reports: [email protected].