get_permits_in_area
List the building permits and works notifications registered since 2016 within a radius of a point — issued decisions only, matched through the parcel geometry we hold, which is near-complete but not the whole cadastre — to see what is being built nearby. Returns a deduplicated list of cases, newest first and NOT nearest first (one entry per permit or notification; a permit and a notification for the same investment are two cases), plus an aggregate by year and statutory object category that counts ALL matched cases in the circle, not only the listed ones, with the permit/notification split and the building volume where it is recorded. Each case carries its kind, intent and works type, object category with a short label, decision or intake date, deciding authority, investment address with the building number, volume, and its distance from the centre of the circle (to the parcel covered by the case, not to the building; rounded to 10 m). A volume marked suspect — a single-family case far above one house, usually several buildings filed as one case — is shown as recorded and stays in the sums. truncated means more cases matched than the limit: pass the returned cursor back as cursor with the same filters for the next page. The aggregate covers all pages, so do not add it up across them. Filters: dateFrom (default two years back, never earlier than 2016-01-01) and dateTo (inclusive; pass dateFrom too when dateTo is older than two years); categories / excludeCategories: statutory object categories I–XXX, arrays (excludeCategories keeps cases that have no category); intent: shorthand for multi_family (= categories [XIII]), single_family (= [I], which includes semi-detached and terraced houses) or all (default), not combinable with categories; worksType: new_construction (default) or all (adds extensions, demolitions and other works). radiusKm is 0.1–2 (default 2); for a wider area make several calls for neighbouring centre points. Category examples: apartment blocks → categories=[XIII]; buildings without the utility-network noise → excludeCategories=[XXVI] (utility networks, XXVI, can make up most of a list); utility works as a sign that land is being serviced for development → categories=[XXVI]. For "how many / how much" questions pass aggregateOnly=true: you get the aggregate without the list, at the same price. What is closest: the list is ordered by date, so a page can be full of cases far from the point. To see what is next to it, use a smaller radiusKm (for example 0.3) rather than paging through a large circle. How to read it: a case is listed when any of its parcels intersects the circle. Permits are held once a decision has been issued; the outcome of that decision, granted or refused, is not part of the data held here, and notifications are held only where they were accepted without objection. Cases still pending are not held at all. Matching uses the parcel's current identifier and geometry, so cases filed before a parcel split or merge may be invisible, some cases whose parcel number carries a sheet segment may be matched less exactly or be missing, and parcels without geometry are not searched. The answer states how many parcels we hold in the circle: 0 means no data for the area, not that nothing is being built. A short or empty list is never a statement that nothing is being built. Coordinates: for a parcel take them from resolve_parcel (or search_parcels); for a street use list_parcels_in_area(location, street) and take the centre point of a returned row; otherwise they come from the user — never guess them. The data is loaded periodically, not live; the answer gives the date of the last refresh. A query that outruns its time limit answers with an error asking for a smaller radius. Cost: 5 API tokens per call, charged also when the list is empty (a collection is not refunded); each page is a separate call. This feature can be switched off for maintenance; when it is, the call returns a plain "temporarily unavailable" message rather than data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude of the circle's centre (WGS84, Poland). From a resolve_parcel / list_parcels_in_area result or the user; never guessed. | |
| lng | Yes | Longitude of the circle's centre (WGS84, Poland). From a resolve_parcel / list_parcels_in_area result or the user; never guessed. | |
| limit | No | Cases in the list, 1–200 (default 50). The aggregate always counts all matched cases. | |
| cursor | No | Opaque cursor from the previous answer, to get the next page. Pass it back unchanged with the same filters (limit may differ); it is not available with aggregateOnly. | |
| dateTo | No | Window end, YYYY-MM-DD, inclusive; not earlier than dateFrom. When it is older than two years, pass dateFrom as well (the default start is two years back). | |
| intent | No | Shorthand: multi_family = categories [XIII], single_family = categories [I] (includes semi-detached and terraced houses), all = no filter (default). Cannot be combined with categories. | |
| dateFrom | No | Window start, YYYY-MM-DD, on the decision date (intake date for notifications). Default: two years back; earlier than 2016-01-01 is treated as 2016-01-01. | |
| radiusKm | No | Radius in km, 0.1–2 (default 2). For a wider area, call again for neighbouring centre points; for what is closest to the point, use a smaller radius. | |
| worksType | No | new_construction (default) or all (adds extensions, demolitions and other works). | |
| categories | No | Keep only these statutory object categories (Roman numerals I–XXX), e.g. ["XIII"] for apartment blocks or ["XXVI"] for utility networks. Not combinable with intent other than all, and must not overlap with excludeCategories. | |
| aggregateOnly | No | true = return only the aggregate (year × category counts, permit/notification split, volumes) without the case list, for 'how many' questions. Same price; cannot be combined with cursor. | |
| excludeCategories | No | Remove these statutory object categories (cases without a category stay), e.g. ["XXVI"] to drop utility networks. Must not overlap with categories. |