---
name: tallinn-document-register
description: Search the correspondence, orders and contracts registered by Tallinn's district governments, city offices and city schools.
module: tallinn.mjs
execution: get
---

# Tallinn Document Register (dhs.tallinn.ee/atp)

**Tallinn runs two public registers and they hold different things.**

- **This one** — `dhs.tallinn.ee/atp`, "Tallinna ametiasutuste dokumendiregister" — is the correspondence register: letters in and out, teabenõuded, käskkirjad, contracts, applications. It is what a citizen means by *dokumendiregister*, and it is the register the eight district governments and Tallinna Linnavalitsus keep.
- **TEELE** — `teele.tallinn.ee`, guide `tallinn-council-documents` — is the city COUNCIL's adopted legal acts: otsused, määrused, eelnõud. A raieluba, a reply to a resident's letter or a contract is not in it.

Asking one for the other's records returns a clean, empty-looking answer. Read the question first: an act the council passed is TEELE, everything a body sent or received is here.

## Access

Everything is a plain GET over HTTPS. No session, no cookie, no token, no JavaScript.

**Fetch this register directly; do not route it through `tallinn.mjs`.**
`dhs.tallinn.ee` blocks by network address rather than by request shape: measured
2026-08-02, the identical URL answered `HTTP 403 Forbidden ... You don't have permission
to access /atp/` from a datacentre address and 200 from an ordinary one. Whether it
answers you therefore depends on where your requests leave from, not on how you make
them, and a 403 here is this block rather than a bad URL. Build the URL below and fetch
it with whatever ordinarily fetches a page for you.

**That costs you the body list, which is the one thing you cannot guess.** The `asutus` id
exists only in the register's own dropdown — Kesklinn is 5, Haabersti 12, Põhja-Tallinn 21 —
and **a wrong id answers HTTP 200 with somebody else's documents**, or with zero rows, which
reads as an empty register. So fetch `https://dhs.tallinn.ee/atp/` first and
read the `<select name="asutus">` options out of it. Note the register calls Tallinna
Linnavalitsus **Tallinna Linnakantselei**. Never guess an id, and never report a count without
checking that the rows' own `Asutus:` line names the body you asked for — that echo is the only
proof the filter applied.


- Register: `https://dhs.tallinn.ee/atp/`
- Search: `https://dhs.tallinn.ee/atp/?c_tpl=1092&command=search&asutus=<id>&pealkiri=<term>&pealkiri_meetod=1&page=1`
- One document: `https://dhs.tallinn.ee/atp/?c_tpl=1092&command=details&dok_id=<id>`
- Results are 15 rows a page, newest first, and page past the last one to get zero rows with the count unchanged.

**`c_tpl=1092` is not optional.** Without it the same query answers HTTP 200 with the register's front page — 35,847 bytes, no error, no count line and no rows — which is a request that never searched dressed as a healthy page.

```probe-limit
claim Without it the same query answers HTTP 200 with the register's front page
GET https://dhs.tallinn.ee/atp/?command=search&asutus=12&pealkiri=leping
expect-status 200
# The front page is the one page carrying `limitform`, the institution
# selector. A results page has `documents_container` and a `Kokku leiti` line
# and no limitform at all, so this pattern is exactly "you got the front page".
expect /name="limitform"/
# The control is the SAME query with c_tpl back. It must fail the pattern
# above — that is what separates "c_tpl is required" from "this register now
# serves its front page to everything", which would confirm the claim while
# meaning the opposite.
control GET https://dhs.tallinn.ee/atp/?c_tpl=1092&command=search&asutus=12&pealkiri=leping
```

## Retrieve

`tallinnDocuments(body, term, {limit, match, from, to, direction})` in `tallinn.mjs` is the whole interface. It sends only names verified to narrow the result, resolves the body against the register's own list, pages safely and reports the register's own count.

```js
const r = await tallinnDocuments("Põhja-Tallinna Valitsus", "raieluba", { from: "2025-01-01", to: "2025-12-31" });
show(r);
```

- `body` is an institution name; aliases work (`"Kesklinn"`). Pass `null` to search every body at once — right for "which Tallinn body handled this", wrong for "what does Haabersti have".
- `term` matches the **title** as a substring, minimum 3 characters.
- `match` is `"all"` (default), `"phrase"` or `"any"`.
- `from` / `to` take `yyyy-mm-dd` and are sent in the register's own dd.mm.yyyy.
- `direction` is one of `sisemine`, `sisse`, `sissetulev`, `välja`, `väljaminev`.
- `limit` defaults to 20, caps at 60.

`tallinnBodies("<fragment>")` lists the registrars. **The register holds 273 of them and the institution table holds nine**: the eight district governments and Tallinna Linnavalitsus (which the register labels *Tallinna Linnakantselei*). The rest are the city offices — Haridusamet, Linnaplaneerimise Amet, Linnavaraamet, Sotsiaal- ja Tervishoiuamet — and the schools, kindergartens and culture centres under them, which is the only route this repo has into a Tallinn school's register.

**The `asutus` ids come from that list and nowhere else.** They are not registry codes and not derivable: Kesklinn is 5, Haabersti 12, Linnakantselei 1. The module reads them live for exactly that reason.

## Return

`{source, page, body, term, ran, scoped, totals:{shown, reported, register}, rows, note}`, each row `{ref, date, title, type, body, url}` with an ISO date and the document's own registration card.

- **`totals.reported` is the register's own count over the whole match. State counts from it, never by tallying `rows`.**
- `totals.register` is everything that body has ever registered, and it is there so the two can be compared — see Verify.
- `scoped` is the register's per-row echo: true when every row came back registered to the body you asked for. `null` means there was nothing to check — no body was named, or the search matched nothing.
- `ran: false` means the request was never accepted as a search. That is a broken request, **not** an empty register, and must never be reported as "no such document".

## Limits

- **A filter name this register does not know is ignored, not rejected**, and the answer is that body's entire register at HTTP 200. `asutuz=12`, `org=12` and `regkpXX_algus=01.01.2026` each come back with 46,064 and 54,691-row totals that look exactly like results. The module sends only verified names; `totals.reported == totals.register` is what catches the platform changing under it.
- **A date it cannot parse is dropped the same way.** `regkp_algus=2026-01-01` — the ISO spelling — answers 200 with the whole register and nothing says the range was ignored. Only dd.mm.yyyy filters.
- **`command=quick` is the front page's Kiirotsing and it ignores `asutus`.** `command=quick&pealkiri=leping&asutus=12` reports 46,064 — every body in Tallinn — where `command=search` with the same pair reports hundreds, all of them that body's. A count from the wrong command is the whole city's, attributed to one district.

```probe-limit
claim `command=quick` is the front page's Kiirotsing and it ignores `asutus`
GET https://dhs.tallinn.ee/atp/?c_tpl=1092&command=quick&pealkiri=leping&asutus=12
expect-status 200
# Five digits is the tell: the unscoped register answered 46,064 on 2026-08-02
# while Haabersti alone answered 487. If quick ever starts honouring asutus,
# this drops to hundreds and the claim fails, which is the point.
expect /Kokku leiti \d{5} dokumen[dt]/
# The control is command=search on the identical pair. It must fail the digit
# bound — that is the half proving the register still scopes at all, rather
# than the whole thing having shrunk below ten thousand documents.
control GET https://dhs.tallinn.ee/atp/?c_tpl=1092&command=search&pealkiri=leping&asutus=12
```

- **The other direction fails silently too**: a value the register does not recognise gives zero rather than the whole register. `suund=zzz`, an `asutus` id that no longer exists, and dropping `command` altogether all answer `Kokku leiti 0 dokumenti` — a zero that reads as "this body has nothing on file". The module validates those before sending.
- **A multi-word title search is empty by default.** `pealkiri_meetod` is 0 = fraas, 1 = kõik sõnad, 2 = üks sõnadest, and the register's own default is 0: `pealkiri=raie luba` matches 0 as a phrase, 5 as all words and 56 as any word. The module defaults to `all` for that reason.
- Restricted documents are published as registration data only — title, number, date and type are public, the content is not. Private people appear as initials or not at all.
- A body's register is large (Haabersti 54,691 rows, Kesklinn 54,921), so a wide term is slow rather than useful. Deep pages take about 2.5 s.

## Verify

A search only succeeded if `ran` is true, which means the response carried the register's own count line: **`Kokku leiti <N> dokumenti`**, or `1 dokument` for a single hit — the singular drops the final *i*, and matching only the plural reports every one-hit search as a search that never ran. Then:

- `scoped: false` means the rows came back registered to other bodies, so the `asutus` filter was dropped and the count is the whole city's. Do not attribute it.
- `totals.reported == totals.register` means the register handed back everything that body has. Either the filter was ignored, or the term is in every title it holds — check a row before stating either.
- `reported: 0` with `ran: true` is a real, empty result for **this** register. Before calling it "no such document": the council's acts are in TEELE, and a Tallinn matter is often registered by the city office that handles it rather than by the district.
- Never name a document without the `url` from its own row.

Known-good acceptance check, run against the live register by `scripts/check-sources.mjs` (issue #82). The counter is the same search with the `asutus` filter misspelt — HTTP 200, rows attached, and the count is every Tallinn body's:

```probe
GET https://dhs.tallinn.ee/atp/?c_tpl=1092&command=search&asutus=12&pealkiri=leping&pealkiri_meetod=1&page=1
expect /Kokku leiti \d{1,4} dokumen[dt]/
expect /<span class="label">Asutus<\/span>Haabersti Linnaosa Valitsus/
# 1,099 of Haabersti's 54,691 documents on 2026-08-02, the first being
# "Lepingu ülesütlemisavaldus". The counter misspells the filter as `asutuz`:
# it answers 46,064 — five digits, every body in the register — with rows from
# Tallinna Kultuuri- ja Spordiamet and others at the top, so it fails both
# assertions. If it ever satisfies them, a dropped scope has become
# indistinguishable from a search that ran.
counter GET https://dhs.tallinn.ee/atp/?c_tpl=1092&command=search&asutuz=12&pealkiri=leping&pealkiri_meetod=1&page=1
```


## Module API
tallinnDocuments(body, term, {limit, match, from, to, direction}) -> {source, page, body, term, ran, scoped, totals, rows, note}