@teryt24/api 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -2
- package/dist/client.d.ts +289 -0
- package/dist/client.js +314 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +10 -0
- package/dist/openapi.gen.d.ts +4296 -0
- package/dist/version.d.ts +10 -0
- package/dist/version.js +10 -0
- package/package.json +37 -4
|
@@ -0,0 +1,4296 @@
|
|
|
1
|
+
/* eslint-disable */
|
|
2
|
+
/**
|
|
3
|
+
* GENERATED by scripts/build-sdk-types.ts from src/api/openapi.ts — the
|
|
4
|
+
* same document GET /openapi.json serves. DO NOT EDIT by hand; run
|
|
5
|
+
* `pnpm sdk:types` to regenerate.
|
|
6
|
+
*/
|
|
7
|
+
export interface paths {
|
|
8
|
+
"/health": {
|
|
9
|
+
parameters: {
|
|
10
|
+
query?: never;
|
|
11
|
+
header?: never;
|
|
12
|
+
path?: never;
|
|
13
|
+
cookie?: never;
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* Deep, advisory health view (dataset freshness, index sizes)
|
|
17
|
+
* @description The historical health route, unchanged: the process and database are healthy, plus the last successful ingest time, per-dataset source dates and ages, and an advisory `stale` flag. Staleness never fails the check — a stale dataset still serves correct, if old, answers. For the two machine questions an orchestrator asks, use `GET /health/live` and `GET /health/ready`.
|
|
18
|
+
*/
|
|
19
|
+
get: {
|
|
20
|
+
parameters: {
|
|
21
|
+
query?: never;
|
|
22
|
+
header?: never;
|
|
23
|
+
path?: never;
|
|
24
|
+
cookie?: never;
|
|
25
|
+
};
|
|
26
|
+
requestBody?: never;
|
|
27
|
+
responses: {
|
|
28
|
+
/** @description Healthy (or DB-less) — see `data` for dataset freshness; `stale` is advisory only. */
|
|
29
|
+
200: {
|
|
30
|
+
headers: {
|
|
31
|
+
[name: string]: unknown;
|
|
32
|
+
};
|
|
33
|
+
content: {
|
|
34
|
+
"application/json": Record<string, never>;
|
|
35
|
+
};
|
|
36
|
+
};
|
|
37
|
+
/** @description Degraded — database unreachable. */
|
|
38
|
+
503: {
|
|
39
|
+
headers: {
|
|
40
|
+
[name: string]: unknown;
|
|
41
|
+
};
|
|
42
|
+
content: {
|
|
43
|
+
"application/json": Record<string, never>;
|
|
44
|
+
};
|
|
45
|
+
};
|
|
46
|
+
};
|
|
47
|
+
};
|
|
48
|
+
put?: never;
|
|
49
|
+
post?: never;
|
|
50
|
+
delete?: never;
|
|
51
|
+
options?: never;
|
|
52
|
+
head?: never;
|
|
53
|
+
patch?: never;
|
|
54
|
+
trace?: never;
|
|
55
|
+
};
|
|
56
|
+
"/health/live": {
|
|
57
|
+
parameters: {
|
|
58
|
+
query?: never;
|
|
59
|
+
header?: never;
|
|
60
|
+
path?: never;
|
|
61
|
+
cookie?: never;
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* Liveness — the process is turning (the restart question)
|
|
65
|
+
* @description Answers 200 for as long as the process can serve a request, and consults NOTHING else — no database, no dataset, no network. This is the endpoint a container healthcheck or a restart policy should point at: a restart fixes a wedged process, and a database outage is not a wedged process.
|
|
66
|
+
*/
|
|
67
|
+
get: {
|
|
68
|
+
parameters: {
|
|
69
|
+
query?: never;
|
|
70
|
+
header?: never;
|
|
71
|
+
path?: never;
|
|
72
|
+
cookie?: never;
|
|
73
|
+
};
|
|
74
|
+
requestBody?: never;
|
|
75
|
+
responses: {
|
|
76
|
+
/** @description The process is alive. */
|
|
77
|
+
200: {
|
|
78
|
+
headers: {
|
|
79
|
+
[name: string]: unknown;
|
|
80
|
+
};
|
|
81
|
+
content: {
|
|
82
|
+
"application/json": {
|
|
83
|
+
/** @enum {string} */
|
|
84
|
+
status?: "ok";
|
|
85
|
+
uptimeSeconds?: number;
|
|
86
|
+
};
|
|
87
|
+
};
|
|
88
|
+
};
|
|
89
|
+
};
|
|
90
|
+
};
|
|
91
|
+
put?: never;
|
|
92
|
+
post?: never;
|
|
93
|
+
delete?: never;
|
|
94
|
+
options?: never;
|
|
95
|
+
head?: never;
|
|
96
|
+
patch?: never;
|
|
97
|
+
trace?: never;
|
|
98
|
+
};
|
|
99
|
+
"/health/ready": {
|
|
100
|
+
parameters: {
|
|
101
|
+
query?: never;
|
|
102
|
+
header?: never;
|
|
103
|
+
path?: never;
|
|
104
|
+
cookie?: never;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* Readiness — this instance can serve traffic (the routing question)
|
|
108
|
+
* @description 200 when the database is reachable AND the city search index is built. 503 with a machine-readable `code` (`database_unavailable` / `index_not_built`) otherwise. It does NOT depend on dataset freshness: a failed refresh leaves the last-known-good catalog serving, which is an alert, not an outage.
|
|
109
|
+
*/
|
|
110
|
+
get: {
|
|
111
|
+
parameters: {
|
|
112
|
+
query?: never;
|
|
113
|
+
header?: never;
|
|
114
|
+
path?: never;
|
|
115
|
+
cookie?: never;
|
|
116
|
+
};
|
|
117
|
+
requestBody?: never;
|
|
118
|
+
responses: {
|
|
119
|
+
/** @description Ready to serve. */
|
|
120
|
+
200: {
|
|
121
|
+
headers: {
|
|
122
|
+
[name: string]: unknown;
|
|
123
|
+
};
|
|
124
|
+
content: {
|
|
125
|
+
"application/json": Record<string, never>;
|
|
126
|
+
};
|
|
127
|
+
};
|
|
128
|
+
/** @description Not ready — `code` says why (database_unavailable | index_not_built). */
|
|
129
|
+
503: {
|
|
130
|
+
headers: {
|
|
131
|
+
[name: string]: unknown;
|
|
132
|
+
};
|
|
133
|
+
content: {
|
|
134
|
+
"application/json": Record<string, never>;
|
|
135
|
+
};
|
|
136
|
+
};
|
|
137
|
+
};
|
|
138
|
+
};
|
|
139
|
+
put?: never;
|
|
140
|
+
post?: never;
|
|
141
|
+
delete?: never;
|
|
142
|
+
options?: never;
|
|
143
|
+
head?: never;
|
|
144
|
+
patch?: never;
|
|
145
|
+
trace?: never;
|
|
146
|
+
};
|
|
147
|
+
"/v1/localities": {
|
|
148
|
+
parameters: {
|
|
149
|
+
query?: never;
|
|
150
|
+
header?: never;
|
|
151
|
+
path?: never;
|
|
152
|
+
cookie?: never;
|
|
153
|
+
};
|
|
154
|
+
/**
|
|
155
|
+
* Full locality autocomplete (all self-standing SIMC entries, ≈54k)
|
|
156
|
+
* @description Villages, kolonie, osady… No dedupe — same-named localities are all returned; disambiguate via province/county. Geographic mode (lat+lon): nearest-first with distanceKm; needs coordinates (GeoNames enrichment) — results are empty when the dataset is absent. Browse mode (province/county/municipality without q): all matching localities in name order. The response carries `meta.total` — the selection's match count before offset/limit (alias hits not counted).
|
|
157
|
+
*/
|
|
158
|
+
get: {
|
|
159
|
+
parameters: {
|
|
160
|
+
query?: {
|
|
161
|
+
/** @description Search query; diacritics- and punctuation-insensitive. Optional in geographic mode (lat+lon given) or when a filter (province/county/municipality/population) is given, required otherwise. */
|
|
162
|
+
q?: string;
|
|
163
|
+
/** @description Maximum results per page (1–50). */
|
|
164
|
+
limit?: number;
|
|
165
|
+
/** @description autocomplete = prefix-first, resolve = exact only, hybrid = combined. Ignored in geographic mode. */
|
|
166
|
+
mode?: "autocomplete" | "resolve" | "hybrid";
|
|
167
|
+
/** @description Optional rodzaj-miejscowości filter: one 2-digit RM code (01 = wieś, 96 = miasto) or a comma-separated list matching any of them (e.g. '96,95,98' — the urban units: miasto + dzielnica + delegatura). Warszawa's SIMC records carry RM 95 (dzielnica m.st. Warszawy), not 96 — use this list form or kind=urban for the urban units. */
|
|
168
|
+
rm?: string;
|
|
169
|
+
/** @description Semantic rodzaj preset: kind=urban selects the urban units (RM 96 miasto + 95 dzielnica m.st. Warszawy + 98 delegatura) — the reliable 'cities' filter (Warszawa's SIMC records carry RM 95, so rm=96 alone misses the capital). Mutually exclusive with rm. */
|
|
170
|
+
kind?: "urban";
|
|
171
|
+
/** @description Optional 2-digit TERC voivodeship code filter (e.g. '14'), as served by /v1/regions. Makes q optional (browse mode: all matching localities in name order). */
|
|
172
|
+
province?: string;
|
|
173
|
+
/** @description Optional 4-digit TERC code filter (WOJ+POW, e.g. '1465'). Makes q optional (browse mode). */
|
|
174
|
+
county?: string;
|
|
175
|
+
/** @description Optional 6-digit TERC code filter (WOJ+POW+GMI, e.g. '146503'). Makes q optional (browse mode). */
|
|
176
|
+
municipality?: string;
|
|
177
|
+
/** @description Optional inhabitants lower bound (GeoNames data; unknown population is excluded). Makes q optional (browse mode). */
|
|
178
|
+
minPopulation?: number;
|
|
179
|
+
/** @description Optional inhabitants upper bound (GeoNames data; unknown population is excluded). Makes q optional (browse mode). */
|
|
180
|
+
maxPopulation?: number;
|
|
181
|
+
/** @description Skip the first N results (0-based, max 10000) to page past the limit. */
|
|
182
|
+
offset?: number;
|
|
183
|
+
/** @description Opt-in exonym fallback (aliases=true): when nothing matched by name, consult the GeoNames-derived alias table ('Danzig' finds Gdańsk). */
|
|
184
|
+
aliases?: "true" | "false";
|
|
185
|
+
/** @description WGS84 latitude (-90..90). Together with lon triggers geographic mode: localities within radiusKm, ordered nearest-first (each with distanceKm). A blank value ('?lat=') is treated as absent — it does not trigger the mode. */
|
|
186
|
+
lat?: number;
|
|
187
|
+
/** @description WGS84 longitude (-180..180). Must be given together with lat. */
|
|
188
|
+
lon?: number;
|
|
189
|
+
/** @description Geographic-mode radius in kilometres (default 10, max 100). */
|
|
190
|
+
radiusKm?: number;
|
|
191
|
+
/** @description 'geojson' answers an RFC 7946 FeatureCollection (points in [lon,lat] order, DTO fields as properties, rows without coordinates carry geometry:null) instead of the JSON envelope. */
|
|
192
|
+
format?: "json" | "geojson";
|
|
193
|
+
};
|
|
194
|
+
header?: never;
|
|
195
|
+
path?: never;
|
|
196
|
+
cookie?: never;
|
|
197
|
+
};
|
|
198
|
+
requestBody?: never;
|
|
199
|
+
responses: {
|
|
200
|
+
/** @description Successful response. */
|
|
201
|
+
200: {
|
|
202
|
+
headers: {
|
|
203
|
+
[name: string]: unknown;
|
|
204
|
+
};
|
|
205
|
+
content: {
|
|
206
|
+
"application/json": {
|
|
207
|
+
localities: {
|
|
208
|
+
name: string;
|
|
209
|
+
province: string | null;
|
|
210
|
+
county: string | null;
|
|
211
|
+
municipality: string | null;
|
|
212
|
+
id: string | null;
|
|
213
|
+
type: string | null;
|
|
214
|
+
typeLabel: string | null;
|
|
215
|
+
normalized: string;
|
|
216
|
+
lat: number | null;
|
|
217
|
+
lon: number | null;
|
|
218
|
+
coordSource: string | null;
|
|
219
|
+
population: number | null;
|
|
220
|
+
provinceCode: string | null;
|
|
221
|
+
countyCode: string | null;
|
|
222
|
+
municipalityCode: string | null;
|
|
223
|
+
distanceKm?: number;
|
|
224
|
+
}[];
|
|
225
|
+
meta?: {
|
|
226
|
+
total: number;
|
|
227
|
+
offset: number;
|
|
228
|
+
limit: number;
|
|
229
|
+
};
|
|
230
|
+
};
|
|
231
|
+
};
|
|
232
|
+
};
|
|
233
|
+
/** @description Invalid query parameters. */
|
|
234
|
+
400: {
|
|
235
|
+
headers: {
|
|
236
|
+
[name: string]: unknown;
|
|
237
|
+
};
|
|
238
|
+
content: {
|
|
239
|
+
"application/json": {
|
|
240
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
241
|
+
error: string;
|
|
242
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
243
|
+
message: string;
|
|
244
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
245
|
+
code: string;
|
|
246
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
247
|
+
details?: {
|
|
248
|
+
path?: string;
|
|
249
|
+
message?: string;
|
|
250
|
+
}[];
|
|
251
|
+
};
|
|
252
|
+
};
|
|
253
|
+
};
|
|
254
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
255
|
+
429: {
|
|
256
|
+
headers: {
|
|
257
|
+
[name: string]: unknown;
|
|
258
|
+
};
|
|
259
|
+
content: {
|
|
260
|
+
"application/json": {
|
|
261
|
+
statusCode: number;
|
|
262
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
263
|
+
error: string;
|
|
264
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
265
|
+
message: string;
|
|
266
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
267
|
+
code: string;
|
|
268
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
269
|
+
details?: {
|
|
270
|
+
path?: string;
|
|
271
|
+
message?: string;
|
|
272
|
+
}[];
|
|
273
|
+
};
|
|
274
|
+
};
|
|
275
|
+
};
|
|
276
|
+
/** @description Service is warming up. */
|
|
277
|
+
503: {
|
|
278
|
+
headers: {
|
|
279
|
+
[name: string]: unknown;
|
|
280
|
+
};
|
|
281
|
+
content: {
|
|
282
|
+
"application/json": {
|
|
283
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
284
|
+
error: string;
|
|
285
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
286
|
+
message: string;
|
|
287
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
288
|
+
code: string;
|
|
289
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
290
|
+
details?: {
|
|
291
|
+
path?: string;
|
|
292
|
+
message?: string;
|
|
293
|
+
}[];
|
|
294
|
+
};
|
|
295
|
+
};
|
|
296
|
+
};
|
|
297
|
+
};
|
|
298
|
+
};
|
|
299
|
+
put?: never;
|
|
300
|
+
post?: never;
|
|
301
|
+
delete?: never;
|
|
302
|
+
options?: never;
|
|
303
|
+
head?: never;
|
|
304
|
+
patch?: never;
|
|
305
|
+
trace?: never;
|
|
306
|
+
};
|
|
307
|
+
"/v1/localities/{sym}": {
|
|
308
|
+
parameters: {
|
|
309
|
+
query?: never;
|
|
310
|
+
header?: never;
|
|
311
|
+
path?: never;
|
|
312
|
+
cookie?: never;
|
|
313
|
+
};
|
|
314
|
+
/**
|
|
315
|
+
* Locality detail by SYM (identity, hierarchy, postal codes, street count)
|
|
316
|
+
* @description One locality's full record: identity and administrative hierarchy from the search index, plus the postal codes serving it (matched PRG-first — the codes whose official GUGiK locality set contains this SYM, scope 'prg' — then gmina → powiat → name; a hit GeoNames never paired is synthesized from the locality registry; postalCodesTruncated: true when the row cap was hit) and the number of registered streets. postalCodes/streetCount are null when the underlying dataset is not available on this instance. Cities resolve here too (a city is an RM 96 locality).
|
|
317
|
+
*/
|
|
318
|
+
get: {
|
|
319
|
+
parameters: {
|
|
320
|
+
query?: never;
|
|
321
|
+
header?: never;
|
|
322
|
+
path: {
|
|
323
|
+
/** @description Locality SYM (7 digits, as returned by /v1/localities). */
|
|
324
|
+
sym: string;
|
|
325
|
+
};
|
|
326
|
+
cookie?: never;
|
|
327
|
+
};
|
|
328
|
+
requestBody?: never;
|
|
329
|
+
responses: {
|
|
330
|
+
/** @description Successful response. */
|
|
331
|
+
200: {
|
|
332
|
+
headers: {
|
|
333
|
+
[name: string]: unknown;
|
|
334
|
+
};
|
|
335
|
+
content: {
|
|
336
|
+
"application/json": {
|
|
337
|
+
locality: {
|
|
338
|
+
name: string;
|
|
339
|
+
province: string | null;
|
|
340
|
+
county: string | null;
|
|
341
|
+
municipality: string | null;
|
|
342
|
+
id: string | null;
|
|
343
|
+
type: string | null;
|
|
344
|
+
typeLabel: string | null;
|
|
345
|
+
normalized: string;
|
|
346
|
+
lat: number | null;
|
|
347
|
+
lon: number | null;
|
|
348
|
+
coordSource: string | null;
|
|
349
|
+
population: number | null;
|
|
350
|
+
populationSource: string | null;
|
|
351
|
+
provinceCode: string | null;
|
|
352
|
+
countyCode: string | null;
|
|
353
|
+
municipalityCode: string | null;
|
|
354
|
+
};
|
|
355
|
+
postalCodes: {
|
|
356
|
+
code: string;
|
|
357
|
+
city: string;
|
|
358
|
+
lat: number | null;
|
|
359
|
+
lon: number | null;
|
|
360
|
+
/** @enum {string} */
|
|
361
|
+
scope: "gmina" | "powiat" | "name";
|
|
362
|
+
}[] | null;
|
|
363
|
+
postalCodesTruncated?: boolean;
|
|
364
|
+
streetCount: number | null;
|
|
365
|
+
gminaStats: {
|
|
366
|
+
gmi: string;
|
|
367
|
+
population: number | null;
|
|
368
|
+
populationYear: string | null;
|
|
369
|
+
series: {
|
|
370
|
+
year: string;
|
|
371
|
+
val: number;
|
|
372
|
+
}[] | null;
|
|
373
|
+
areaValue: number | null;
|
|
374
|
+
areaUnit: string | null;
|
|
375
|
+
regonCount: number | null;
|
|
376
|
+
regonYear: string | null;
|
|
377
|
+
budgetIncomePerCapita: number | null;
|
|
378
|
+
budgetExpensePerCapita: number | null;
|
|
379
|
+
budgetYear: string | null;
|
|
380
|
+
} | null;
|
|
381
|
+
census: {
|
|
382
|
+
resident: number | null;
|
|
383
|
+
residentMale: number | null;
|
|
384
|
+
residentFemale: number | null;
|
|
385
|
+
preproductive: number | null;
|
|
386
|
+
workingAge: number | null;
|
|
387
|
+
workingAgeMobile: number | null;
|
|
388
|
+
workingAgeImmobile: number | null;
|
|
389
|
+
postproductive: number | null;
|
|
390
|
+
} | null;
|
|
391
|
+
};
|
|
392
|
+
};
|
|
393
|
+
};
|
|
394
|
+
/** @description Invalid query parameters. */
|
|
395
|
+
400: {
|
|
396
|
+
headers: {
|
|
397
|
+
[name: string]: unknown;
|
|
398
|
+
};
|
|
399
|
+
content: {
|
|
400
|
+
"application/json": {
|
|
401
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
402
|
+
error: string;
|
|
403
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
404
|
+
message: string;
|
|
405
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
406
|
+
code: string;
|
|
407
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
408
|
+
details?: {
|
|
409
|
+
path?: string;
|
|
410
|
+
message?: string;
|
|
411
|
+
}[];
|
|
412
|
+
};
|
|
413
|
+
};
|
|
414
|
+
};
|
|
415
|
+
/** @description Unknown locality SYM. */
|
|
416
|
+
404: {
|
|
417
|
+
headers: {
|
|
418
|
+
[name: string]: unknown;
|
|
419
|
+
};
|
|
420
|
+
content: {
|
|
421
|
+
"application/json": {
|
|
422
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
423
|
+
error: string;
|
|
424
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
425
|
+
message: string;
|
|
426
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
427
|
+
code: string;
|
|
428
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
429
|
+
details?: {
|
|
430
|
+
path?: string;
|
|
431
|
+
message?: string;
|
|
432
|
+
}[];
|
|
433
|
+
};
|
|
434
|
+
};
|
|
435
|
+
};
|
|
436
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
437
|
+
429: {
|
|
438
|
+
headers: {
|
|
439
|
+
[name: string]: unknown;
|
|
440
|
+
};
|
|
441
|
+
content: {
|
|
442
|
+
"application/json": {
|
|
443
|
+
statusCode: number;
|
|
444
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
445
|
+
error: string;
|
|
446
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
447
|
+
message: string;
|
|
448
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
449
|
+
code: string;
|
|
450
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
451
|
+
details?: {
|
|
452
|
+
path?: string;
|
|
453
|
+
message?: string;
|
|
454
|
+
}[];
|
|
455
|
+
};
|
|
456
|
+
};
|
|
457
|
+
};
|
|
458
|
+
/** @description Service is warming up. */
|
|
459
|
+
503: {
|
|
460
|
+
headers: {
|
|
461
|
+
[name: string]: unknown;
|
|
462
|
+
};
|
|
463
|
+
content: {
|
|
464
|
+
"application/json": {
|
|
465
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
466
|
+
error: string;
|
|
467
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
468
|
+
message: string;
|
|
469
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
470
|
+
code: string;
|
|
471
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
472
|
+
details?: {
|
|
473
|
+
path?: string;
|
|
474
|
+
message?: string;
|
|
475
|
+
}[];
|
|
476
|
+
};
|
|
477
|
+
};
|
|
478
|
+
};
|
|
479
|
+
};
|
|
480
|
+
};
|
|
481
|
+
put?: never;
|
|
482
|
+
post?: never;
|
|
483
|
+
delete?: never;
|
|
484
|
+
options?: never;
|
|
485
|
+
head?: never;
|
|
486
|
+
patch?: never;
|
|
487
|
+
trace?: never;
|
|
488
|
+
};
|
|
489
|
+
"/v1/regions": {
|
|
490
|
+
parameters: {
|
|
491
|
+
query?: never;
|
|
492
|
+
header?: never;
|
|
493
|
+
path?: never;
|
|
494
|
+
cookie?: never;
|
|
495
|
+
};
|
|
496
|
+
/** Voivodeships (TERC) */
|
|
497
|
+
get: {
|
|
498
|
+
parameters: {
|
|
499
|
+
query?: never;
|
|
500
|
+
header?: never;
|
|
501
|
+
path?: never;
|
|
502
|
+
cookie?: never;
|
|
503
|
+
};
|
|
504
|
+
requestBody?: never;
|
|
505
|
+
responses: {
|
|
506
|
+
/** @description Successful response. */
|
|
507
|
+
200: {
|
|
508
|
+
headers: {
|
|
509
|
+
[name: string]: unknown;
|
|
510
|
+
};
|
|
511
|
+
content: {
|
|
512
|
+
"application/json": {
|
|
513
|
+
regions: {
|
|
514
|
+
code: string;
|
|
515
|
+
name: string;
|
|
516
|
+
kind: string | null;
|
|
517
|
+
nuts: string[];
|
|
518
|
+
}[];
|
|
519
|
+
};
|
|
520
|
+
};
|
|
521
|
+
};
|
|
522
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
523
|
+
429: {
|
|
524
|
+
headers: {
|
|
525
|
+
[name: string]: unknown;
|
|
526
|
+
};
|
|
527
|
+
content: {
|
|
528
|
+
"application/json": {
|
|
529
|
+
statusCode: number;
|
|
530
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
531
|
+
error: string;
|
|
532
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
533
|
+
message: string;
|
|
534
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
535
|
+
code: string;
|
|
536
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
537
|
+
details?: {
|
|
538
|
+
path?: string;
|
|
539
|
+
message?: string;
|
|
540
|
+
}[];
|
|
541
|
+
};
|
|
542
|
+
};
|
|
543
|
+
};
|
|
544
|
+
/** @description Service is warming up. */
|
|
545
|
+
503: {
|
|
546
|
+
headers: {
|
|
547
|
+
[name: string]: unknown;
|
|
548
|
+
};
|
|
549
|
+
content: {
|
|
550
|
+
"application/json": {
|
|
551
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
552
|
+
error: string;
|
|
553
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
554
|
+
message: string;
|
|
555
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
556
|
+
code: string;
|
|
557
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
558
|
+
details?: {
|
|
559
|
+
path?: string;
|
|
560
|
+
message?: string;
|
|
561
|
+
}[];
|
|
562
|
+
};
|
|
563
|
+
};
|
|
564
|
+
};
|
|
565
|
+
};
|
|
566
|
+
};
|
|
567
|
+
put?: never;
|
|
568
|
+
post?: never;
|
|
569
|
+
delete?: never;
|
|
570
|
+
options?: never;
|
|
571
|
+
head?: never;
|
|
572
|
+
patch?: never;
|
|
573
|
+
trace?: never;
|
|
574
|
+
};
|
|
575
|
+
"/v1/area-codes/{terc}": {
|
|
576
|
+
parameters: {
|
|
577
|
+
query?: never;
|
|
578
|
+
header?: never;
|
|
579
|
+
path?: never;
|
|
580
|
+
cookie?: never;
|
|
581
|
+
};
|
|
582
|
+
/**
|
|
583
|
+
* Telephone area code of one gmina (UKE numbering zones)
|
|
584
|
+
* @description The fixed-line telephone area code (`WSN`/`AB`) prefixing numbers in a gmina, from the vendored UKE `wykaz gmin w strefach numeracyjnych` (the National Numbering Plan defines zones by gmina, not by powiat). A consumer holding a bare 7-digit local number whose area code the source dropped completes it as `wsn` + the local number. 404 when this gmina has no listing; 503 when the dataset is not loaded.
|
|
585
|
+
*/
|
|
586
|
+
get: {
|
|
587
|
+
parameters: {
|
|
588
|
+
query?: never;
|
|
589
|
+
header?: never;
|
|
590
|
+
path: {
|
|
591
|
+
/** @description 6-digit gmina TERC code (WOJ+POW+GMI), e.g. '302116'. */
|
|
592
|
+
terc: string;
|
|
593
|
+
};
|
|
594
|
+
cookie?: never;
|
|
595
|
+
};
|
|
596
|
+
requestBody?: never;
|
|
597
|
+
responses: {
|
|
598
|
+
/** @description Successful response. */
|
|
599
|
+
200: {
|
|
600
|
+
headers: {
|
|
601
|
+
[name: string]: unknown;
|
|
602
|
+
};
|
|
603
|
+
content: {
|
|
604
|
+
"application/json": {
|
|
605
|
+
terc: string;
|
|
606
|
+
wsn: string;
|
|
607
|
+
sn: string;
|
|
608
|
+
};
|
|
609
|
+
};
|
|
610
|
+
};
|
|
611
|
+
/** @description Invalid query parameters. */
|
|
612
|
+
400: {
|
|
613
|
+
headers: {
|
|
614
|
+
[name: string]: unknown;
|
|
615
|
+
};
|
|
616
|
+
content: {
|
|
617
|
+
"application/json": {
|
|
618
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
619
|
+
error: string;
|
|
620
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
621
|
+
message: string;
|
|
622
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
623
|
+
code: string;
|
|
624
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
625
|
+
details?: {
|
|
626
|
+
path?: string;
|
|
627
|
+
message?: string;
|
|
628
|
+
}[];
|
|
629
|
+
};
|
|
630
|
+
};
|
|
631
|
+
};
|
|
632
|
+
/** @description No area code for this gmina. */
|
|
633
|
+
404: {
|
|
634
|
+
headers: {
|
|
635
|
+
[name: string]: unknown;
|
|
636
|
+
};
|
|
637
|
+
content: {
|
|
638
|
+
"application/json": {
|
|
639
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
640
|
+
error: string;
|
|
641
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
642
|
+
message: string;
|
|
643
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
644
|
+
code: string;
|
|
645
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
646
|
+
details?: {
|
|
647
|
+
path?: string;
|
|
648
|
+
message?: string;
|
|
649
|
+
}[];
|
|
650
|
+
};
|
|
651
|
+
};
|
|
652
|
+
};
|
|
653
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
654
|
+
429: {
|
|
655
|
+
headers: {
|
|
656
|
+
[name: string]: unknown;
|
|
657
|
+
};
|
|
658
|
+
content: {
|
|
659
|
+
"application/json": {
|
|
660
|
+
statusCode: number;
|
|
661
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
662
|
+
error: string;
|
|
663
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
664
|
+
message: string;
|
|
665
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
666
|
+
code: string;
|
|
667
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
668
|
+
details?: {
|
|
669
|
+
path?: string;
|
|
670
|
+
message?: string;
|
|
671
|
+
}[];
|
|
672
|
+
};
|
|
673
|
+
};
|
|
674
|
+
};
|
|
675
|
+
/** @description Service is warming up, or the area-code dataset is unavailable. */
|
|
676
|
+
503: {
|
|
677
|
+
headers: {
|
|
678
|
+
[name: string]: unknown;
|
|
679
|
+
};
|
|
680
|
+
content: {
|
|
681
|
+
"application/json": {
|
|
682
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
683
|
+
error: string;
|
|
684
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
685
|
+
message: string;
|
|
686
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
687
|
+
code: string;
|
|
688
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
689
|
+
details?: {
|
|
690
|
+
path?: string;
|
|
691
|
+
message?: string;
|
|
692
|
+
}[];
|
|
693
|
+
};
|
|
694
|
+
};
|
|
695
|
+
};
|
|
696
|
+
};
|
|
697
|
+
};
|
|
698
|
+
put?: never;
|
|
699
|
+
post?: never;
|
|
700
|
+
delete?: never;
|
|
701
|
+
options?: never;
|
|
702
|
+
head?: never;
|
|
703
|
+
patch?: never;
|
|
704
|
+
trace?: never;
|
|
705
|
+
};
|
|
706
|
+
"/v1/regions/{code}/counties": {
|
|
707
|
+
parameters: {
|
|
708
|
+
query?: never;
|
|
709
|
+
header?: never;
|
|
710
|
+
path?: never;
|
|
711
|
+
cookie?: never;
|
|
712
|
+
};
|
|
713
|
+
/** Counties of one voivodeship (incl. miasta na prawach powiatu) */
|
|
714
|
+
get: {
|
|
715
|
+
parameters: {
|
|
716
|
+
query?: never;
|
|
717
|
+
header?: never;
|
|
718
|
+
path: {
|
|
719
|
+
/** @description TERC code: 2 digits for a voivodeship (e.g. '14'). */
|
|
720
|
+
code: string;
|
|
721
|
+
};
|
|
722
|
+
cookie?: never;
|
|
723
|
+
};
|
|
724
|
+
requestBody?: never;
|
|
725
|
+
responses: {
|
|
726
|
+
/** @description Successful response. */
|
|
727
|
+
200: {
|
|
728
|
+
headers: {
|
|
729
|
+
[name: string]: unknown;
|
|
730
|
+
};
|
|
731
|
+
content: {
|
|
732
|
+
"application/json": {
|
|
733
|
+
counties: {
|
|
734
|
+
code: string;
|
|
735
|
+
name: string;
|
|
736
|
+
kind: string | null;
|
|
737
|
+
nuts: string[];
|
|
738
|
+
}[];
|
|
739
|
+
};
|
|
740
|
+
};
|
|
741
|
+
};
|
|
742
|
+
/** @description Invalid query parameters. */
|
|
743
|
+
400: {
|
|
744
|
+
headers: {
|
|
745
|
+
[name: string]: unknown;
|
|
746
|
+
};
|
|
747
|
+
content: {
|
|
748
|
+
"application/json": {
|
|
749
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
750
|
+
error: string;
|
|
751
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
752
|
+
message: string;
|
|
753
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
754
|
+
code: string;
|
|
755
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
756
|
+
details?: {
|
|
757
|
+
path?: string;
|
|
758
|
+
message?: string;
|
|
759
|
+
}[];
|
|
760
|
+
};
|
|
761
|
+
};
|
|
762
|
+
};
|
|
763
|
+
/** @description Unknown voivodeship code. */
|
|
764
|
+
404: {
|
|
765
|
+
headers: {
|
|
766
|
+
[name: string]: unknown;
|
|
767
|
+
};
|
|
768
|
+
content: {
|
|
769
|
+
"application/json": {
|
|
770
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
771
|
+
error: string;
|
|
772
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
773
|
+
message: string;
|
|
774
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
775
|
+
code: string;
|
|
776
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
777
|
+
details?: {
|
|
778
|
+
path?: string;
|
|
779
|
+
message?: string;
|
|
780
|
+
}[];
|
|
781
|
+
};
|
|
782
|
+
};
|
|
783
|
+
};
|
|
784
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
785
|
+
429: {
|
|
786
|
+
headers: {
|
|
787
|
+
[name: string]: unknown;
|
|
788
|
+
};
|
|
789
|
+
content: {
|
|
790
|
+
"application/json": {
|
|
791
|
+
statusCode: number;
|
|
792
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
793
|
+
error: string;
|
|
794
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
795
|
+
message: string;
|
|
796
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
797
|
+
code: string;
|
|
798
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
799
|
+
details?: {
|
|
800
|
+
path?: string;
|
|
801
|
+
message?: string;
|
|
802
|
+
}[];
|
|
803
|
+
};
|
|
804
|
+
};
|
|
805
|
+
};
|
|
806
|
+
/** @description Service is warming up. */
|
|
807
|
+
503: {
|
|
808
|
+
headers: {
|
|
809
|
+
[name: string]: unknown;
|
|
810
|
+
};
|
|
811
|
+
content: {
|
|
812
|
+
"application/json": {
|
|
813
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
814
|
+
error: string;
|
|
815
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
816
|
+
message: string;
|
|
817
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
818
|
+
code: string;
|
|
819
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
820
|
+
details?: {
|
|
821
|
+
path?: string;
|
|
822
|
+
message?: string;
|
|
823
|
+
}[];
|
|
824
|
+
};
|
|
825
|
+
};
|
|
826
|
+
};
|
|
827
|
+
};
|
|
828
|
+
};
|
|
829
|
+
put?: never;
|
|
830
|
+
post?: never;
|
|
831
|
+
delete?: never;
|
|
832
|
+
options?: never;
|
|
833
|
+
head?: never;
|
|
834
|
+
patch?: never;
|
|
835
|
+
trace?: never;
|
|
836
|
+
};
|
|
837
|
+
"/v1/regions/{code}/municipalities": {
|
|
838
|
+
parameters: {
|
|
839
|
+
query?: never;
|
|
840
|
+
header?: never;
|
|
841
|
+
path?: never;
|
|
842
|
+
cookie?: never;
|
|
843
|
+
};
|
|
844
|
+
/** Municipalities (gminy) of a voivodeship, optionally narrowed to one county */
|
|
845
|
+
get: {
|
|
846
|
+
parameters: {
|
|
847
|
+
query?: {
|
|
848
|
+
/** @description Optional 2-digit TERC powiat code to narrow to one county. */
|
|
849
|
+
county?: string;
|
|
850
|
+
};
|
|
851
|
+
header?: never;
|
|
852
|
+
path: {
|
|
853
|
+
/** @description TERC code: 2 digits for a voivodeship (e.g. '14'). */
|
|
854
|
+
code: string;
|
|
855
|
+
};
|
|
856
|
+
cookie?: never;
|
|
857
|
+
};
|
|
858
|
+
requestBody?: never;
|
|
859
|
+
responses: {
|
|
860
|
+
/** @description Successful response. */
|
|
861
|
+
200: {
|
|
862
|
+
headers: {
|
|
863
|
+
[name: string]: unknown;
|
|
864
|
+
};
|
|
865
|
+
content: {
|
|
866
|
+
"application/json": {
|
|
867
|
+
municipalities: {
|
|
868
|
+
code: string;
|
|
869
|
+
name: string;
|
|
870
|
+
kind: string | null;
|
|
871
|
+
nuts: string[];
|
|
872
|
+
}[];
|
|
873
|
+
};
|
|
874
|
+
};
|
|
875
|
+
};
|
|
876
|
+
/** @description Invalid query parameters. */
|
|
877
|
+
400: {
|
|
878
|
+
headers: {
|
|
879
|
+
[name: string]: unknown;
|
|
880
|
+
};
|
|
881
|
+
content: {
|
|
882
|
+
"application/json": {
|
|
883
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
884
|
+
error: string;
|
|
885
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
886
|
+
message: string;
|
|
887
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
888
|
+
code: string;
|
|
889
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
890
|
+
details?: {
|
|
891
|
+
path?: string;
|
|
892
|
+
message?: string;
|
|
893
|
+
}[];
|
|
894
|
+
};
|
|
895
|
+
};
|
|
896
|
+
};
|
|
897
|
+
/** @description Unknown voivodeship or county code. */
|
|
898
|
+
404: {
|
|
899
|
+
headers: {
|
|
900
|
+
[name: string]: unknown;
|
|
901
|
+
};
|
|
902
|
+
content: {
|
|
903
|
+
"application/json": {
|
|
904
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
905
|
+
error: string;
|
|
906
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
907
|
+
message: string;
|
|
908
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
909
|
+
code: string;
|
|
910
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
911
|
+
details?: {
|
|
912
|
+
path?: string;
|
|
913
|
+
message?: string;
|
|
914
|
+
}[];
|
|
915
|
+
};
|
|
916
|
+
};
|
|
917
|
+
};
|
|
918
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
919
|
+
429: {
|
|
920
|
+
headers: {
|
|
921
|
+
[name: string]: unknown;
|
|
922
|
+
};
|
|
923
|
+
content: {
|
|
924
|
+
"application/json": {
|
|
925
|
+
statusCode: number;
|
|
926
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
927
|
+
error: string;
|
|
928
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
929
|
+
message: string;
|
|
930
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
931
|
+
code: string;
|
|
932
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
933
|
+
details?: {
|
|
934
|
+
path?: string;
|
|
935
|
+
message?: string;
|
|
936
|
+
}[];
|
|
937
|
+
};
|
|
938
|
+
};
|
|
939
|
+
};
|
|
940
|
+
/** @description Service is warming up. */
|
|
941
|
+
503: {
|
|
942
|
+
headers: {
|
|
943
|
+
[name: string]: unknown;
|
|
944
|
+
};
|
|
945
|
+
content: {
|
|
946
|
+
"application/json": {
|
|
947
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
948
|
+
error: string;
|
|
949
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
950
|
+
message: string;
|
|
951
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
952
|
+
code: string;
|
|
953
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
954
|
+
details?: {
|
|
955
|
+
path?: string;
|
|
956
|
+
message?: string;
|
|
957
|
+
}[];
|
|
958
|
+
};
|
|
959
|
+
};
|
|
960
|
+
};
|
|
961
|
+
};
|
|
962
|
+
};
|
|
963
|
+
put?: never;
|
|
964
|
+
post?: never;
|
|
965
|
+
delete?: never;
|
|
966
|
+
options?: never;
|
|
967
|
+
head?: never;
|
|
968
|
+
patch?: never;
|
|
969
|
+
trace?: never;
|
|
970
|
+
};
|
|
971
|
+
"/v1/regions/{code}/demography": {
|
|
972
|
+
parameters: {
|
|
973
|
+
query?: never;
|
|
974
|
+
header?: never;
|
|
975
|
+
path?: never;
|
|
976
|
+
cookie?: never;
|
|
977
|
+
};
|
|
978
|
+
/**
|
|
979
|
+
* Demographic decomposition of one voivodeship (natural balance, net migration, reconciled against the population series)
|
|
980
|
+
* @description The natural balance (births − deaths) and the net internal and net foreign migration of a voivodeship, from GUS BDL and summed over its counties (the BDL publishes no demography at the voivodeship level). `residual` is the change of the counties the row covers minus what those two forces explain — it is not zero, because GUS rebuilds the series between editions, and it is returned as it stands. A year is measured over the counties that published every component, and `powiats`/`powiatsTotal` say how many that was; a year in which no county did is listed in `incomplete`.
|
|
981
|
+
*/
|
|
982
|
+
get: {
|
|
983
|
+
parameters: {
|
|
984
|
+
query?: never;
|
|
985
|
+
header?: never;
|
|
986
|
+
path: {
|
|
987
|
+
/** @description TERC code: 2 digits for a voivodeship (e.g. '14'). */
|
|
988
|
+
code: string;
|
|
989
|
+
};
|
|
990
|
+
cookie?: never;
|
|
991
|
+
};
|
|
992
|
+
requestBody?: never;
|
|
993
|
+
responses: {
|
|
994
|
+
/** @description Successful response. */
|
|
995
|
+
200: {
|
|
996
|
+
headers: {
|
|
997
|
+
[name: string]: unknown;
|
|
998
|
+
};
|
|
999
|
+
content: {
|
|
1000
|
+
"application/json": {
|
|
1001
|
+
code: string;
|
|
1002
|
+
years: {
|
|
1003
|
+
year: string;
|
|
1004
|
+
births: number;
|
|
1005
|
+
deaths: number;
|
|
1006
|
+
naturalBalance: number;
|
|
1007
|
+
migrationInternal: number;
|
|
1008
|
+
migrationForeign: number;
|
|
1009
|
+
migration: number;
|
|
1010
|
+
populationDelta: number | null;
|
|
1011
|
+
explained: number | null;
|
|
1012
|
+
residual: number | null;
|
|
1013
|
+
powiats: number | null;
|
|
1014
|
+
powiatsTotal: number | null;
|
|
1015
|
+
}[];
|
|
1016
|
+
incomplete: {
|
|
1017
|
+
year: string;
|
|
1018
|
+
have: number;
|
|
1019
|
+
of: number;
|
|
1020
|
+
}[];
|
|
1021
|
+
varIds: {
|
|
1022
|
+
[key: string]: number | null;
|
|
1023
|
+
};
|
|
1024
|
+
};
|
|
1025
|
+
};
|
|
1026
|
+
};
|
|
1027
|
+
/** @description Invalid query parameters. */
|
|
1028
|
+
400: {
|
|
1029
|
+
headers: {
|
|
1030
|
+
[name: string]: unknown;
|
|
1031
|
+
};
|
|
1032
|
+
content: {
|
|
1033
|
+
"application/json": {
|
|
1034
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1035
|
+
error: string;
|
|
1036
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1037
|
+
message: string;
|
|
1038
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1039
|
+
code: string;
|
|
1040
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1041
|
+
details?: {
|
|
1042
|
+
path?: string;
|
|
1043
|
+
message?: string;
|
|
1044
|
+
}[];
|
|
1045
|
+
};
|
|
1046
|
+
};
|
|
1047
|
+
};
|
|
1048
|
+
/** @description Unknown voivodeship code, or no decomposition fetched for it. */
|
|
1049
|
+
404: {
|
|
1050
|
+
headers: {
|
|
1051
|
+
[name: string]: unknown;
|
|
1052
|
+
};
|
|
1053
|
+
content: {
|
|
1054
|
+
"application/json": {
|
|
1055
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1056
|
+
error: string;
|
|
1057
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1058
|
+
message: string;
|
|
1059
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1060
|
+
code: string;
|
|
1061
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1062
|
+
details?: {
|
|
1063
|
+
path?: string;
|
|
1064
|
+
message?: string;
|
|
1065
|
+
}[];
|
|
1066
|
+
};
|
|
1067
|
+
};
|
|
1068
|
+
};
|
|
1069
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
1070
|
+
429: {
|
|
1071
|
+
headers: {
|
|
1072
|
+
[name: string]: unknown;
|
|
1073
|
+
};
|
|
1074
|
+
content: {
|
|
1075
|
+
"application/json": {
|
|
1076
|
+
statusCode: number;
|
|
1077
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1078
|
+
error: string;
|
|
1079
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1080
|
+
message: string;
|
|
1081
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
1082
|
+
code: string;
|
|
1083
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1084
|
+
details?: {
|
|
1085
|
+
path?: string;
|
|
1086
|
+
message?: string;
|
|
1087
|
+
}[];
|
|
1088
|
+
};
|
|
1089
|
+
};
|
|
1090
|
+
};
|
|
1091
|
+
/** @description Service is warming up. */
|
|
1092
|
+
503: {
|
|
1093
|
+
headers: {
|
|
1094
|
+
[name: string]: unknown;
|
|
1095
|
+
};
|
|
1096
|
+
content: {
|
|
1097
|
+
"application/json": {
|
|
1098
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1099
|
+
error: string;
|
|
1100
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1101
|
+
message: string;
|
|
1102
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1103
|
+
code: string;
|
|
1104
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1105
|
+
details?: {
|
|
1106
|
+
path?: string;
|
|
1107
|
+
message?: string;
|
|
1108
|
+
}[];
|
|
1109
|
+
};
|
|
1110
|
+
};
|
|
1111
|
+
};
|
|
1112
|
+
};
|
|
1113
|
+
};
|
|
1114
|
+
put?: never;
|
|
1115
|
+
post?: never;
|
|
1116
|
+
delete?: never;
|
|
1117
|
+
options?: never;
|
|
1118
|
+
head?: never;
|
|
1119
|
+
patch?: never;
|
|
1120
|
+
trace?: never;
|
|
1121
|
+
};
|
|
1122
|
+
"/v1/regions/{code}/census": {
|
|
1123
|
+
parameters: {
|
|
1124
|
+
query?: never;
|
|
1125
|
+
header?: never;
|
|
1126
|
+
path?: never;
|
|
1127
|
+
cookie?: never;
|
|
1128
|
+
};
|
|
1129
|
+
/**
|
|
1130
|
+
* NSP 2021 census of one unit (employment, dwellings, buildings, households) at any of the three TERC levels
|
|
1131
|
+
* @description The 2021 national census (stan na 31.03.2021, GUS BDL) for the unit the TERC code names — one block per family: `economicActivity` (`employed`, `economicallyActive`, persons 15+), `dwellings`, `buildings` and `households` (`total` each). A block the register does not publish for the level is `null`, and a figure the register suppressed is `null` inside a block — never zero. A voivodeship (2-digit code) is the SUM of its powiats' figures, measured over the powiats that published them: each block states that reach in `unitsReported`/`unitsTotal`. A powiat and a gmina serve the register's own figures (`unitsReported`/`unitsTotal` null). 404 for an unknown code, or when this instance carries no census figure in scope (an absent dataset is not an empty one).
|
|
1132
|
+
*/
|
|
1133
|
+
get: {
|
|
1134
|
+
parameters: {
|
|
1135
|
+
query?: never;
|
|
1136
|
+
header?: never;
|
|
1137
|
+
path: {
|
|
1138
|
+
/** @description TERC code, the length naming the level: 2 digits for a voivodeship ('14'), 4 for a powiat ('1401'), 6 for a gmina ('140101'). */
|
|
1139
|
+
code: string;
|
|
1140
|
+
};
|
|
1141
|
+
cookie?: never;
|
|
1142
|
+
};
|
|
1143
|
+
requestBody?: never;
|
|
1144
|
+
responses: {
|
|
1145
|
+
/** @description Successful response. */
|
|
1146
|
+
200: {
|
|
1147
|
+
headers: {
|
|
1148
|
+
[name: string]: unknown;
|
|
1149
|
+
};
|
|
1150
|
+
content: {
|
|
1151
|
+
"application/json": {
|
|
1152
|
+
terc: string;
|
|
1153
|
+
year: string;
|
|
1154
|
+
economicActivity: {
|
|
1155
|
+
unitsReported: number | null;
|
|
1156
|
+
unitsTotal: number | null;
|
|
1157
|
+
employed: number | null;
|
|
1158
|
+
economicallyActive: number | null;
|
|
1159
|
+
} | null;
|
|
1160
|
+
dwellings: {
|
|
1161
|
+
unitsReported: number | null;
|
|
1162
|
+
unitsTotal: number | null;
|
|
1163
|
+
total: number | null;
|
|
1164
|
+
} | null;
|
|
1165
|
+
buildings: {
|
|
1166
|
+
unitsReported: number | null;
|
|
1167
|
+
unitsTotal: number | null;
|
|
1168
|
+
total: number | null;
|
|
1169
|
+
} | null;
|
|
1170
|
+
households: {
|
|
1171
|
+
unitsReported: number | null;
|
|
1172
|
+
unitsTotal: number | null;
|
|
1173
|
+
total: number | null;
|
|
1174
|
+
} | null;
|
|
1175
|
+
varIds: {
|
|
1176
|
+
[key: string]: number;
|
|
1177
|
+
};
|
|
1178
|
+
};
|
|
1179
|
+
};
|
|
1180
|
+
};
|
|
1181
|
+
/** @description Invalid query parameters. */
|
|
1182
|
+
400: {
|
|
1183
|
+
headers: {
|
|
1184
|
+
[name: string]: unknown;
|
|
1185
|
+
};
|
|
1186
|
+
content: {
|
|
1187
|
+
"application/json": {
|
|
1188
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1189
|
+
error: string;
|
|
1190
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1191
|
+
message: string;
|
|
1192
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1193
|
+
code: string;
|
|
1194
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1195
|
+
details?: {
|
|
1196
|
+
path?: string;
|
|
1197
|
+
message?: string;
|
|
1198
|
+
}[];
|
|
1199
|
+
};
|
|
1200
|
+
};
|
|
1201
|
+
};
|
|
1202
|
+
/** @description Unknown TERC code, or no census figures fetched for the unit. */
|
|
1203
|
+
404: {
|
|
1204
|
+
headers: {
|
|
1205
|
+
[name: string]: unknown;
|
|
1206
|
+
};
|
|
1207
|
+
content: {
|
|
1208
|
+
"application/json": {
|
|
1209
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1210
|
+
error: string;
|
|
1211
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1212
|
+
message: string;
|
|
1213
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1214
|
+
code: string;
|
|
1215
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1216
|
+
details?: {
|
|
1217
|
+
path?: string;
|
|
1218
|
+
message?: string;
|
|
1219
|
+
}[];
|
|
1220
|
+
};
|
|
1221
|
+
};
|
|
1222
|
+
};
|
|
1223
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
1224
|
+
429: {
|
|
1225
|
+
headers: {
|
|
1226
|
+
[name: string]: unknown;
|
|
1227
|
+
};
|
|
1228
|
+
content: {
|
|
1229
|
+
"application/json": {
|
|
1230
|
+
statusCode: number;
|
|
1231
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1232
|
+
error: string;
|
|
1233
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1234
|
+
message: string;
|
|
1235
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
1236
|
+
code: string;
|
|
1237
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1238
|
+
details?: {
|
|
1239
|
+
path?: string;
|
|
1240
|
+
message?: string;
|
|
1241
|
+
}[];
|
|
1242
|
+
};
|
|
1243
|
+
};
|
|
1244
|
+
};
|
|
1245
|
+
/** @description Service is warming up, or the census figures could not be read. */
|
|
1246
|
+
503: {
|
|
1247
|
+
headers: {
|
|
1248
|
+
[name: string]: unknown;
|
|
1249
|
+
};
|
|
1250
|
+
content: {
|
|
1251
|
+
"application/json": {
|
|
1252
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1253
|
+
error: string;
|
|
1254
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1255
|
+
message: string;
|
|
1256
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1257
|
+
code: string;
|
|
1258
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1259
|
+
details?: {
|
|
1260
|
+
path?: string;
|
|
1261
|
+
message?: string;
|
|
1262
|
+
}[];
|
|
1263
|
+
};
|
|
1264
|
+
};
|
|
1265
|
+
};
|
|
1266
|
+
};
|
|
1267
|
+
};
|
|
1268
|
+
put?: never;
|
|
1269
|
+
post?: never;
|
|
1270
|
+
delete?: never;
|
|
1271
|
+
options?: never;
|
|
1272
|
+
head?: never;
|
|
1273
|
+
patch?: never;
|
|
1274
|
+
trace?: never;
|
|
1275
|
+
};
|
|
1276
|
+
"/v1/boundaries/counties": {
|
|
1277
|
+
parameters: {
|
|
1278
|
+
query?: never;
|
|
1279
|
+
header?: never;
|
|
1280
|
+
path?: never;
|
|
1281
|
+
cookie?: never;
|
|
1282
|
+
};
|
|
1283
|
+
/**
|
|
1284
|
+
* The 380 counties' administrative boundaries as WGS84 GeoJSON (GUGiK PRG)
|
|
1285
|
+
* @description An RFC 7946 FeatureCollection of Poland's counties (powiaty, including the cities with county rights), keyed by TERC code — the geometry a choropleth keyed on /v1/regions' county codes draws. Each feature's geometry is a Polygon or MultiPolygon in [lon, lat] degrees (exterior rings counterclockwise, holes clockwise); shared borders are simplified ONCE, so neighbouring features carry the same line with no cracks. Properties: `terc` (4 digits), `name` (verbatim TERC name), `kind` ("powiat"), `provinceCode` (2 digits), `labelLat`/`labelLon` — the unit's label point (the interior point furthest from its boundary), for badges and station assignment. The geometry is the committed PRG edition reported by the `X-PRG-Boundaries-Version` response header; names come from the TERC catalog (null when the instance's catalog does not carry a code). The response is ~0.7 MB raw / well under 200 kB compressed for the whole country; the optional `province` filter trims it to one voivodeship.
|
|
1286
|
+
*/
|
|
1287
|
+
get: {
|
|
1288
|
+
parameters: {
|
|
1289
|
+
query?: {
|
|
1290
|
+
/** @description Optional 2-digit TERC voivodeship code filter (e.g. '14'), as served by /v1/regions — trims the collection to that voivodeship's geometry. A blank value is treated as absent. */
|
|
1291
|
+
province?: string;
|
|
1292
|
+
};
|
|
1293
|
+
header?: never;
|
|
1294
|
+
path?: never;
|
|
1295
|
+
cookie?: never;
|
|
1296
|
+
};
|
|
1297
|
+
requestBody?: never;
|
|
1298
|
+
responses: {
|
|
1299
|
+
/** @description Successful response — an RFC 7946 FeatureCollection. */
|
|
1300
|
+
200: {
|
|
1301
|
+
headers: {
|
|
1302
|
+
[name: string]: unknown;
|
|
1303
|
+
};
|
|
1304
|
+
content: {
|
|
1305
|
+
"application/geo+json": {
|
|
1306
|
+
/** @constant */
|
|
1307
|
+
type: "FeatureCollection";
|
|
1308
|
+
features: {
|
|
1309
|
+
/** @constant */
|
|
1310
|
+
type: "Feature";
|
|
1311
|
+
geometry: {
|
|
1312
|
+
/** @constant */
|
|
1313
|
+
type: "Polygon";
|
|
1314
|
+
coordinates: [
|
|
1315
|
+
number,
|
|
1316
|
+
number
|
|
1317
|
+
][][];
|
|
1318
|
+
} | {
|
|
1319
|
+
/** @constant */
|
|
1320
|
+
type: "MultiPolygon";
|
|
1321
|
+
coordinates: [
|
|
1322
|
+
number,
|
|
1323
|
+
number
|
|
1324
|
+
][][][];
|
|
1325
|
+
};
|
|
1326
|
+
properties: {
|
|
1327
|
+
terc: string;
|
|
1328
|
+
name: string | null;
|
|
1329
|
+
/** @enum {string} */
|
|
1330
|
+
kind: "powiat" | "region";
|
|
1331
|
+
provinceCode: string;
|
|
1332
|
+
labelLat: number;
|
|
1333
|
+
labelLon: number;
|
|
1334
|
+
};
|
|
1335
|
+
}[];
|
|
1336
|
+
};
|
|
1337
|
+
};
|
|
1338
|
+
};
|
|
1339
|
+
/** @description Invalid query parameters. */
|
|
1340
|
+
400: {
|
|
1341
|
+
headers: {
|
|
1342
|
+
[name: string]: unknown;
|
|
1343
|
+
};
|
|
1344
|
+
content: {
|
|
1345
|
+
"application/json": {
|
|
1346
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1347
|
+
error: string;
|
|
1348
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1349
|
+
message: string;
|
|
1350
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1351
|
+
code: string;
|
|
1352
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1353
|
+
details?: {
|
|
1354
|
+
path?: string;
|
|
1355
|
+
message?: string;
|
|
1356
|
+
}[];
|
|
1357
|
+
};
|
|
1358
|
+
};
|
|
1359
|
+
};
|
|
1360
|
+
/** @description The province filter is a well-formed code the boundary geometry does not cover. */
|
|
1361
|
+
404: {
|
|
1362
|
+
headers: {
|
|
1363
|
+
[name: string]: unknown;
|
|
1364
|
+
};
|
|
1365
|
+
content: {
|
|
1366
|
+
"application/json": {
|
|
1367
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1368
|
+
error: string;
|
|
1369
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1370
|
+
message: string;
|
|
1371
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1372
|
+
code: string;
|
|
1373
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1374
|
+
details?: {
|
|
1375
|
+
path?: string;
|
|
1376
|
+
message?: string;
|
|
1377
|
+
}[];
|
|
1378
|
+
};
|
|
1379
|
+
};
|
|
1380
|
+
};
|
|
1381
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
1382
|
+
429: {
|
|
1383
|
+
headers: {
|
|
1384
|
+
[name: string]: unknown;
|
|
1385
|
+
};
|
|
1386
|
+
content: {
|
|
1387
|
+
"application/json": {
|
|
1388
|
+
statusCode: number;
|
|
1389
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1390
|
+
error: string;
|
|
1391
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1392
|
+
message: string;
|
|
1393
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
1394
|
+
code: string;
|
|
1395
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1396
|
+
details?: {
|
|
1397
|
+
path?: string;
|
|
1398
|
+
message?: string;
|
|
1399
|
+
}[];
|
|
1400
|
+
};
|
|
1401
|
+
};
|
|
1402
|
+
};
|
|
1403
|
+
/** @description Service is warming up. */
|
|
1404
|
+
503: {
|
|
1405
|
+
headers: {
|
|
1406
|
+
[name: string]: unknown;
|
|
1407
|
+
};
|
|
1408
|
+
content: {
|
|
1409
|
+
"application/json": {
|
|
1410
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1411
|
+
error: string;
|
|
1412
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1413
|
+
message: string;
|
|
1414
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1415
|
+
code: string;
|
|
1416
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1417
|
+
details?: {
|
|
1418
|
+
path?: string;
|
|
1419
|
+
message?: string;
|
|
1420
|
+
}[];
|
|
1421
|
+
};
|
|
1422
|
+
};
|
|
1423
|
+
};
|
|
1424
|
+
};
|
|
1425
|
+
};
|
|
1426
|
+
put?: never;
|
|
1427
|
+
post?: never;
|
|
1428
|
+
delete?: never;
|
|
1429
|
+
options?: never;
|
|
1430
|
+
head?: never;
|
|
1431
|
+
patch?: never;
|
|
1432
|
+
trace?: never;
|
|
1433
|
+
};
|
|
1434
|
+
"/v1/boundaries/regions": {
|
|
1435
|
+
parameters: {
|
|
1436
|
+
query?: never;
|
|
1437
|
+
header?: never;
|
|
1438
|
+
path?: never;
|
|
1439
|
+
cookie?: never;
|
|
1440
|
+
};
|
|
1441
|
+
/**
|
|
1442
|
+
* The 16 voivodeships' administrative boundaries as WGS84 GeoJSON (GUGiK PRG)
|
|
1443
|
+
* @description An RFC 7946 FeatureCollection of Poland's voivodeships, keyed by TERC code — the same committed PRG geometry as GET /v1/boundaries/counties, at the province level. Properties: `terc` (2 digits), `name` (verbatim TERC name), `kind` ("region"), `provinceCode` (equal to `terc`), `labelLat`/`labelLon` (the label point). The `province` filter narrows the collection to one voivodeship.
|
|
1444
|
+
*/
|
|
1445
|
+
get: {
|
|
1446
|
+
parameters: {
|
|
1447
|
+
query?: {
|
|
1448
|
+
/** @description Optional 2-digit TERC voivodeship code filter (e.g. '14'), as served by /v1/regions — trims the collection to that voivodeship's geometry. A blank value is treated as absent. */
|
|
1449
|
+
province?: string;
|
|
1450
|
+
};
|
|
1451
|
+
header?: never;
|
|
1452
|
+
path?: never;
|
|
1453
|
+
cookie?: never;
|
|
1454
|
+
};
|
|
1455
|
+
requestBody?: never;
|
|
1456
|
+
responses: {
|
|
1457
|
+
/** @description Successful response — an RFC 7946 FeatureCollection. */
|
|
1458
|
+
200: {
|
|
1459
|
+
headers: {
|
|
1460
|
+
[name: string]: unknown;
|
|
1461
|
+
};
|
|
1462
|
+
content: {
|
|
1463
|
+
"application/geo+json": {
|
|
1464
|
+
/** @constant */
|
|
1465
|
+
type: "FeatureCollection";
|
|
1466
|
+
features: {
|
|
1467
|
+
/** @constant */
|
|
1468
|
+
type: "Feature";
|
|
1469
|
+
geometry: {
|
|
1470
|
+
/** @constant */
|
|
1471
|
+
type: "Polygon";
|
|
1472
|
+
coordinates: [
|
|
1473
|
+
number,
|
|
1474
|
+
number
|
|
1475
|
+
][][];
|
|
1476
|
+
} | {
|
|
1477
|
+
/** @constant */
|
|
1478
|
+
type: "MultiPolygon";
|
|
1479
|
+
coordinates: [
|
|
1480
|
+
number,
|
|
1481
|
+
number
|
|
1482
|
+
][][][];
|
|
1483
|
+
};
|
|
1484
|
+
properties: {
|
|
1485
|
+
terc: string;
|
|
1486
|
+
name: string | null;
|
|
1487
|
+
/** @enum {string} */
|
|
1488
|
+
kind: "powiat" | "region";
|
|
1489
|
+
provinceCode: string;
|
|
1490
|
+
labelLat: number;
|
|
1491
|
+
labelLon: number;
|
|
1492
|
+
};
|
|
1493
|
+
}[];
|
|
1494
|
+
};
|
|
1495
|
+
};
|
|
1496
|
+
};
|
|
1497
|
+
/** @description Invalid query parameters. */
|
|
1498
|
+
400: {
|
|
1499
|
+
headers: {
|
|
1500
|
+
[name: string]: unknown;
|
|
1501
|
+
};
|
|
1502
|
+
content: {
|
|
1503
|
+
"application/json": {
|
|
1504
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1505
|
+
error: string;
|
|
1506
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1507
|
+
message: string;
|
|
1508
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1509
|
+
code: string;
|
|
1510
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1511
|
+
details?: {
|
|
1512
|
+
path?: string;
|
|
1513
|
+
message?: string;
|
|
1514
|
+
}[];
|
|
1515
|
+
};
|
|
1516
|
+
};
|
|
1517
|
+
};
|
|
1518
|
+
/** @description The province filter is a well-formed code the boundary geometry does not cover. */
|
|
1519
|
+
404: {
|
|
1520
|
+
headers: {
|
|
1521
|
+
[name: string]: unknown;
|
|
1522
|
+
};
|
|
1523
|
+
content: {
|
|
1524
|
+
"application/json": {
|
|
1525
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1526
|
+
error: string;
|
|
1527
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1528
|
+
message: string;
|
|
1529
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1530
|
+
code: string;
|
|
1531
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1532
|
+
details?: {
|
|
1533
|
+
path?: string;
|
|
1534
|
+
message?: string;
|
|
1535
|
+
}[];
|
|
1536
|
+
};
|
|
1537
|
+
};
|
|
1538
|
+
};
|
|
1539
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
1540
|
+
429: {
|
|
1541
|
+
headers: {
|
|
1542
|
+
[name: string]: unknown;
|
|
1543
|
+
};
|
|
1544
|
+
content: {
|
|
1545
|
+
"application/json": {
|
|
1546
|
+
statusCode: number;
|
|
1547
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1548
|
+
error: string;
|
|
1549
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1550
|
+
message: string;
|
|
1551
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
1552
|
+
code: string;
|
|
1553
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1554
|
+
details?: {
|
|
1555
|
+
path?: string;
|
|
1556
|
+
message?: string;
|
|
1557
|
+
}[];
|
|
1558
|
+
};
|
|
1559
|
+
};
|
|
1560
|
+
};
|
|
1561
|
+
/** @description Service is warming up. */
|
|
1562
|
+
503: {
|
|
1563
|
+
headers: {
|
|
1564
|
+
[name: string]: unknown;
|
|
1565
|
+
};
|
|
1566
|
+
content: {
|
|
1567
|
+
"application/json": {
|
|
1568
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1569
|
+
error: string;
|
|
1570
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1571
|
+
message: string;
|
|
1572
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1573
|
+
code: string;
|
|
1574
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1575
|
+
details?: {
|
|
1576
|
+
path?: string;
|
|
1577
|
+
message?: string;
|
|
1578
|
+
}[];
|
|
1579
|
+
};
|
|
1580
|
+
};
|
|
1581
|
+
};
|
|
1582
|
+
};
|
|
1583
|
+
};
|
|
1584
|
+
put?: never;
|
|
1585
|
+
post?: never;
|
|
1586
|
+
delete?: never;
|
|
1587
|
+
options?: never;
|
|
1588
|
+
head?: never;
|
|
1589
|
+
patch?: never;
|
|
1590
|
+
trace?: never;
|
|
1591
|
+
};
|
|
1592
|
+
"/v1/streets": {
|
|
1593
|
+
parameters: {
|
|
1594
|
+
query?: never;
|
|
1595
|
+
header?: never;
|
|
1596
|
+
path?: never;
|
|
1597
|
+
cookie?: never;
|
|
1598
|
+
};
|
|
1599
|
+
/**
|
|
1600
|
+
* Street autocomplete (GUS ULIC, ≈310k streets) — per locality or country-wide
|
|
1601
|
+
* @description With city: street search within one locality (pick a locality via /v1/localities first, then type a street). With q alone: country-wide prefix search — which localities have this street? Rows then carry localityName and the inflated province/county to disambiguate repeated names.
|
|
1602
|
+
*/
|
|
1603
|
+
get: {
|
|
1604
|
+
parameters: {
|
|
1605
|
+
query?: {
|
|
1606
|
+
/** @description Locality SYM (7 digits, as returned by /v1/localities). Optional: omit it (with q) for a country-wide street search. */
|
|
1607
|
+
city?: string;
|
|
1608
|
+
/** @description Diacritics-insensitive prefix against the street name without its 'ul.' prefix, in either member order — the natural reading order ('10 Marca' finds 'ul. 10 Marca') or the register-order main member ('korfantego' finds 'ul. Wojciecha Korfantego'). Required (and triggers country-wide search) when city is absent; optional within a city (omitted → first `limit` streets alphabetically). */
|
|
1609
|
+
q?: string;
|
|
1610
|
+
/** @description Maximum results per page (1–50). */
|
|
1611
|
+
limit?: number;
|
|
1612
|
+
/** @description Skip the first N results (0-based, max 10000) to page past the limit. */
|
|
1613
|
+
offset?: number;
|
|
1614
|
+
/** @description 'name' (default) keeps the established search-key ordering; 'prominence' ranks by real-world volume — PRG address points on the street first, then how many localities register it (ULIC), then the name key as the tie-break. The response carries addressCount/localityCount in this mode. */
|
|
1615
|
+
sort?: "name" | "prominence";
|
|
1616
|
+
};
|
|
1617
|
+
header?: never;
|
|
1618
|
+
path?: never;
|
|
1619
|
+
cookie?: never;
|
|
1620
|
+
};
|
|
1621
|
+
requestBody?: never;
|
|
1622
|
+
responses: {
|
|
1623
|
+
/** @description Successful response. */
|
|
1624
|
+
200: {
|
|
1625
|
+
headers: {
|
|
1626
|
+
[name: string]: unknown;
|
|
1627
|
+
};
|
|
1628
|
+
content: {
|
|
1629
|
+
"application/json": {
|
|
1630
|
+
streets: {
|
|
1631
|
+
name: string;
|
|
1632
|
+
cecha: string | null;
|
|
1633
|
+
id: string;
|
|
1634
|
+
city: string;
|
|
1635
|
+
localityName?: string;
|
|
1636
|
+
province?: string | null;
|
|
1637
|
+
county?: string | null;
|
|
1638
|
+
provinceCode?: string | null;
|
|
1639
|
+
countyCode?: string | null;
|
|
1640
|
+
addressCount?: number;
|
|
1641
|
+
localityCount?: number;
|
|
1642
|
+
}[];
|
|
1643
|
+
};
|
|
1644
|
+
};
|
|
1645
|
+
};
|
|
1646
|
+
/** @description Invalid query parameters. */
|
|
1647
|
+
400: {
|
|
1648
|
+
headers: {
|
|
1649
|
+
[name: string]: unknown;
|
|
1650
|
+
};
|
|
1651
|
+
content: {
|
|
1652
|
+
"application/json": {
|
|
1653
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1654
|
+
error: string;
|
|
1655
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1656
|
+
message: string;
|
|
1657
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1658
|
+
code: string;
|
|
1659
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1660
|
+
details?: {
|
|
1661
|
+
path?: string;
|
|
1662
|
+
message?: string;
|
|
1663
|
+
}[];
|
|
1664
|
+
};
|
|
1665
|
+
};
|
|
1666
|
+
};
|
|
1667
|
+
/** @description Unknown locality SYM. */
|
|
1668
|
+
404: {
|
|
1669
|
+
headers: {
|
|
1670
|
+
[name: string]: unknown;
|
|
1671
|
+
};
|
|
1672
|
+
content: {
|
|
1673
|
+
"application/json": {
|
|
1674
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1675
|
+
error: string;
|
|
1676
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1677
|
+
message: string;
|
|
1678
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1679
|
+
code: string;
|
|
1680
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1681
|
+
details?: {
|
|
1682
|
+
path?: string;
|
|
1683
|
+
message?: string;
|
|
1684
|
+
}[];
|
|
1685
|
+
};
|
|
1686
|
+
};
|
|
1687
|
+
};
|
|
1688
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
1689
|
+
429: {
|
|
1690
|
+
headers: {
|
|
1691
|
+
[name: string]: unknown;
|
|
1692
|
+
};
|
|
1693
|
+
content: {
|
|
1694
|
+
"application/json": {
|
|
1695
|
+
statusCode: number;
|
|
1696
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1697
|
+
error: string;
|
|
1698
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1699
|
+
message: string;
|
|
1700
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
1701
|
+
code: string;
|
|
1702
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1703
|
+
details?: {
|
|
1704
|
+
path?: string;
|
|
1705
|
+
message?: string;
|
|
1706
|
+
}[];
|
|
1707
|
+
};
|
|
1708
|
+
};
|
|
1709
|
+
};
|
|
1710
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
1711
|
+
500: {
|
|
1712
|
+
headers: {
|
|
1713
|
+
[name: string]: unknown;
|
|
1714
|
+
};
|
|
1715
|
+
content: {
|
|
1716
|
+
"application/json": {
|
|
1717
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1718
|
+
error: string;
|
|
1719
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1720
|
+
message: string;
|
|
1721
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1722
|
+
code: string;
|
|
1723
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1724
|
+
details?: {
|
|
1725
|
+
path?: string;
|
|
1726
|
+
message?: string;
|
|
1727
|
+
}[];
|
|
1728
|
+
};
|
|
1729
|
+
};
|
|
1730
|
+
};
|
|
1731
|
+
/** @description Street dataset not available (fetch it via POST /admin/fetch-data?datasets=ulic). */
|
|
1732
|
+
503: {
|
|
1733
|
+
headers: {
|
|
1734
|
+
[name: string]: unknown;
|
|
1735
|
+
};
|
|
1736
|
+
content: {
|
|
1737
|
+
"application/json": {
|
|
1738
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1739
|
+
error: string;
|
|
1740
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1741
|
+
message: string;
|
|
1742
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1743
|
+
code: string;
|
|
1744
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1745
|
+
details?: {
|
|
1746
|
+
path?: string;
|
|
1747
|
+
message?: string;
|
|
1748
|
+
}[];
|
|
1749
|
+
};
|
|
1750
|
+
};
|
|
1751
|
+
};
|
|
1752
|
+
};
|
|
1753
|
+
};
|
|
1754
|
+
put?: never;
|
|
1755
|
+
post?: never;
|
|
1756
|
+
delete?: never;
|
|
1757
|
+
options?: never;
|
|
1758
|
+
head?: never;
|
|
1759
|
+
patch?: never;
|
|
1760
|
+
trace?: never;
|
|
1761
|
+
};
|
|
1762
|
+
"/v1/postal-codes": {
|
|
1763
|
+
parameters: {
|
|
1764
|
+
query?: never;
|
|
1765
|
+
header?: never;
|
|
1766
|
+
path?: never;
|
|
1767
|
+
cookie?: never;
|
|
1768
|
+
};
|
|
1769
|
+
/**
|
|
1770
|
+
* Polish postal-code lookup (PNA → locality, GeoNames-derived)
|
|
1771
|
+
* @description Three modes. q=…: a prefix lookup — each row carries the TERC-inflated hierarchy (province, county, municipality) and — when the row resolves to one locality (PRG official set → gmina → voivodeship → name) — its SYM, type and population; citySlug is the canonical /miasta link for rows whose name is a catalog city that could not be pinned to one SYM (the divided cities). locality=<SYM>: the codes serving one locality, one row per code, named for the requested locality. lat+lon: nearest mode — the codes whose official PRG centroids are closest, distance-sorted (503 until the PRG ingest produced them). postalCodesTruncated: true when more rows matched than the limit (row modes). meta.total counts the matching rows before offset/limit (prefix matches in q mode, the locality's full code set in locality mode, all centroid codes in nearest mode).
|
|
1772
|
+
*/
|
|
1773
|
+
get: {
|
|
1774
|
+
parameters: {
|
|
1775
|
+
query?: {
|
|
1776
|
+
/** @description Postal code in any form: '00-950', '00950', or a prefix of either ('00-9', '009'); non-digits are ignored. Required unless locality or lat+lon is given. */
|
|
1777
|
+
q?: string;
|
|
1778
|
+
/** @description Locality SYM (7 digits, as returned by /v1/localities): the postal codes serving it — PRG official set first, then the PNA name ladder; one row per code, named for the requested locality (synthesized from the registry when GeoNames never paired it). Mutually exclusive with q and lat+lon; sym/type/population always describe the requested locality. */
|
|
1779
|
+
locality?: string;
|
|
1780
|
+
/** @description WGS84 latitude (-90..90). Together with lon triggers nearest mode: the codes whose official PRG centroids are closest, distance-sorted (each with distanceKm, centroidLat/centroidLon, addressCount, streetCount). Mutually exclusive with q and locality. A blank value ('?lat=') is treated as absent — it does not trigger the mode. */
|
|
1781
|
+
lat?: number;
|
|
1782
|
+
/** @description WGS84 longitude (-180..180). Must be given together with lat. */
|
|
1783
|
+
lon?: number;
|
|
1784
|
+
/** @description Maximum results (1–50). */
|
|
1785
|
+
limit?: number;
|
|
1786
|
+
/** @description Skip the first N results (0-based, max 10000) to page past the limit. */
|
|
1787
|
+
offset?: number;
|
|
1788
|
+
/** @description 'geojson' answers an RFC 7946 FeatureCollection (row points — the PRG centroids in nearest mode — in [lon,lat] order) instead of the JSON envelope. */
|
|
1789
|
+
format?: "json" | "geojson";
|
|
1790
|
+
};
|
|
1791
|
+
header?: never;
|
|
1792
|
+
path?: never;
|
|
1793
|
+
cookie?: never;
|
|
1794
|
+
};
|
|
1795
|
+
requestBody?: never;
|
|
1796
|
+
responses: {
|
|
1797
|
+
/** @description Successful response — the row shape depends on the mode: the q/locality DTO for prefix and locality lookups, the nearest DTO (code, distanceKm, centroid, counts) for lat+lon. */
|
|
1798
|
+
200: {
|
|
1799
|
+
headers: {
|
|
1800
|
+
[name: string]: unknown;
|
|
1801
|
+
};
|
|
1802
|
+
content: {
|
|
1803
|
+
"application/json": {
|
|
1804
|
+
postalCodes: {
|
|
1805
|
+
code: string;
|
|
1806
|
+
city: string;
|
|
1807
|
+
province: string | null;
|
|
1808
|
+
county: string | null;
|
|
1809
|
+
municipality: string | null;
|
|
1810
|
+
municipalityKind: string | null;
|
|
1811
|
+
lat: number | null;
|
|
1812
|
+
lon: number | null;
|
|
1813
|
+
sym: string | null;
|
|
1814
|
+
citySlug: string | null;
|
|
1815
|
+
type: string | null;
|
|
1816
|
+
typeLabel: string | null;
|
|
1817
|
+
population: number | null;
|
|
1818
|
+
}[];
|
|
1819
|
+
postalCodesTruncated?: boolean;
|
|
1820
|
+
meta?: {
|
|
1821
|
+
total: number;
|
|
1822
|
+
offset: number;
|
|
1823
|
+
limit: number;
|
|
1824
|
+
};
|
|
1825
|
+
} | {
|
|
1826
|
+
postalCodes: {
|
|
1827
|
+
code: string;
|
|
1828
|
+
distanceKm: number;
|
|
1829
|
+
centroidLat: number;
|
|
1830
|
+
centroidLon: number;
|
|
1831
|
+
addressCount: number;
|
|
1832
|
+
streetCount: number;
|
|
1833
|
+
}[];
|
|
1834
|
+
meta?: {
|
|
1835
|
+
total: number;
|
|
1836
|
+
offset: number;
|
|
1837
|
+
limit: number;
|
|
1838
|
+
};
|
|
1839
|
+
};
|
|
1840
|
+
};
|
|
1841
|
+
};
|
|
1842
|
+
/** @description Invalid query parameters. */
|
|
1843
|
+
400: {
|
|
1844
|
+
headers: {
|
|
1845
|
+
[name: string]: unknown;
|
|
1846
|
+
};
|
|
1847
|
+
content: {
|
|
1848
|
+
"application/json": {
|
|
1849
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1850
|
+
error: string;
|
|
1851
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1852
|
+
message: string;
|
|
1853
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1854
|
+
code: string;
|
|
1855
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1856
|
+
details?: {
|
|
1857
|
+
path?: string;
|
|
1858
|
+
message?: string;
|
|
1859
|
+
}[];
|
|
1860
|
+
};
|
|
1861
|
+
};
|
|
1862
|
+
};
|
|
1863
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
1864
|
+
429: {
|
|
1865
|
+
headers: {
|
|
1866
|
+
[name: string]: unknown;
|
|
1867
|
+
};
|
|
1868
|
+
content: {
|
|
1869
|
+
"application/json": {
|
|
1870
|
+
statusCode: number;
|
|
1871
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1872
|
+
error: string;
|
|
1873
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1874
|
+
message: string;
|
|
1875
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
1876
|
+
code: string;
|
|
1877
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1878
|
+
details?: {
|
|
1879
|
+
path?: string;
|
|
1880
|
+
message?: string;
|
|
1881
|
+
}[];
|
|
1882
|
+
};
|
|
1883
|
+
};
|
|
1884
|
+
};
|
|
1885
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
1886
|
+
500: {
|
|
1887
|
+
headers: {
|
|
1888
|
+
[name: string]: unknown;
|
|
1889
|
+
};
|
|
1890
|
+
content: {
|
|
1891
|
+
"application/json": {
|
|
1892
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1893
|
+
error: string;
|
|
1894
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1895
|
+
message: string;
|
|
1896
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1897
|
+
code: string;
|
|
1898
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1899
|
+
details?: {
|
|
1900
|
+
path?: string;
|
|
1901
|
+
message?: string;
|
|
1902
|
+
}[];
|
|
1903
|
+
};
|
|
1904
|
+
};
|
|
1905
|
+
};
|
|
1906
|
+
/** @description Postal-code dataset not available (generate data/pna CSV via pnpm fetch:pna); the nearest mode additionally requires the PRG ingest. */
|
|
1907
|
+
503: {
|
|
1908
|
+
headers: {
|
|
1909
|
+
[name: string]: unknown;
|
|
1910
|
+
};
|
|
1911
|
+
content: {
|
|
1912
|
+
"application/json": {
|
|
1913
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
1914
|
+
error: string;
|
|
1915
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
1916
|
+
message: string;
|
|
1917
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
1918
|
+
code: string;
|
|
1919
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
1920
|
+
details?: {
|
|
1921
|
+
path?: string;
|
|
1922
|
+
message?: string;
|
|
1923
|
+
}[];
|
|
1924
|
+
};
|
|
1925
|
+
};
|
|
1926
|
+
};
|
|
1927
|
+
};
|
|
1928
|
+
};
|
|
1929
|
+
put?: never;
|
|
1930
|
+
post?: never;
|
|
1931
|
+
delete?: never;
|
|
1932
|
+
options?: never;
|
|
1933
|
+
head?: never;
|
|
1934
|
+
patch?: never;
|
|
1935
|
+
trace?: never;
|
|
1936
|
+
};
|
|
1937
|
+
"/v1/postal-codes/{code}": {
|
|
1938
|
+
parameters: {
|
|
1939
|
+
query?: never;
|
|
1940
|
+
header?: never;
|
|
1941
|
+
path?: never;
|
|
1942
|
+
cookie?: never;
|
|
1943
|
+
};
|
|
1944
|
+
/**
|
|
1945
|
+
* Postal-code detail by code (all localities + PRG address-point aggregates)
|
|
1946
|
+
* @description One code's full record: every PNA (code, locality) row with the TERC-inflated hierarchy and resolved locality extras, plus the prg block — building count, distinct streets, weighted centroid and a capped alphabetical street-name sample (GUGiK address points; null when the PRG dataset is not ingested on this instance). Unknown codes answer 404; existence is the PNA dataset's.
|
|
1947
|
+
*/
|
|
1948
|
+
get: {
|
|
1949
|
+
parameters: {
|
|
1950
|
+
query?: never;
|
|
1951
|
+
header?: never;
|
|
1952
|
+
path: {
|
|
1953
|
+
/** @description Postal code in the display ('59-700') or digits ('59700') form. */
|
|
1954
|
+
code: string;
|
|
1955
|
+
};
|
|
1956
|
+
cookie?: never;
|
|
1957
|
+
};
|
|
1958
|
+
requestBody?: never;
|
|
1959
|
+
responses: {
|
|
1960
|
+
/** @description Successful response. */
|
|
1961
|
+
200: {
|
|
1962
|
+
headers: {
|
|
1963
|
+
[name: string]: unknown;
|
|
1964
|
+
};
|
|
1965
|
+
content: {
|
|
1966
|
+
"application/json": {
|
|
1967
|
+
code: string;
|
|
1968
|
+
rows: {
|
|
1969
|
+
code: string;
|
|
1970
|
+
city: string;
|
|
1971
|
+
province: string | null;
|
|
1972
|
+
county: string | null;
|
|
1973
|
+
municipality: string | null;
|
|
1974
|
+
municipalityKind: string | null;
|
|
1975
|
+
lat: number | null;
|
|
1976
|
+
lon: number | null;
|
|
1977
|
+
sym: string | null;
|
|
1978
|
+
citySlug: string | null;
|
|
1979
|
+
type: string | null;
|
|
1980
|
+
typeLabel: string | null;
|
|
1981
|
+
population: number | null;
|
|
1982
|
+
}[];
|
|
1983
|
+
prg: {
|
|
1984
|
+
addressCount: number;
|
|
1985
|
+
streetCount: number;
|
|
1986
|
+
centroidLat: number;
|
|
1987
|
+
centroidLon: number;
|
|
1988
|
+
streets: string[];
|
|
1989
|
+
streetsTruncated?: boolean;
|
|
1990
|
+
} | null;
|
|
1991
|
+
};
|
|
1992
|
+
};
|
|
1993
|
+
};
|
|
1994
|
+
/** @description Invalid query parameters. */
|
|
1995
|
+
400: {
|
|
1996
|
+
headers: {
|
|
1997
|
+
[name: string]: unknown;
|
|
1998
|
+
};
|
|
1999
|
+
content: {
|
|
2000
|
+
"application/json": {
|
|
2001
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2002
|
+
error: string;
|
|
2003
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2004
|
+
message: string;
|
|
2005
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2006
|
+
code: string;
|
|
2007
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2008
|
+
details?: {
|
|
2009
|
+
path?: string;
|
|
2010
|
+
message?: string;
|
|
2011
|
+
}[];
|
|
2012
|
+
};
|
|
2013
|
+
};
|
|
2014
|
+
};
|
|
2015
|
+
/** @description Unknown postal code. */
|
|
2016
|
+
404: {
|
|
2017
|
+
headers: {
|
|
2018
|
+
[name: string]: unknown;
|
|
2019
|
+
};
|
|
2020
|
+
content: {
|
|
2021
|
+
"application/json": {
|
|
2022
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2023
|
+
error: string;
|
|
2024
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2025
|
+
message: string;
|
|
2026
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2027
|
+
code: string;
|
|
2028
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2029
|
+
details?: {
|
|
2030
|
+
path?: string;
|
|
2031
|
+
message?: string;
|
|
2032
|
+
}[];
|
|
2033
|
+
};
|
|
2034
|
+
};
|
|
2035
|
+
};
|
|
2036
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
2037
|
+
429: {
|
|
2038
|
+
headers: {
|
|
2039
|
+
[name: string]: unknown;
|
|
2040
|
+
};
|
|
2041
|
+
content: {
|
|
2042
|
+
"application/json": {
|
|
2043
|
+
statusCode: number;
|
|
2044
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2045
|
+
error: string;
|
|
2046
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2047
|
+
message: string;
|
|
2048
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
2049
|
+
code: string;
|
|
2050
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2051
|
+
details?: {
|
|
2052
|
+
path?: string;
|
|
2053
|
+
message?: string;
|
|
2054
|
+
}[];
|
|
2055
|
+
};
|
|
2056
|
+
};
|
|
2057
|
+
};
|
|
2058
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
2059
|
+
500: {
|
|
2060
|
+
headers: {
|
|
2061
|
+
[name: string]: unknown;
|
|
2062
|
+
};
|
|
2063
|
+
content: {
|
|
2064
|
+
"application/json": {
|
|
2065
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2066
|
+
error: string;
|
|
2067
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2068
|
+
message: string;
|
|
2069
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2070
|
+
code: string;
|
|
2071
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2072
|
+
details?: {
|
|
2073
|
+
path?: string;
|
|
2074
|
+
message?: string;
|
|
2075
|
+
}[];
|
|
2076
|
+
};
|
|
2077
|
+
};
|
|
2078
|
+
};
|
|
2079
|
+
/** @description Postal-code dataset not available (generate data/pna CSV via pnpm fetch:pna). */
|
|
2080
|
+
503: {
|
|
2081
|
+
headers: {
|
|
2082
|
+
[name: string]: unknown;
|
|
2083
|
+
};
|
|
2084
|
+
content: {
|
|
2085
|
+
"application/json": {
|
|
2086
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2087
|
+
error: string;
|
|
2088
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2089
|
+
message: string;
|
|
2090
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2091
|
+
code: string;
|
|
2092
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2093
|
+
details?: {
|
|
2094
|
+
path?: string;
|
|
2095
|
+
message?: string;
|
|
2096
|
+
}[];
|
|
2097
|
+
};
|
|
2098
|
+
};
|
|
2099
|
+
};
|
|
2100
|
+
};
|
|
2101
|
+
};
|
|
2102
|
+
put?: never;
|
|
2103
|
+
post?: never;
|
|
2104
|
+
delete?: never;
|
|
2105
|
+
options?: never;
|
|
2106
|
+
head?: never;
|
|
2107
|
+
patch?: never;
|
|
2108
|
+
trace?: never;
|
|
2109
|
+
};
|
|
2110
|
+
"/v1/geocode": {
|
|
2111
|
+
parameters: {
|
|
2112
|
+
query?: never;
|
|
2113
|
+
header?: never;
|
|
2114
|
+
path?: never;
|
|
2115
|
+
cookie?: never;
|
|
2116
|
+
};
|
|
2117
|
+
/**
|
|
2118
|
+
* Address validation (GUGiK PRG address points, ~8.6M rows)
|
|
2119
|
+
* @description House-number-level validation. Three forms: fielded (street + number + locality SYM → exact building point), structured-by-name (`locality` resolves a locality/city NAME through the locality index — several same-named localities → `locality-ambiguous` with a population-ordered shortlist in `localities[]`, optionally narrowed by `postalCode`), or free-text `address` (one Polish address string, parsed into city/street/number and resolved through the same pipeline; the `query` echo shows the parse). Cityless strings ('ul. Legnicka 61') fall back to resolving the locality from the street itself, verified per candidate locality by the house number: one locality confirms → exact; several → street-ambiguous with locality context in `streets[]`. When the number is unknown but the street exists, nearby numbers are suggested. Requires the PRG dataset on the instance (POST /admin/ingest-prg); otherwise 503.
|
|
2120
|
+
*/
|
|
2121
|
+
get: {
|
|
2122
|
+
parameters: {
|
|
2123
|
+
query?: {
|
|
2124
|
+
/** @description Free-text Polish address ('Wrocław-Fabryczna, ul. Eugeniusza Horbaczewskiego 35'), parsed into locality/street/number internally — locality resolution reuses the exact+fuzzy name-search pipeline, so district strings ('Wrocław-Śródmieście') resolve to the same city. Mutually exclusive with sym, number, street, streetName, locality and postalCode; may only appear with limit. Additive `query` echo reports the parse (`cityResolved` distinguishes a bad split from an unknown address). */
|
|
2125
|
+
address?: string;
|
|
2126
|
+
/** @description Locality SYM (7 digits, from /v1/localities). Required unless `address` or `locality` is given; mutually exclusive with locality. */
|
|
2127
|
+
sym?: string;
|
|
2128
|
+
/** @description Locality/city NAME (diacritics-insensitive) instead of a SYM — resolved through the locality index (exact matches all considered, fuzzy fallback otherwise). Several matches → result 'locality-ambiguous' with a population-ordered shortlist in `localities[]` (capped at 50, `localitiesTruncated` when cut); re-query fielded with sym=. Mutually exclusive with sym and address. */
|
|
2129
|
+
locality?: string;
|
|
2130
|
+
/** @description Optional narrowing hint for the locality mode: only localities the code officially serves (its PRG locality set, else the PNA name set) stay candidates — a code contradicting every name match answers result 'none'. Requires locality. */
|
|
2131
|
+
postalCode?: string;
|
|
2132
|
+
/** @description House number ('21A'). Required unless `address` is given. */
|
|
2133
|
+
number?: string;
|
|
2134
|
+
/** @description Street SYM_UL (5 digits, from /v1/streets). Omit for rural 'locality + number' addresses. */
|
|
2135
|
+
street?: string;
|
|
2136
|
+
/** @description Street name prefix (diacritics-insensitive; 'rynek' finds 'ul. Rynek'), resolved via the ULIC registry. Mutually exclusive with street; several matches → result 'street-ambiguous' with candidates. */
|
|
2137
|
+
streetName?: string;
|
|
2138
|
+
/** @description Maximum matches (1–50). */
|
|
2139
|
+
limit?: number;
|
|
2140
|
+
/** @description 'geojson' answers an RFC 7946 FeatureCollection (every match a Feature) instead of the JSON envelope. */
|
|
2141
|
+
format?: "json" | "geojson";
|
|
2142
|
+
};
|
|
2143
|
+
header?: never;
|
|
2144
|
+
path?: never;
|
|
2145
|
+
cookie?: never;
|
|
2146
|
+
};
|
|
2147
|
+
requestBody?: never;
|
|
2148
|
+
responses: {
|
|
2149
|
+
/** @description Resolution result — 'exact' (building points), 'street' (number unknown, suggestions provided), 'street-ambiguous' (streetName matched several streets), 'locality-ambiguous' (the locality name matched several localities; shortlist in `localities[]`) or 'none'. Address- and locality-mode responses carry the `query` echo (cityResolved records whether the locality token resolved). */
|
|
2150
|
+
200: {
|
|
2151
|
+
headers: {
|
|
2152
|
+
[name: string]: unknown;
|
|
2153
|
+
};
|
|
2154
|
+
content: {
|
|
2155
|
+
"application/json": {
|
|
2156
|
+
/** @enum {string} */
|
|
2157
|
+
result: "exact" | "street" | "street-ambiguous" | "locality-ambiguous" | "none";
|
|
2158
|
+
matches: {
|
|
2159
|
+
lat: number;
|
|
2160
|
+
lon: number;
|
|
2161
|
+
number: string;
|
|
2162
|
+
streetId: string | null;
|
|
2163
|
+
postalCode: string | null;
|
|
2164
|
+
}[];
|
|
2165
|
+
query?: {
|
|
2166
|
+
city: string | null;
|
|
2167
|
+
street: string | null;
|
|
2168
|
+
number: string | null;
|
|
2169
|
+
numbers?: string[];
|
|
2170
|
+
range?: boolean;
|
|
2171
|
+
cityResolved: boolean;
|
|
2172
|
+
};
|
|
2173
|
+
nearestNumbers?: {
|
|
2174
|
+
number: string;
|
|
2175
|
+
distance: number;
|
|
2176
|
+
}[];
|
|
2177
|
+
baseNumberMatch?: {
|
|
2178
|
+
number: string;
|
|
2179
|
+
lat: number;
|
|
2180
|
+
lon: number;
|
|
2181
|
+
postalCode: string | null;
|
|
2182
|
+
};
|
|
2183
|
+
streets?: {
|
|
2184
|
+
id: string;
|
|
2185
|
+
name: string;
|
|
2186
|
+
sym?: string;
|
|
2187
|
+
city?: string;
|
|
2188
|
+
provinceCode?: string | null;
|
|
2189
|
+
}[];
|
|
2190
|
+
localities?: {
|
|
2191
|
+
sym: string;
|
|
2192
|
+
name: string;
|
|
2193
|
+
type: string | null;
|
|
2194
|
+
typeLabel: string | null;
|
|
2195
|
+
province: string | null;
|
|
2196
|
+
county: string | null;
|
|
2197
|
+
municipality: string | null;
|
|
2198
|
+
provinceCode: string | null;
|
|
2199
|
+
countyCode: string | null;
|
|
2200
|
+
municipalityCode: string | null;
|
|
2201
|
+
population: number | null;
|
|
2202
|
+
}[];
|
|
2203
|
+
localitiesTruncated?: boolean;
|
|
2204
|
+
};
|
|
2205
|
+
/** @description The same answer as an RFC 7946 FeatureCollection: every match a Feature (lat/lon in the geometry), `result` and the other top-level fields as foreign members. */
|
|
2206
|
+
"application/geo+json": Record<string, never>;
|
|
2207
|
+
};
|
|
2208
|
+
};
|
|
2209
|
+
/** @description Invalid query parameters. */
|
|
2210
|
+
400: {
|
|
2211
|
+
headers: {
|
|
2212
|
+
[name: string]: unknown;
|
|
2213
|
+
};
|
|
2214
|
+
content: {
|
|
2215
|
+
"application/json": {
|
|
2216
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2217
|
+
error: string;
|
|
2218
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2219
|
+
message: string;
|
|
2220
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2221
|
+
code: string;
|
|
2222
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2223
|
+
details?: {
|
|
2224
|
+
path?: string;
|
|
2225
|
+
message?: string;
|
|
2226
|
+
}[];
|
|
2227
|
+
};
|
|
2228
|
+
};
|
|
2229
|
+
};
|
|
2230
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
2231
|
+
429: {
|
|
2232
|
+
headers: {
|
|
2233
|
+
[name: string]: unknown;
|
|
2234
|
+
};
|
|
2235
|
+
content: {
|
|
2236
|
+
"application/json": {
|
|
2237
|
+
statusCode: number;
|
|
2238
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2239
|
+
error: string;
|
|
2240
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2241
|
+
message: string;
|
|
2242
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
2243
|
+
code: string;
|
|
2244
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2245
|
+
details?: {
|
|
2246
|
+
path?: string;
|
|
2247
|
+
message?: string;
|
|
2248
|
+
}[];
|
|
2249
|
+
};
|
|
2250
|
+
};
|
|
2251
|
+
};
|
|
2252
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
2253
|
+
500: {
|
|
2254
|
+
headers: {
|
|
2255
|
+
[name: string]: unknown;
|
|
2256
|
+
};
|
|
2257
|
+
content: {
|
|
2258
|
+
"application/json": {
|
|
2259
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2260
|
+
error: string;
|
|
2261
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2262
|
+
message: string;
|
|
2263
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2264
|
+
code: string;
|
|
2265
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2266
|
+
details?: {
|
|
2267
|
+
path?: string;
|
|
2268
|
+
message?: string;
|
|
2269
|
+
}[];
|
|
2270
|
+
};
|
|
2271
|
+
};
|
|
2272
|
+
};
|
|
2273
|
+
/** @description Address dataset not available (POST /admin/ingest-prg). */
|
|
2274
|
+
503: {
|
|
2275
|
+
headers: {
|
|
2276
|
+
[name: string]: unknown;
|
|
2277
|
+
};
|
|
2278
|
+
content: {
|
|
2279
|
+
"application/json": {
|
|
2280
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2281
|
+
error: string;
|
|
2282
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2283
|
+
message: string;
|
|
2284
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2285
|
+
code: string;
|
|
2286
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2287
|
+
details?: {
|
|
2288
|
+
path?: string;
|
|
2289
|
+
message?: string;
|
|
2290
|
+
}[];
|
|
2291
|
+
};
|
|
2292
|
+
};
|
|
2293
|
+
};
|
|
2294
|
+
};
|
|
2295
|
+
};
|
|
2296
|
+
put?: never;
|
|
2297
|
+
post?: never;
|
|
2298
|
+
delete?: never;
|
|
2299
|
+
options?: never;
|
|
2300
|
+
head?: never;
|
|
2301
|
+
patch?: never;
|
|
2302
|
+
trace?: never;
|
|
2303
|
+
};
|
|
2304
|
+
"/v1/validate": {
|
|
2305
|
+
parameters: {
|
|
2306
|
+
query?: never;
|
|
2307
|
+
header?: never;
|
|
2308
|
+
path?: never;
|
|
2309
|
+
cookie?: never;
|
|
2310
|
+
};
|
|
2311
|
+
/**
|
|
2312
|
+
* Address validation workflow — structured fields, match kinds, verdict and issues
|
|
2313
|
+
* @description The composite answer to a written address: the STRUCTURED fields (locality, street, house number, unit, postal code, coordinates) with their registry identifiers, HOW WELL each field matched (`exact` / `normalized` / `partial` / `ambiguous` / `not-found`), a VERDICT (`valid` / `corrected` / `ambiguous` / `incomplete` / `invalid`) and the ISSUES that explain every discrepancy — so a consumer can accept, correct, or fall back to a manual entry. The three input forms mirror GET /v1/geocode (fielded `sym`, structured-by-name `locality`, free-text `address`), with one difference: `number` is OPTIONAL here — a missing house number is an INCOMPLETE address, not a malformed request. The building-point verdict comes from the same pipeline GET /v1/geocode runs, so the two endpoints can never disagree about whether a building exists. Two rules the endpoint never breaks: a postal code is only ever the matched building point's own code (never inferred from a locality or a proximity), and a component the registries do not carry stays null and says so. Requires the PRG dataset on the instance (POST /admin/ingest-prg); otherwise 503.
|
|
2314
|
+
*/
|
|
2315
|
+
get: {
|
|
2316
|
+
parameters: {
|
|
2317
|
+
query?: {
|
|
2318
|
+
/** @description Free-text Polish address ('Wrocław-Fabryczna, ul. Eugeniusza Horbaczewskiego 35'), parsed into locality/street/number internally and resolved through the same pipeline as GET /v1/geocode. Mutually exclusive with sym, number, street, streetName, locality and postalCode. */
|
|
2319
|
+
address?: string;
|
|
2320
|
+
/** @description Locality SYM (7 digits, from /v1/localities). Required unless `address` or `locality` is given; mutually exclusive with locality. An unknown SYM answers 404. */
|
|
2321
|
+
sym?: string;
|
|
2322
|
+
/** @description Locality/city NAME (diacritics-insensitive) instead of a SYM — resolved through the locality index. Several matches → verdict 'ambiguous' with a population-ordered shortlist in `candidates.localities` (capped at 50, `localitiesTruncated` when cut). Mutually exclusive with sym and address. */
|
|
2323
|
+
locality?: string;
|
|
2324
|
+
/** @description The caller's claim about the postal code. With `locality` it also narrows the candidates (the code's officially served localities); in every form it is VERIFIED against the matched building point's own code — a disagreement is reported as the `postal_code_mismatch` issue and the register's code is returned. Requires sym or locality. */
|
|
2325
|
+
postalCode?: string;
|
|
2326
|
+
/** @description House number ('21A'). OPTIONAL here (unlike GET /v1/geocode): a missing number makes the address INCOMPLETE, and the response says so instead of rejecting the request. */
|
|
2327
|
+
number?: string;
|
|
2328
|
+
/** @description Street SYM_UL (5 digits, from /v1/streets). Mutually exclusive with streetName. */
|
|
2329
|
+
street?: string;
|
|
2330
|
+
/** @description Street name prefix (diacritics-insensitive; 'rynek' finds 'ul. Rynek'). A typed 'ul.'/'al.' prefix is stripped before the search and kept as the claimed street type. Several matches → verdict 'ambiguous' with candidates in `candidates.streets`. */
|
|
2331
|
+
streetName?: string;
|
|
2332
|
+
/** @description Maximum matches (1–50). */
|
|
2333
|
+
limit?: number;
|
|
2334
|
+
};
|
|
2335
|
+
header?: never;
|
|
2336
|
+
path?: never;
|
|
2337
|
+
cookie?: never;
|
|
2338
|
+
};
|
|
2339
|
+
requestBody?: never;
|
|
2340
|
+
responses: {
|
|
2341
|
+
/** @description The validation answer: `verdict` (valid | corrected | ambiguous | incomplete | invalid), the structured `address`, the per-field `match` kinds, the `issues` that explain every discrepancy, the `candidates` for an unresolved ambiguity, and `sources` (which dataset each field came from). */
|
|
2342
|
+
200: {
|
|
2343
|
+
headers: {
|
|
2344
|
+
[name: string]: unknown;
|
|
2345
|
+
};
|
|
2346
|
+
content: {
|
|
2347
|
+
"application/json": {
|
|
2348
|
+
/** @enum {string} */
|
|
2349
|
+
verdict: "valid" | "corrected" | "ambiguous" | "incomplete" | "invalid";
|
|
2350
|
+
address: {
|
|
2351
|
+
locality: {
|
|
2352
|
+
sym: string;
|
|
2353
|
+
name: string;
|
|
2354
|
+
type: string | null;
|
|
2355
|
+
typeLabel: string | null;
|
|
2356
|
+
province: string | null;
|
|
2357
|
+
county: string | null;
|
|
2358
|
+
municipality: string | null;
|
|
2359
|
+
provinceCode: string | null;
|
|
2360
|
+
countyCode: string | null;
|
|
2361
|
+
municipalityCode: string | null;
|
|
2362
|
+
lat: number | null;
|
|
2363
|
+
lon: number | null;
|
|
2364
|
+
coordSource: string | null;
|
|
2365
|
+
population: number | null;
|
|
2366
|
+
populationSource: string | null;
|
|
2367
|
+
} | null;
|
|
2368
|
+
street: {
|
|
2369
|
+
id: string;
|
|
2370
|
+
name: string;
|
|
2371
|
+
cecha: string | null;
|
|
2372
|
+
} | null;
|
|
2373
|
+
houseNumber: string | null;
|
|
2374
|
+
unit: string | null;
|
|
2375
|
+
postalCode: string | null;
|
|
2376
|
+
lat: number | null;
|
|
2377
|
+
lon: number | null;
|
|
2378
|
+
};
|
|
2379
|
+
match: {
|
|
2380
|
+
/** @enum {string} */
|
|
2381
|
+
locality: "exact" | "normalized" | "partial" | "ambiguous" | "not-found";
|
|
2382
|
+
/** @enum {string} */
|
|
2383
|
+
street: "exact" | "normalized" | "partial" | "ambiguous" | "not-found";
|
|
2384
|
+
/** @enum {string} */
|
|
2385
|
+
houseNumber: "exact" | "normalized" | "partial" | "ambiguous" | "not-found";
|
|
2386
|
+
/** @enum {string} */
|
|
2387
|
+
postalCode: "exact" | "normalized" | "partial" | "ambiguous" | "not-found";
|
|
2388
|
+
};
|
|
2389
|
+
issues: {
|
|
2390
|
+
code: string;
|
|
2391
|
+
field: string | null;
|
|
2392
|
+
message: string;
|
|
2393
|
+
expected?: string | null;
|
|
2394
|
+
actual?: string | null;
|
|
2395
|
+
}[];
|
|
2396
|
+
candidates?: {
|
|
2397
|
+
localities?: {
|
|
2398
|
+
sym: string;
|
|
2399
|
+
name: string;
|
|
2400
|
+
type: string | null;
|
|
2401
|
+
typeLabel: string | null;
|
|
2402
|
+
province: string | null;
|
|
2403
|
+
county: string | null;
|
|
2404
|
+
municipality: string | null;
|
|
2405
|
+
provinceCode: string | null;
|
|
2406
|
+
countyCode: string | null;
|
|
2407
|
+
municipalityCode: string | null;
|
|
2408
|
+
population: number | null;
|
|
2409
|
+
}[];
|
|
2410
|
+
streets?: {
|
|
2411
|
+
id: string;
|
|
2412
|
+
name: string;
|
|
2413
|
+
}[];
|
|
2414
|
+
nearestNumbers?: {
|
|
2415
|
+
number: string;
|
|
2416
|
+
distance: number;
|
|
2417
|
+
}[];
|
|
2418
|
+
localitiesTruncated?: boolean;
|
|
2419
|
+
};
|
|
2420
|
+
sources: {
|
|
2421
|
+
locality: string | null;
|
|
2422
|
+
street: string | null;
|
|
2423
|
+
addressPoint: string | null;
|
|
2424
|
+
postalCode: string | null;
|
|
2425
|
+
};
|
|
2426
|
+
query?: {
|
|
2427
|
+
city: string | null;
|
|
2428
|
+
street: string | null;
|
|
2429
|
+
number: string | null;
|
|
2430
|
+
numbers?: string[];
|
|
2431
|
+
range?: boolean;
|
|
2432
|
+
cityResolved: boolean;
|
|
2433
|
+
};
|
|
2434
|
+
};
|
|
2435
|
+
};
|
|
2436
|
+
};
|
|
2437
|
+
/** @description Invalid query parameters. */
|
|
2438
|
+
400: {
|
|
2439
|
+
headers: {
|
|
2440
|
+
[name: string]: unknown;
|
|
2441
|
+
};
|
|
2442
|
+
content: {
|
|
2443
|
+
"application/json": {
|
|
2444
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2445
|
+
error: string;
|
|
2446
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2447
|
+
message: string;
|
|
2448
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2449
|
+
code: string;
|
|
2450
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2451
|
+
details?: {
|
|
2452
|
+
path?: string;
|
|
2453
|
+
message?: string;
|
|
2454
|
+
}[];
|
|
2455
|
+
};
|
|
2456
|
+
};
|
|
2457
|
+
};
|
|
2458
|
+
/** @description Unknown locality SYM. */
|
|
2459
|
+
404: {
|
|
2460
|
+
headers: {
|
|
2461
|
+
[name: string]: unknown;
|
|
2462
|
+
};
|
|
2463
|
+
content: {
|
|
2464
|
+
"application/json": {
|
|
2465
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2466
|
+
error: string;
|
|
2467
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2468
|
+
message: string;
|
|
2469
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2470
|
+
code: string;
|
|
2471
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2472
|
+
details?: {
|
|
2473
|
+
path?: string;
|
|
2474
|
+
message?: string;
|
|
2475
|
+
}[];
|
|
2476
|
+
};
|
|
2477
|
+
};
|
|
2478
|
+
};
|
|
2479
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
2480
|
+
429: {
|
|
2481
|
+
headers: {
|
|
2482
|
+
[name: string]: unknown;
|
|
2483
|
+
};
|
|
2484
|
+
content: {
|
|
2485
|
+
"application/json": {
|
|
2486
|
+
statusCode: number;
|
|
2487
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2488
|
+
error: string;
|
|
2489
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2490
|
+
message: string;
|
|
2491
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
2492
|
+
code: string;
|
|
2493
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2494
|
+
details?: {
|
|
2495
|
+
path?: string;
|
|
2496
|
+
message?: string;
|
|
2497
|
+
}[];
|
|
2498
|
+
};
|
|
2499
|
+
};
|
|
2500
|
+
};
|
|
2501
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
2502
|
+
500: {
|
|
2503
|
+
headers: {
|
|
2504
|
+
[name: string]: unknown;
|
|
2505
|
+
};
|
|
2506
|
+
content: {
|
|
2507
|
+
"application/json": {
|
|
2508
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2509
|
+
error: string;
|
|
2510
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2511
|
+
message: string;
|
|
2512
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2513
|
+
code: string;
|
|
2514
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2515
|
+
details?: {
|
|
2516
|
+
path?: string;
|
|
2517
|
+
message?: string;
|
|
2518
|
+
}[];
|
|
2519
|
+
};
|
|
2520
|
+
};
|
|
2521
|
+
};
|
|
2522
|
+
/** @description Address dataset not available (POST /admin/ingest-prg). */
|
|
2523
|
+
503: {
|
|
2524
|
+
headers: {
|
|
2525
|
+
[name: string]: unknown;
|
|
2526
|
+
};
|
|
2527
|
+
content: {
|
|
2528
|
+
"application/json": {
|
|
2529
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2530
|
+
error: string;
|
|
2531
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2532
|
+
message: string;
|
|
2533
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2534
|
+
code: string;
|
|
2535
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2536
|
+
details?: {
|
|
2537
|
+
path?: string;
|
|
2538
|
+
message?: string;
|
|
2539
|
+
}[];
|
|
2540
|
+
};
|
|
2541
|
+
};
|
|
2542
|
+
};
|
|
2543
|
+
};
|
|
2544
|
+
};
|
|
2545
|
+
put?: never;
|
|
2546
|
+
post?: never;
|
|
2547
|
+
delete?: never;
|
|
2548
|
+
options?: never;
|
|
2549
|
+
head?: never;
|
|
2550
|
+
patch?: never;
|
|
2551
|
+
trace?: never;
|
|
2552
|
+
};
|
|
2553
|
+
"/v1/bulk/addresses": {
|
|
2554
|
+
parameters: {
|
|
2555
|
+
query?: never;
|
|
2556
|
+
header?: never;
|
|
2557
|
+
path?: never;
|
|
2558
|
+
cookie?: never;
|
|
2559
|
+
};
|
|
2560
|
+
get?: never;
|
|
2561
|
+
put?: never;
|
|
2562
|
+
/**
|
|
2563
|
+
* Bulk address normalisation — upload a CSV, get the result file back
|
|
2564
|
+
* @description Uploads a CSV of addresses for normalisation and returns a JOB (202): the file is processed in the background, row by row, through the same validation pipeline GET /v1/validate runs. The body is the raw CSV (`Content-Type: text/csv`); the columns are named by the caller through the query parameters — the service never guesses which column is the street. A named API key is REQUIRED (401 without one): the job stores the customer's personal data on the instance for the retention window and costs real work per row. Re-uploading the same file (or the same Idempotency-Key) returns the EXISTING job instead of processing and billing it twice. The result file carries the customer's ORIGINAL columns verbatim plus the service's columns beside them: the confirmed locality, street, house number, postal code and coordinates, the per-field match kinds, and the reasons the rows that were not confirmed were not confirmed. A value that was not confirmed is left EMPTY rather than guessed. The upload and its result are deleted when the retention window ends (24 hours by default), and the job answers 410 Gone from then on.
|
|
2565
|
+
*/
|
|
2566
|
+
post: {
|
|
2567
|
+
parameters: {
|
|
2568
|
+
query?: {
|
|
2569
|
+
/** @description The column holding the locality — a name or a 7-digit SYM. Required unless `address` is given. */
|
|
2570
|
+
locality?: string;
|
|
2571
|
+
/** @description The column holding the street — a name or a 5-digit SYM_UL. */
|
|
2572
|
+
street?: string;
|
|
2573
|
+
/** @description The column holding the house number. */
|
|
2574
|
+
number?: string;
|
|
2575
|
+
/** @description The column holding the postal code — it also narrows an ambiguous locality name. */
|
|
2576
|
+
postalCode?: string;
|
|
2577
|
+
/** @description The column holding the WHOLE address (one free-text field) — the alternative to the four separate columns. */
|
|
2578
|
+
address?: string;
|
|
2579
|
+
/** @description The column identifying the row (echoed into the result). */
|
|
2580
|
+
id?: string;
|
|
2581
|
+
};
|
|
2582
|
+
header?: never;
|
|
2583
|
+
path?: never;
|
|
2584
|
+
cookie?: never;
|
|
2585
|
+
};
|
|
2586
|
+
/** @description The CSV file itself, as the raw request body. UTF-8 (a BOM is fine), `,`/`;`/tab delimited, one header row. */
|
|
2587
|
+
requestBody: {
|
|
2588
|
+
content: {
|
|
2589
|
+
"text/csv": string;
|
|
2590
|
+
};
|
|
2591
|
+
};
|
|
2592
|
+
responses: {
|
|
2593
|
+
/** @description The same file was uploaded before: the EXISTING job is returned (`duplicate: true`) — the file is not processed or billed twice. */
|
|
2594
|
+
200: {
|
|
2595
|
+
headers: {
|
|
2596
|
+
[name: string]: unknown;
|
|
2597
|
+
};
|
|
2598
|
+
content: {
|
|
2599
|
+
"application/json": Record<string, never>;
|
|
2600
|
+
};
|
|
2601
|
+
};
|
|
2602
|
+
/** @description The job was accepted: `{ id, status, rows, processed, matched, ambiguous, invalid, unmatched, resultUrl }`. Poll GET /v1/bulk/jobs/{id} for progress and GET /v1/bulk/jobs/{id}/result.csv for the result. */
|
|
2603
|
+
202: {
|
|
2604
|
+
headers: {
|
|
2605
|
+
[name: string]: unknown;
|
|
2606
|
+
};
|
|
2607
|
+
content: {
|
|
2608
|
+
"application/json": Record<string, never>;
|
|
2609
|
+
};
|
|
2610
|
+
};
|
|
2611
|
+
/** @description Invalid query parameters. */
|
|
2612
|
+
400: {
|
|
2613
|
+
headers: {
|
|
2614
|
+
[name: string]: unknown;
|
|
2615
|
+
};
|
|
2616
|
+
content: {
|
|
2617
|
+
"application/json": {
|
|
2618
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2619
|
+
error: string;
|
|
2620
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2621
|
+
message: string;
|
|
2622
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2623
|
+
code: string;
|
|
2624
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2625
|
+
details?: {
|
|
2626
|
+
path?: string;
|
|
2627
|
+
message?: string;
|
|
2628
|
+
}[];
|
|
2629
|
+
};
|
|
2630
|
+
};
|
|
2631
|
+
};
|
|
2632
|
+
/** @description A named API key is required for bulk processing. */
|
|
2633
|
+
401: {
|
|
2634
|
+
headers: {
|
|
2635
|
+
[name: string]: unknown;
|
|
2636
|
+
};
|
|
2637
|
+
content: {
|
|
2638
|
+
"application/json": Record<string, never>;
|
|
2639
|
+
};
|
|
2640
|
+
};
|
|
2641
|
+
/** @description The file has more rows than the configured limit. */
|
|
2642
|
+
413: {
|
|
2643
|
+
headers: {
|
|
2644
|
+
[name: string]: unknown;
|
|
2645
|
+
};
|
|
2646
|
+
content: {
|
|
2647
|
+
"application/json": Record<string, never>;
|
|
2648
|
+
};
|
|
2649
|
+
};
|
|
2650
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
2651
|
+
429: {
|
|
2652
|
+
headers: {
|
|
2653
|
+
[name: string]: unknown;
|
|
2654
|
+
};
|
|
2655
|
+
content: {
|
|
2656
|
+
"application/json": {
|
|
2657
|
+
statusCode: number;
|
|
2658
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2659
|
+
error: string;
|
|
2660
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2661
|
+
message: string;
|
|
2662
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
2663
|
+
code: string;
|
|
2664
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2665
|
+
details?: {
|
|
2666
|
+
path?: string;
|
|
2667
|
+
message?: string;
|
|
2668
|
+
}[];
|
|
2669
|
+
};
|
|
2670
|
+
};
|
|
2671
|
+
};
|
|
2672
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
2673
|
+
500: {
|
|
2674
|
+
headers: {
|
|
2675
|
+
[name: string]: unknown;
|
|
2676
|
+
};
|
|
2677
|
+
content: {
|
|
2678
|
+
"application/json": {
|
|
2679
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2680
|
+
error: string;
|
|
2681
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2682
|
+
message: string;
|
|
2683
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
2684
|
+
code: string;
|
|
2685
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2686
|
+
details?: {
|
|
2687
|
+
path?: string;
|
|
2688
|
+
message?: string;
|
|
2689
|
+
}[];
|
|
2690
|
+
};
|
|
2691
|
+
};
|
|
2692
|
+
};
|
|
2693
|
+
};
|
|
2694
|
+
};
|
|
2695
|
+
delete?: never;
|
|
2696
|
+
options?: never;
|
|
2697
|
+
head?: never;
|
|
2698
|
+
patch?: never;
|
|
2699
|
+
trace?: never;
|
|
2700
|
+
};
|
|
2701
|
+
"/v1/bulk/jobs": {
|
|
2702
|
+
parameters: {
|
|
2703
|
+
query?: never;
|
|
2704
|
+
header?: never;
|
|
2705
|
+
path?: never;
|
|
2706
|
+
cookie?: never;
|
|
2707
|
+
};
|
|
2708
|
+
/**
|
|
2709
|
+
* The caller's bulk jobs
|
|
2710
|
+
* @description The caller's own bulk jobs, newest first. A job belongs to the key that created it — one customer never sees another's upload.
|
|
2711
|
+
*/
|
|
2712
|
+
get: {
|
|
2713
|
+
parameters: {
|
|
2714
|
+
query?: never;
|
|
2715
|
+
header?: never;
|
|
2716
|
+
path?: never;
|
|
2717
|
+
cookie?: never;
|
|
2718
|
+
};
|
|
2719
|
+
requestBody?: never;
|
|
2720
|
+
responses: {
|
|
2721
|
+
/** @description The caller's jobs. */
|
|
2722
|
+
200: {
|
|
2723
|
+
headers: {
|
|
2724
|
+
[name: string]: unknown;
|
|
2725
|
+
};
|
|
2726
|
+
content: {
|
|
2727
|
+
"application/json": Record<string, never>;
|
|
2728
|
+
};
|
|
2729
|
+
};
|
|
2730
|
+
/** @description A named API key is required. */
|
|
2731
|
+
401: {
|
|
2732
|
+
headers: {
|
|
2733
|
+
[name: string]: unknown;
|
|
2734
|
+
};
|
|
2735
|
+
content: {
|
|
2736
|
+
"application/json": Record<string, never>;
|
|
2737
|
+
};
|
|
2738
|
+
};
|
|
2739
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
2740
|
+
429: {
|
|
2741
|
+
headers: {
|
|
2742
|
+
[name: string]: unknown;
|
|
2743
|
+
};
|
|
2744
|
+
content: {
|
|
2745
|
+
"application/json": {
|
|
2746
|
+
statusCode: number;
|
|
2747
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2748
|
+
error: string;
|
|
2749
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2750
|
+
message: string;
|
|
2751
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
2752
|
+
code: string;
|
|
2753
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2754
|
+
details?: {
|
|
2755
|
+
path?: string;
|
|
2756
|
+
message?: string;
|
|
2757
|
+
}[];
|
|
2758
|
+
};
|
|
2759
|
+
};
|
|
2760
|
+
};
|
|
2761
|
+
};
|
|
2762
|
+
};
|
|
2763
|
+
put?: never;
|
|
2764
|
+
post?: never;
|
|
2765
|
+
delete?: never;
|
|
2766
|
+
options?: never;
|
|
2767
|
+
head?: never;
|
|
2768
|
+
patch?: never;
|
|
2769
|
+
trace?: never;
|
|
2770
|
+
};
|
|
2771
|
+
"/v1/bulk/jobs/{id}": {
|
|
2772
|
+
parameters: {
|
|
2773
|
+
query?: never;
|
|
2774
|
+
header?: never;
|
|
2775
|
+
path?: never;
|
|
2776
|
+
cookie?: never;
|
|
2777
|
+
};
|
|
2778
|
+
/**
|
|
2779
|
+
* One bulk job's state
|
|
2780
|
+
* @description The job's status and progress: `queued` | `running` | `done` | `failed` | `expired`, the row count, how many rows were processed and how they split (matched / ambiguous / invalid / unmatched), and the failure reason when the job failed. 410 Gone once the retention window has ended — the job existed, and its files are gone.
|
|
2781
|
+
*/
|
|
2782
|
+
get: {
|
|
2783
|
+
parameters: {
|
|
2784
|
+
query?: never;
|
|
2785
|
+
header?: never;
|
|
2786
|
+
path: {
|
|
2787
|
+
/** @description The job id. */
|
|
2788
|
+
id: string;
|
|
2789
|
+
};
|
|
2790
|
+
cookie?: never;
|
|
2791
|
+
};
|
|
2792
|
+
requestBody?: never;
|
|
2793
|
+
responses: {
|
|
2794
|
+
/** @description The job's state. */
|
|
2795
|
+
200: {
|
|
2796
|
+
headers: {
|
|
2797
|
+
[name: string]: unknown;
|
|
2798
|
+
};
|
|
2799
|
+
content: {
|
|
2800
|
+
"application/json": Record<string, never>;
|
|
2801
|
+
};
|
|
2802
|
+
};
|
|
2803
|
+
/** @description A named API key is required. */
|
|
2804
|
+
401: {
|
|
2805
|
+
headers: {
|
|
2806
|
+
[name: string]: unknown;
|
|
2807
|
+
};
|
|
2808
|
+
content: {
|
|
2809
|
+
"application/json": Record<string, never>;
|
|
2810
|
+
};
|
|
2811
|
+
};
|
|
2812
|
+
/** @description No such job (for this key). */
|
|
2813
|
+
404: {
|
|
2814
|
+
headers: {
|
|
2815
|
+
[name: string]: unknown;
|
|
2816
|
+
};
|
|
2817
|
+
content: {
|
|
2818
|
+
"application/json": Record<string, never>;
|
|
2819
|
+
};
|
|
2820
|
+
};
|
|
2821
|
+
/** @description The job's files were deleted when the retention window ended. */
|
|
2822
|
+
410: {
|
|
2823
|
+
headers: {
|
|
2824
|
+
[name: string]: unknown;
|
|
2825
|
+
};
|
|
2826
|
+
content: {
|
|
2827
|
+
"application/json": Record<string, never>;
|
|
2828
|
+
};
|
|
2829
|
+
};
|
|
2830
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
2831
|
+
429: {
|
|
2832
|
+
headers: {
|
|
2833
|
+
[name: string]: unknown;
|
|
2834
|
+
};
|
|
2835
|
+
content: {
|
|
2836
|
+
"application/json": {
|
|
2837
|
+
statusCode: number;
|
|
2838
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2839
|
+
error: string;
|
|
2840
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2841
|
+
message: string;
|
|
2842
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
2843
|
+
code: string;
|
|
2844
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2845
|
+
details?: {
|
|
2846
|
+
path?: string;
|
|
2847
|
+
message?: string;
|
|
2848
|
+
}[];
|
|
2849
|
+
};
|
|
2850
|
+
};
|
|
2851
|
+
};
|
|
2852
|
+
};
|
|
2853
|
+
};
|
|
2854
|
+
put?: never;
|
|
2855
|
+
post?: never;
|
|
2856
|
+
delete?: never;
|
|
2857
|
+
options?: never;
|
|
2858
|
+
head?: never;
|
|
2859
|
+
patch?: never;
|
|
2860
|
+
trace?: never;
|
|
2861
|
+
};
|
|
2862
|
+
"/v1/bulk/jobs/{id}/result.csv": {
|
|
2863
|
+
parameters: {
|
|
2864
|
+
query?: never;
|
|
2865
|
+
header?: never;
|
|
2866
|
+
path?: never;
|
|
2867
|
+
cookie?: never;
|
|
2868
|
+
};
|
|
2869
|
+
/**
|
|
2870
|
+
* The job's result file
|
|
2871
|
+
* @description The result CSV: the customer's ORIGINAL columns, verbatim, plus the service's columns beside them — the confirmed locality, street, house number, unit, postal code and coordinates, the per-field match kinds, the row's verdict, and the reasons the rows that were not confirmed were not confirmed. A value the register did not confirm is EMPTY, never a guess. The file is UTF-8 with a BOM, so Excel opens the accented Polish names correctly.
|
|
2872
|
+
*/
|
|
2873
|
+
get: {
|
|
2874
|
+
parameters: {
|
|
2875
|
+
query?: never;
|
|
2876
|
+
header?: never;
|
|
2877
|
+
path: {
|
|
2878
|
+
/** @description The job id. */
|
|
2879
|
+
id: string;
|
|
2880
|
+
};
|
|
2881
|
+
cookie?: never;
|
|
2882
|
+
};
|
|
2883
|
+
requestBody?: never;
|
|
2884
|
+
responses: {
|
|
2885
|
+
/** @description The result file. */
|
|
2886
|
+
200: {
|
|
2887
|
+
headers: {
|
|
2888
|
+
[name: string]: unknown;
|
|
2889
|
+
};
|
|
2890
|
+
content: {
|
|
2891
|
+
"text/csv": string;
|
|
2892
|
+
};
|
|
2893
|
+
};
|
|
2894
|
+
/** @description A named API key is required. */
|
|
2895
|
+
401: {
|
|
2896
|
+
headers: {
|
|
2897
|
+
[name: string]: unknown;
|
|
2898
|
+
};
|
|
2899
|
+
content: {
|
|
2900
|
+
"application/json": Record<string, never>;
|
|
2901
|
+
};
|
|
2902
|
+
};
|
|
2903
|
+
/** @description No such job (for this key). */
|
|
2904
|
+
404: {
|
|
2905
|
+
headers: {
|
|
2906
|
+
[name: string]: unknown;
|
|
2907
|
+
};
|
|
2908
|
+
content: {
|
|
2909
|
+
"application/json": Record<string, never>;
|
|
2910
|
+
};
|
|
2911
|
+
};
|
|
2912
|
+
/** @description The job has not finished yet. */
|
|
2913
|
+
409: {
|
|
2914
|
+
headers: {
|
|
2915
|
+
[name: string]: unknown;
|
|
2916
|
+
};
|
|
2917
|
+
content: {
|
|
2918
|
+
"application/json": Record<string, never>;
|
|
2919
|
+
};
|
|
2920
|
+
};
|
|
2921
|
+
/** @description The job's files were deleted when the retention window ended. */
|
|
2922
|
+
410: {
|
|
2923
|
+
headers: {
|
|
2924
|
+
[name: string]: unknown;
|
|
2925
|
+
};
|
|
2926
|
+
content: {
|
|
2927
|
+
"application/json": Record<string, never>;
|
|
2928
|
+
};
|
|
2929
|
+
};
|
|
2930
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
2931
|
+
429: {
|
|
2932
|
+
headers: {
|
|
2933
|
+
[name: string]: unknown;
|
|
2934
|
+
};
|
|
2935
|
+
content: {
|
|
2936
|
+
"application/json": {
|
|
2937
|
+
statusCode: number;
|
|
2938
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
2939
|
+
error: string;
|
|
2940
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
2941
|
+
message: string;
|
|
2942
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
2943
|
+
code: string;
|
|
2944
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
2945
|
+
details?: {
|
|
2946
|
+
path?: string;
|
|
2947
|
+
message?: string;
|
|
2948
|
+
}[];
|
|
2949
|
+
};
|
|
2950
|
+
};
|
|
2951
|
+
};
|
|
2952
|
+
};
|
|
2953
|
+
};
|
|
2954
|
+
put?: never;
|
|
2955
|
+
post?: never;
|
|
2956
|
+
delete?: never;
|
|
2957
|
+
options?: never;
|
|
2958
|
+
head?: never;
|
|
2959
|
+
patch?: never;
|
|
2960
|
+
trace?: never;
|
|
2961
|
+
};
|
|
2962
|
+
"/v1/changes": {
|
|
2963
|
+
parameters: {
|
|
2964
|
+
query?: never;
|
|
2965
|
+
header?: never;
|
|
2966
|
+
path?: never;
|
|
2967
|
+
cookie?: never;
|
|
2968
|
+
};
|
|
2969
|
+
/**
|
|
2970
|
+
* TERYT change feed — what the registry changed, and when
|
|
2971
|
+
* @description The changes GUS published in its TERYT update files ("pliki aktualizacyjne"), served as a feed: additions, modifications, moves, renames, orderings and deletions, with the catalogue state each side belongs to. Three semantics, stated plainly: a DELETION means the object left the catalogue — it does NOT mean the address became invalid; a `reordered` change (ULIC's "Z") is a FORMATTING change — only the part of the street's name that decides its alphabetical position changed — and it is a type of its own so it can be filtered out. The `before`/`after` blocks carry GUS's own field names verbatim; the feed invents no schema. The dates are the CATALOGUE STATES (GUS's StanPrzed/StanPo), not the moment the file was published. The feed starts with the first update file this service ingested — the registry's earlier history is NOT reconstructed, and `meta.coverage.complete` says so. 503 until the first update file has been fetched (POST /admin/fetch-data?datasets=changes).
|
|
2972
|
+
*/
|
|
2973
|
+
get: {
|
|
2974
|
+
parameters: {
|
|
2975
|
+
query?: {
|
|
2976
|
+
/** @description The catalogue state to start from (YYYY-MM-DD). Changes whose "after" state is on or after this date are returned. */
|
|
2977
|
+
since?: string;
|
|
2978
|
+
/** @description The catalogue state to stop at (YYYY-MM-DD), inclusive. */
|
|
2979
|
+
until?: string;
|
|
2980
|
+
/** @description The registry: terc (administrative units) | simc (localities) | ulic (streets). All three when omitted. */
|
|
2981
|
+
dataset?: "terc" | "simc" | "ulic";
|
|
2982
|
+
/** @description The change type(s), comma-separated: added, modified, moved, renamed, reordered, deleted. All of them when omitted. */
|
|
2983
|
+
type?: string;
|
|
2984
|
+
/** @description Maximum changes per page (1–200). */
|
|
2985
|
+
limit?: number;
|
|
2986
|
+
/** @description 0-based, skips the first N changes (max 10000). */
|
|
2987
|
+
offset?: number;
|
|
2988
|
+
};
|
|
2989
|
+
header?: never;
|
|
2990
|
+
path?: never;
|
|
2991
|
+
cookie?: never;
|
|
2992
|
+
};
|
|
2993
|
+
requestBody?: never;
|
|
2994
|
+
responses: {
|
|
2995
|
+
/** @description The changes, newest first, plus `meta.coverage` — the states the feed covers, when it was last ingested, and the fact that the earlier history is not reconstructed. */
|
|
2996
|
+
200: {
|
|
2997
|
+
headers: {
|
|
2998
|
+
[name: string]: unknown;
|
|
2999
|
+
};
|
|
3000
|
+
content: {
|
|
3001
|
+
"application/json": {
|
|
3002
|
+
changes: {
|
|
3003
|
+
/** @enum {string} */
|
|
3004
|
+
dataset: "terc" | "simc" | "ulic";
|
|
3005
|
+
type: string;
|
|
3006
|
+
correctionType: string | null;
|
|
3007
|
+
stanBefore: string | null;
|
|
3008
|
+
stanAfter: string | null;
|
|
3009
|
+
identityBefore: string | null;
|
|
3010
|
+
identityAfter: string | null;
|
|
3011
|
+
nameBefore: string | null;
|
|
3012
|
+
nameAfter: string | null;
|
|
3013
|
+
before: {
|
|
3014
|
+
[key: string]: unknown;
|
|
3015
|
+
};
|
|
3016
|
+
after: {
|
|
3017
|
+
[key: string]: unknown;
|
|
3018
|
+
};
|
|
3019
|
+
ingestedAt: string;
|
|
3020
|
+
}[];
|
|
3021
|
+
meta: {
|
|
3022
|
+
total: number;
|
|
3023
|
+
offset: number;
|
|
3024
|
+
limit: number;
|
|
3025
|
+
coverage: {
|
|
3026
|
+
from: string | null;
|
|
3027
|
+
to: string | null;
|
|
3028
|
+
ingestedAt: string | null;
|
|
3029
|
+
/** @constant */
|
|
3030
|
+
complete: false;
|
|
3031
|
+
};
|
|
3032
|
+
};
|
|
3033
|
+
};
|
|
3034
|
+
};
|
|
3035
|
+
};
|
|
3036
|
+
/** @description Invalid query parameters. */
|
|
3037
|
+
400: {
|
|
3038
|
+
headers: {
|
|
3039
|
+
[name: string]: unknown;
|
|
3040
|
+
};
|
|
3041
|
+
content: {
|
|
3042
|
+
"application/json": {
|
|
3043
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3044
|
+
error: string;
|
|
3045
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3046
|
+
message: string;
|
|
3047
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3048
|
+
code: string;
|
|
3049
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3050
|
+
details?: {
|
|
3051
|
+
path?: string;
|
|
3052
|
+
message?: string;
|
|
3053
|
+
}[];
|
|
3054
|
+
};
|
|
3055
|
+
};
|
|
3056
|
+
};
|
|
3057
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
3058
|
+
429: {
|
|
3059
|
+
headers: {
|
|
3060
|
+
[name: string]: unknown;
|
|
3061
|
+
};
|
|
3062
|
+
content: {
|
|
3063
|
+
"application/json": {
|
|
3064
|
+
statusCode: number;
|
|
3065
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3066
|
+
error: string;
|
|
3067
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3068
|
+
message: string;
|
|
3069
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
3070
|
+
code: string;
|
|
3071
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3072
|
+
details?: {
|
|
3073
|
+
path?: string;
|
|
3074
|
+
message?: string;
|
|
3075
|
+
}[];
|
|
3076
|
+
};
|
|
3077
|
+
};
|
|
3078
|
+
};
|
|
3079
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
3080
|
+
500: {
|
|
3081
|
+
headers: {
|
|
3082
|
+
[name: string]: unknown;
|
|
3083
|
+
};
|
|
3084
|
+
content: {
|
|
3085
|
+
"application/json": {
|
|
3086
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3087
|
+
error: string;
|
|
3088
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3089
|
+
message: string;
|
|
3090
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3091
|
+
code: string;
|
|
3092
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3093
|
+
details?: {
|
|
3094
|
+
path?: string;
|
|
3095
|
+
message?: string;
|
|
3096
|
+
}[];
|
|
3097
|
+
};
|
|
3098
|
+
};
|
|
3099
|
+
};
|
|
3100
|
+
};
|
|
3101
|
+
};
|
|
3102
|
+
put?: never;
|
|
3103
|
+
post?: never;
|
|
3104
|
+
delete?: never;
|
|
3105
|
+
options?: never;
|
|
3106
|
+
head?: never;
|
|
3107
|
+
patch?: never;
|
|
3108
|
+
trace?: never;
|
|
3109
|
+
};
|
|
3110
|
+
"/v1/reverse-geocode": {
|
|
3111
|
+
parameters: {
|
|
3112
|
+
query?: never;
|
|
3113
|
+
header?: never;
|
|
3114
|
+
path?: never;
|
|
3115
|
+
cookie?: never;
|
|
3116
|
+
};
|
|
3117
|
+
/**
|
|
3118
|
+
* Reverse geocoding (nearest PRG address point)
|
|
3119
|
+
* @description Nearest address for a WGS84 coordinate (single exact KNN query over a GiST earthdistance index — great-circle ordering in the database); falls back to the nearest localities (Phase 1 coordinates) when no address point is within 128 km.
|
|
3120
|
+
*/
|
|
3121
|
+
get: {
|
|
3122
|
+
parameters: {
|
|
3123
|
+
query: {
|
|
3124
|
+
/** @description WGS84 latitude. Required — a blank value ('?lat=') is a 400, not 0. */
|
|
3125
|
+
lat: number;
|
|
3126
|
+
/** @description WGS84 longitude. Required — a blank value ('?lon=') is a 400, not 0. */
|
|
3127
|
+
lon: number;
|
|
3128
|
+
/** @description Maximum matches (1–50). */
|
|
3129
|
+
limit?: number;
|
|
3130
|
+
/** @description 'geojson' answers an RFC 7946 FeatureCollection (every match a Feature) instead of the JSON envelope. */
|
|
3131
|
+
format?: "json" | "geojson";
|
|
3132
|
+
};
|
|
3133
|
+
header?: never;
|
|
3134
|
+
path?: never;
|
|
3135
|
+
cookie?: never;
|
|
3136
|
+
};
|
|
3137
|
+
requestBody?: never;
|
|
3138
|
+
responses: {
|
|
3139
|
+
/** @description 'address' (PRG points, with street/locality/postal) or 'locality' (Phase 1 fallback) or 'none'. */
|
|
3140
|
+
200: {
|
|
3141
|
+
headers: {
|
|
3142
|
+
[name: string]: unknown;
|
|
3143
|
+
};
|
|
3144
|
+
content: {
|
|
3145
|
+
"application/json": {
|
|
3146
|
+
/** @enum {string} */
|
|
3147
|
+
result: "address" | "locality" | "none";
|
|
3148
|
+
matches: {
|
|
3149
|
+
lat: number;
|
|
3150
|
+
lon: number;
|
|
3151
|
+
number: string;
|
|
3152
|
+
streetId: string | null;
|
|
3153
|
+
streetName: string | null;
|
|
3154
|
+
localitySym: string;
|
|
3155
|
+
localityName: string | null;
|
|
3156
|
+
postalCode: string | null;
|
|
3157
|
+
distanceKm: number;
|
|
3158
|
+
}[];
|
|
3159
|
+
};
|
|
3160
|
+
/** @description The same answer as an RFC 7946 FeatureCollection: every match a Feature (lat/lon in the geometry), `result` as a foreign member. */
|
|
3161
|
+
"application/geo+json": Record<string, never>;
|
|
3162
|
+
};
|
|
3163
|
+
};
|
|
3164
|
+
/** @description Invalid query parameters. */
|
|
3165
|
+
400: {
|
|
3166
|
+
headers: {
|
|
3167
|
+
[name: string]: unknown;
|
|
3168
|
+
};
|
|
3169
|
+
content: {
|
|
3170
|
+
"application/json": {
|
|
3171
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3172
|
+
error: string;
|
|
3173
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3174
|
+
message: string;
|
|
3175
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3176
|
+
code: string;
|
|
3177
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3178
|
+
details?: {
|
|
3179
|
+
path?: string;
|
|
3180
|
+
message?: string;
|
|
3181
|
+
}[];
|
|
3182
|
+
};
|
|
3183
|
+
};
|
|
3184
|
+
};
|
|
3185
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
3186
|
+
429: {
|
|
3187
|
+
headers: {
|
|
3188
|
+
[name: string]: unknown;
|
|
3189
|
+
};
|
|
3190
|
+
content: {
|
|
3191
|
+
"application/json": {
|
|
3192
|
+
statusCode: number;
|
|
3193
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3194
|
+
error: string;
|
|
3195
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3196
|
+
message: string;
|
|
3197
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
3198
|
+
code: string;
|
|
3199
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3200
|
+
details?: {
|
|
3201
|
+
path?: string;
|
|
3202
|
+
message?: string;
|
|
3203
|
+
}[];
|
|
3204
|
+
};
|
|
3205
|
+
};
|
|
3206
|
+
};
|
|
3207
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
3208
|
+
500: {
|
|
3209
|
+
headers: {
|
|
3210
|
+
[name: string]: unknown;
|
|
3211
|
+
};
|
|
3212
|
+
content: {
|
|
3213
|
+
"application/json": {
|
|
3214
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3215
|
+
error: string;
|
|
3216
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3217
|
+
message: string;
|
|
3218
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3219
|
+
code: string;
|
|
3220
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3221
|
+
details?: {
|
|
3222
|
+
path?: string;
|
|
3223
|
+
message?: string;
|
|
3224
|
+
}[];
|
|
3225
|
+
};
|
|
3226
|
+
};
|
|
3227
|
+
};
|
|
3228
|
+
/** @description Address dataset not available (POST /admin/ingest-prg). */
|
|
3229
|
+
503: {
|
|
3230
|
+
headers: {
|
|
3231
|
+
[name: string]: unknown;
|
|
3232
|
+
};
|
|
3233
|
+
content: {
|
|
3234
|
+
"application/json": {
|
|
3235
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3236
|
+
error: string;
|
|
3237
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3238
|
+
message: string;
|
|
3239
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3240
|
+
code: string;
|
|
3241
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3242
|
+
details?: {
|
|
3243
|
+
path?: string;
|
|
3244
|
+
message?: string;
|
|
3245
|
+
}[];
|
|
3246
|
+
};
|
|
3247
|
+
};
|
|
3248
|
+
};
|
|
3249
|
+
};
|
|
3250
|
+
};
|
|
3251
|
+
put?: never;
|
|
3252
|
+
post?: never;
|
|
3253
|
+
delete?: never;
|
|
3254
|
+
options?: never;
|
|
3255
|
+
head?: never;
|
|
3256
|
+
patch?: never;
|
|
3257
|
+
trace?: never;
|
|
3258
|
+
};
|
|
3259
|
+
"/v1/whoami": {
|
|
3260
|
+
parameters: {
|
|
3261
|
+
query?: never;
|
|
3262
|
+
header?: never;
|
|
3263
|
+
path?: never;
|
|
3264
|
+
cookie?: never;
|
|
3265
|
+
};
|
|
3266
|
+
/**
|
|
3267
|
+
* What this service sees about your requests
|
|
3268
|
+
* @description Echoes the attribution fields recorded for your requests: caller classification, normalized User-Agent family, referrer/origin hostname, Cloudflare country, the API client a presented key resolves to, the rate limit that applies to you, and a link to the usage policy. Intended for integrators verifying their identification: a meaningful User-Agent and/or an `X-API-Key` header (operator-issued, `t24_…`) is what turns an anonymous caller into a named one with a rate-limit bucket of its own. Not cached — the answer is per-caller.
|
|
3269
|
+
*/
|
|
3270
|
+
get: {
|
|
3271
|
+
parameters: {
|
|
3272
|
+
query?: never;
|
|
3273
|
+
header?: never;
|
|
3274
|
+
path?: never;
|
|
3275
|
+
cookie?: never;
|
|
3276
|
+
};
|
|
3277
|
+
requestBody?: never;
|
|
3278
|
+
responses: {
|
|
3279
|
+
/** @description What the service records about this request. */
|
|
3280
|
+
200: {
|
|
3281
|
+
headers: {
|
|
3282
|
+
[name: string]: unknown;
|
|
3283
|
+
};
|
|
3284
|
+
content: {
|
|
3285
|
+
"application/json": {
|
|
3286
|
+
/** @description Label of the API key presented, null when keyless. */
|
|
3287
|
+
apiClient: string | null;
|
|
3288
|
+
identified: boolean;
|
|
3289
|
+
/** @description browser | bot | server | unknown. */
|
|
3290
|
+
clientClass: string;
|
|
3291
|
+
/** @description Normalized User-Agent family, e.g. 'Chrome/141'. */
|
|
3292
|
+
userAgent: string;
|
|
3293
|
+
refererHost: string | null;
|
|
3294
|
+
originHost: string | null;
|
|
3295
|
+
/** @description 2-letter CF-IPCountry; null when the request bypassed the edge. */
|
|
3296
|
+
country: string | null;
|
|
3297
|
+
/** @description Path of the usage-policy page (limits, identification, attribution, prohibited uses). */
|
|
3298
|
+
policyUrl: string;
|
|
3299
|
+
rateLimit: {
|
|
3300
|
+
max: number;
|
|
3301
|
+
windowMs: number;
|
|
3302
|
+
scope: string;
|
|
3303
|
+
};
|
|
3304
|
+
};
|
|
3305
|
+
};
|
|
3306
|
+
};
|
|
3307
|
+
/** @description The presented X-API-Key is invalid or revoked. */
|
|
3308
|
+
401: {
|
|
3309
|
+
headers: {
|
|
3310
|
+
[name: string]: unknown;
|
|
3311
|
+
};
|
|
3312
|
+
content: {
|
|
3313
|
+
"application/json": {
|
|
3314
|
+
error: string;
|
|
3315
|
+
message?: string;
|
|
3316
|
+
};
|
|
3317
|
+
};
|
|
3318
|
+
};
|
|
3319
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
3320
|
+
429: {
|
|
3321
|
+
headers: {
|
|
3322
|
+
[name: string]: unknown;
|
|
3323
|
+
};
|
|
3324
|
+
content: {
|
|
3325
|
+
"application/json": {
|
|
3326
|
+
statusCode: number;
|
|
3327
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3328
|
+
error: string;
|
|
3329
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3330
|
+
message: string;
|
|
3331
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
3332
|
+
code: string;
|
|
3333
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3334
|
+
details?: {
|
|
3335
|
+
path?: string;
|
|
3336
|
+
message?: string;
|
|
3337
|
+
}[];
|
|
3338
|
+
};
|
|
3339
|
+
};
|
|
3340
|
+
};
|
|
3341
|
+
};
|
|
3342
|
+
};
|
|
3343
|
+
put?: never;
|
|
3344
|
+
post?: never;
|
|
3345
|
+
delete?: never;
|
|
3346
|
+
options?: never;
|
|
3347
|
+
head?: never;
|
|
3348
|
+
patch?: never;
|
|
3349
|
+
trace?: never;
|
|
3350
|
+
};
|
|
3351
|
+
"/v1/usage": {
|
|
3352
|
+
parameters: {
|
|
3353
|
+
query?: never;
|
|
3354
|
+
header?: never;
|
|
3355
|
+
path?: never;
|
|
3356
|
+
cookie?: never;
|
|
3357
|
+
};
|
|
3358
|
+
/**
|
|
3359
|
+
* Your own usage report (API-key holders)
|
|
3360
|
+
* @description Aggregates this key's recorded requests over a window: totals and a zero-filled per-day series (UTC days), including the 429s the key's own bucket answered. Keyless callers are answered too — `identified: false` with null `totals`/`perDay` and the shared keyless bucket in `rateLimit`; `unavailable: true` means the aggregation failed (the request still answers 200). Not cached — the answer is per-caller. Data is available up to the 90-day analytics retention.
|
|
3361
|
+
*/
|
|
3362
|
+
get: {
|
|
3363
|
+
parameters: {
|
|
3364
|
+
query?: {
|
|
3365
|
+
/** @description Window length in days (1–90, default 30). A blank value falls back to the default. */
|
|
3366
|
+
days?: number;
|
|
3367
|
+
};
|
|
3368
|
+
header?: never;
|
|
3369
|
+
path?: never;
|
|
3370
|
+
cookie?: never;
|
|
3371
|
+
};
|
|
3372
|
+
requestBody?: never;
|
|
3373
|
+
responses: {
|
|
3374
|
+
/** @description Successful response. */
|
|
3375
|
+
200: {
|
|
3376
|
+
headers: {
|
|
3377
|
+
[name: string]: unknown;
|
|
3378
|
+
};
|
|
3379
|
+
content: {
|
|
3380
|
+
"application/json": {
|
|
3381
|
+
apiClient: string | null;
|
|
3382
|
+
identified: boolean;
|
|
3383
|
+
windowDays: number;
|
|
3384
|
+
totals: {
|
|
3385
|
+
requests: number;
|
|
3386
|
+
avgLatencyMs: number | null;
|
|
3387
|
+
rateLimited: number;
|
|
3388
|
+
} | null;
|
|
3389
|
+
perDay: {
|
|
3390
|
+
date: string;
|
|
3391
|
+
requests: number;
|
|
3392
|
+
avgLatencyMs: number | null;
|
|
3393
|
+
rateLimited: number;
|
|
3394
|
+
}[] | null;
|
|
3395
|
+
unavailable: boolean;
|
|
3396
|
+
rateLimit: {
|
|
3397
|
+
max: number;
|
|
3398
|
+
windowMs: number;
|
|
3399
|
+
scope: string;
|
|
3400
|
+
};
|
|
3401
|
+
plan: {
|
|
3402
|
+
code: string | null;
|
|
3403
|
+
name: string | null;
|
|
3404
|
+
monthlyUnits: number | null;
|
|
3405
|
+
/** @enum {string} */
|
|
3406
|
+
quotaSource: "plan" | "client-override" | "none";
|
|
3407
|
+
supportLevel: string | null;
|
|
3408
|
+
} | null;
|
|
3409
|
+
period: {
|
|
3410
|
+
key: string;
|
|
3411
|
+
timezone: string;
|
|
3412
|
+
startedAt: string;
|
|
3413
|
+
nextResetAt: string;
|
|
3414
|
+
} | null;
|
|
3415
|
+
quota: {
|
|
3416
|
+
limit: number | null;
|
|
3417
|
+
used: number;
|
|
3418
|
+
remaining: number | null;
|
|
3419
|
+
percentUsed: number | null;
|
|
3420
|
+
enforced: boolean;
|
|
3421
|
+
} | null;
|
|
3422
|
+
perEndpoint: {
|
|
3423
|
+
endpoint: string;
|
|
3424
|
+
requests: number;
|
|
3425
|
+
units: number;
|
|
3426
|
+
revalidations: number;
|
|
3427
|
+
rateLimited: number;
|
|
3428
|
+
}[] | null;
|
|
3429
|
+
generatedAt: string;
|
|
3430
|
+
};
|
|
3431
|
+
};
|
|
3432
|
+
};
|
|
3433
|
+
/** @description The presented X-API-Key is invalid or revoked. */
|
|
3434
|
+
401: {
|
|
3435
|
+
headers: {
|
|
3436
|
+
[name: string]: unknown;
|
|
3437
|
+
};
|
|
3438
|
+
content: {
|
|
3439
|
+
"application/json": {
|
|
3440
|
+
error: string;
|
|
3441
|
+
message?: string;
|
|
3442
|
+
};
|
|
3443
|
+
};
|
|
3444
|
+
};
|
|
3445
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
3446
|
+
429: {
|
|
3447
|
+
headers: {
|
|
3448
|
+
[name: string]: unknown;
|
|
3449
|
+
};
|
|
3450
|
+
content: {
|
|
3451
|
+
"application/json": {
|
|
3452
|
+
statusCode: number;
|
|
3453
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3454
|
+
error: string;
|
|
3455
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3456
|
+
message: string;
|
|
3457
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
3458
|
+
code: string;
|
|
3459
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3460
|
+
details?: {
|
|
3461
|
+
path?: string;
|
|
3462
|
+
message?: string;
|
|
3463
|
+
}[];
|
|
3464
|
+
};
|
|
3465
|
+
};
|
|
3466
|
+
};
|
|
3467
|
+
};
|
|
3468
|
+
};
|
|
3469
|
+
put?: never;
|
|
3470
|
+
post?: never;
|
|
3471
|
+
delete?: never;
|
|
3472
|
+
options?: never;
|
|
3473
|
+
head?: never;
|
|
3474
|
+
patch?: never;
|
|
3475
|
+
trace?: never;
|
|
3476
|
+
};
|
|
3477
|
+
"/v1/datasets": {
|
|
3478
|
+
parameters: {
|
|
3479
|
+
query?: never;
|
|
3480
|
+
header?: never;
|
|
3481
|
+
path?: never;
|
|
3482
|
+
cookie?: never;
|
|
3483
|
+
};
|
|
3484
|
+
/**
|
|
3485
|
+
* Dataset provenance and freshness
|
|
3486
|
+
* @description What data this instance serves and how old it is. Per dataset: the source and its licence, the date the SOURCE stamped (the GUS/GeoNames file name date; null for the per-voivodeship PRG packages and the BDL census, which have no single one), when this instance last published it, the row count as measured by that ingest, and whether it is past its staleness budget. `lastAttempt` reports the most recent ingest run of any status — a validation-rejected or failed update is visible here instead of the data silently looking current. Raw errors are never exposed; the outcome bucket is the public fact. Values only: a missing fact is null (unknown), never guessed. Not cached.
|
|
3487
|
+
*/
|
|
3488
|
+
get: {
|
|
3489
|
+
parameters: {
|
|
3490
|
+
query?: never;
|
|
3491
|
+
header?: never;
|
|
3492
|
+
path?: never;
|
|
3493
|
+
cookie?: never;
|
|
3494
|
+
};
|
|
3495
|
+
requestBody?: never;
|
|
3496
|
+
responses: {
|
|
3497
|
+
/** @description Per-dataset status, values only. */
|
|
3498
|
+
200: {
|
|
3499
|
+
headers: {
|
|
3500
|
+
[name: string]: unknown;
|
|
3501
|
+
};
|
|
3502
|
+
content: {
|
|
3503
|
+
"application/json": {
|
|
3504
|
+
datasets: {
|
|
3505
|
+
/** @enum {string} */
|
|
3506
|
+
id: "simc" | "terc" | "ulic" | "pna" | "geonames" | "prg" | "bdl";
|
|
3507
|
+
title: string;
|
|
3508
|
+
source: string;
|
|
3509
|
+
licence?: string | null;
|
|
3510
|
+
/** @description True when age is measured from the source's own date stamp; false when only the ingest time is known (prg/bdl). */
|
|
3511
|
+
sourceDated: boolean;
|
|
3512
|
+
sourceFile?: string | null;
|
|
3513
|
+
/** @description YYYY-MM-DD parsed from the source file name; null when the source publishes no single date. */
|
|
3514
|
+
sourceDate?: string | null;
|
|
3515
|
+
sourceAgeDays?: number | null;
|
|
3516
|
+
/** @description When this instance started processing the published version. */
|
|
3517
|
+
processingStartedAt?: string | null;
|
|
3518
|
+
/** @description When this instance committed the currently served version. */
|
|
3519
|
+
publishedAt?: string | null;
|
|
3520
|
+
ingestAgeDays?: number | null;
|
|
3521
|
+
/** @description Rows as measured by the publishing ingest (or the live state tables for prg/bdl); null when never ingested here. */
|
|
3522
|
+
recordCount?: number | null;
|
|
3523
|
+
recordCountAsOf?: string | null;
|
|
3524
|
+
/** @description Runtime datasets only: how much of the dataset exists here. */
|
|
3525
|
+
coverage?: string | null;
|
|
3526
|
+
budgetDays: number;
|
|
3527
|
+
stale: boolean;
|
|
3528
|
+
/** @enum {string} */
|
|
3529
|
+
status: "ok" | "stale" | "unknown";
|
|
3530
|
+
publishedWith?: {
|
|
3531
|
+
warnings: number;
|
|
3532
|
+
forced: boolean;
|
|
3533
|
+
} | null;
|
|
3534
|
+
}[];
|
|
3535
|
+
lastAttempt?: {
|
|
3536
|
+
startedAt: string;
|
|
3537
|
+
finishedAt?: string | null;
|
|
3538
|
+
/** @enum {string} */
|
|
3539
|
+
status: "running" | "success" | "failed";
|
|
3540
|
+
/**
|
|
3541
|
+
* @description validation-rejected means the update was blocked and the previously published data is still served.
|
|
3542
|
+
* @enum {string}
|
|
3543
|
+
*/
|
|
3544
|
+
outcome: "published" | "validation-rejected" | "failed" | "running";
|
|
3545
|
+
} | null;
|
|
3546
|
+
policyUrl: string;
|
|
3547
|
+
generatedAt: string;
|
|
3548
|
+
};
|
|
3549
|
+
};
|
|
3550
|
+
};
|
|
3551
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
3552
|
+
429: {
|
|
3553
|
+
headers: {
|
|
3554
|
+
[name: string]: unknown;
|
|
3555
|
+
};
|
|
3556
|
+
content: {
|
|
3557
|
+
"application/json": {
|
|
3558
|
+
statusCode: number;
|
|
3559
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3560
|
+
error: string;
|
|
3561
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3562
|
+
message: string;
|
|
3563
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
3564
|
+
code: string;
|
|
3565
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3566
|
+
details?: {
|
|
3567
|
+
path?: string;
|
|
3568
|
+
message?: string;
|
|
3569
|
+
}[];
|
|
3570
|
+
};
|
|
3571
|
+
};
|
|
3572
|
+
};
|
|
3573
|
+
};
|
|
3574
|
+
};
|
|
3575
|
+
put?: never;
|
|
3576
|
+
post?: never;
|
|
3577
|
+
delete?: never;
|
|
3578
|
+
options?: never;
|
|
3579
|
+
head?: never;
|
|
3580
|
+
patch?: never;
|
|
3581
|
+
trace?: never;
|
|
3582
|
+
};
|
|
3583
|
+
"/v1/autosuggest": {
|
|
3584
|
+
parameters: {
|
|
3585
|
+
query?: never;
|
|
3586
|
+
header?: never;
|
|
3587
|
+
path?: never;
|
|
3588
|
+
cookie?: never;
|
|
3589
|
+
};
|
|
3590
|
+
/**
|
|
3591
|
+
* Unified autocomplete across cities, localities, streets and postal codes
|
|
3592
|
+
* @description One dropdown call over the whole catalog. Each layer reuses the exact search its dedicated endpoint serves (cities/localities prefix+fuzzy, streets ranked by prominence, postal digit-prefixes), merged by a documented formula: the match tier (exact > prefix > alias > fuzzy) dominates, real-world prominence (population, address points) spreads within a tier, and the optional lat/lon focus reorders by distance inside a tier without restricting the results. A dataset-backed layer that is absent or failing contributes nothing and is named in `layersDegraded`. Response rows are a discriminated union on `type`; `label` is the fully-qualified display string.
|
|
3593
|
+
*/
|
|
3594
|
+
get: {
|
|
3595
|
+
parameters: {
|
|
3596
|
+
query: {
|
|
3597
|
+
/** @description Search query; diacritics- and punctuation-insensitive. */
|
|
3598
|
+
q: string;
|
|
3599
|
+
/** @description Comma-separated subset of city,locality,street,postal (default: all). An unknown layer name is a 400. */
|
|
3600
|
+
layers?: string;
|
|
3601
|
+
/** @description Maximum suggestions (1–20, default 8). */
|
|
3602
|
+
limit?: number;
|
|
3603
|
+
/** @description WGS84 latitude of the optional focus point (with lon): reorders within a tier by distance, never restricts. A blank value is treated as absent. */
|
|
3604
|
+
lat?: number;
|
|
3605
|
+
/** @description WGS84 longitude — must be given together with lat. */
|
|
3606
|
+
lon?: number;
|
|
3607
|
+
/** @description Optional 2-digit rodzaj filter for the place layers. */
|
|
3608
|
+
rm?: string;
|
|
3609
|
+
/** @description Optional 2-digit TERC voivodeship filter (place layers). */
|
|
3610
|
+
province?: string;
|
|
3611
|
+
/** @description Optional 4-digit TERC filter (place layers). */
|
|
3612
|
+
county?: string;
|
|
3613
|
+
/** @description Optional 6-digit TERC filter (place layers). */
|
|
3614
|
+
municipality?: string;
|
|
3615
|
+
/** @description Opt-in exonym fallback for the place layers ('Danzig' finds Gdańsk). */
|
|
3616
|
+
aliases?: "true" | "false";
|
|
3617
|
+
};
|
|
3618
|
+
header?: never;
|
|
3619
|
+
path?: never;
|
|
3620
|
+
cookie?: never;
|
|
3621
|
+
};
|
|
3622
|
+
requestBody?: never;
|
|
3623
|
+
responses: {
|
|
3624
|
+
/** @description Successful response. */
|
|
3625
|
+
200: {
|
|
3626
|
+
headers: {
|
|
3627
|
+
[name: string]: unknown;
|
|
3628
|
+
};
|
|
3629
|
+
content: {
|
|
3630
|
+
"application/json": {
|
|
3631
|
+
suggestions: ({
|
|
3632
|
+
/** @constant */
|
|
3633
|
+
type: "city";
|
|
3634
|
+
id: string | null;
|
|
3635
|
+
name: string;
|
|
3636
|
+
label: string;
|
|
3637
|
+
score: number;
|
|
3638
|
+
province: string | null;
|
|
3639
|
+
county: string | null;
|
|
3640
|
+
municipality: string | null;
|
|
3641
|
+
provinceCode: string | null;
|
|
3642
|
+
countyCode: string | null;
|
|
3643
|
+
municipalityCode: string | null;
|
|
3644
|
+
lat: number | null;
|
|
3645
|
+
lon: number | null;
|
|
3646
|
+
population: number | null;
|
|
3647
|
+
distanceKm?: number;
|
|
3648
|
+
} | {
|
|
3649
|
+
/** @constant */
|
|
3650
|
+
type: "locality";
|
|
3651
|
+
id: string;
|
|
3652
|
+
name: string;
|
|
3653
|
+
label: string;
|
|
3654
|
+
score: number;
|
|
3655
|
+
rm: string | null;
|
|
3656
|
+
typeLabel: string | null;
|
|
3657
|
+
province: string | null;
|
|
3658
|
+
county: string | null;
|
|
3659
|
+
municipality: string | null;
|
|
3660
|
+
provinceCode: string | null;
|
|
3661
|
+
countyCode: string | null;
|
|
3662
|
+
municipalityCode: string | null;
|
|
3663
|
+
lat: number | null;
|
|
3664
|
+
lon: number | null;
|
|
3665
|
+
population: number | null;
|
|
3666
|
+
distanceKm?: number;
|
|
3667
|
+
} | {
|
|
3668
|
+
/** @constant */
|
|
3669
|
+
type: "street";
|
|
3670
|
+
id: string;
|
|
3671
|
+
name: string;
|
|
3672
|
+
label: string;
|
|
3673
|
+
score: number;
|
|
3674
|
+
cecha: string | null;
|
|
3675
|
+
city: string;
|
|
3676
|
+
localityName: string;
|
|
3677
|
+
provinceCode: string | null;
|
|
3678
|
+
countyCode: string | null;
|
|
3679
|
+
addressCount?: number;
|
|
3680
|
+
localityCount?: number;
|
|
3681
|
+
lat: number | null;
|
|
3682
|
+
lon: number | null;
|
|
3683
|
+
distanceKm?: number;
|
|
3684
|
+
} | {
|
|
3685
|
+
/** @constant */
|
|
3686
|
+
type: "postal";
|
|
3687
|
+
code: string;
|
|
3688
|
+
city: string;
|
|
3689
|
+
label: string;
|
|
3690
|
+
score: number;
|
|
3691
|
+
province: string | null;
|
|
3692
|
+
lat: number | null;
|
|
3693
|
+
lon: number | null;
|
|
3694
|
+
distanceKm?: number;
|
|
3695
|
+
})[];
|
|
3696
|
+
layersDegraded?: ("city" | "locality" | "street" | "postal")[];
|
|
3697
|
+
};
|
|
3698
|
+
};
|
|
3699
|
+
};
|
|
3700
|
+
/** @description Invalid query parameters. */
|
|
3701
|
+
400: {
|
|
3702
|
+
headers: {
|
|
3703
|
+
[name: string]: unknown;
|
|
3704
|
+
};
|
|
3705
|
+
content: {
|
|
3706
|
+
"application/json": {
|
|
3707
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3708
|
+
error: string;
|
|
3709
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3710
|
+
message: string;
|
|
3711
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3712
|
+
code: string;
|
|
3713
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3714
|
+
details?: {
|
|
3715
|
+
path?: string;
|
|
3716
|
+
message?: string;
|
|
3717
|
+
}[];
|
|
3718
|
+
};
|
|
3719
|
+
};
|
|
3720
|
+
};
|
|
3721
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
3722
|
+
429: {
|
|
3723
|
+
headers: {
|
|
3724
|
+
[name: string]: unknown;
|
|
3725
|
+
};
|
|
3726
|
+
content: {
|
|
3727
|
+
"application/json": {
|
|
3728
|
+
statusCode: number;
|
|
3729
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3730
|
+
error: string;
|
|
3731
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3732
|
+
message: string;
|
|
3733
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
3734
|
+
code: string;
|
|
3735
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3736
|
+
details?: {
|
|
3737
|
+
path?: string;
|
|
3738
|
+
message?: string;
|
|
3739
|
+
}[];
|
|
3740
|
+
};
|
|
3741
|
+
};
|
|
3742
|
+
};
|
|
3743
|
+
/** @description Service is warming up. */
|
|
3744
|
+
503: {
|
|
3745
|
+
headers: {
|
|
3746
|
+
[name: string]: unknown;
|
|
3747
|
+
};
|
|
3748
|
+
content: {
|
|
3749
|
+
"application/json": {
|
|
3750
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3751
|
+
error: string;
|
|
3752
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3753
|
+
message: string;
|
|
3754
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3755
|
+
code: string;
|
|
3756
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3757
|
+
details?: {
|
|
3758
|
+
path?: string;
|
|
3759
|
+
message?: string;
|
|
3760
|
+
}[];
|
|
3761
|
+
};
|
|
3762
|
+
};
|
|
3763
|
+
};
|
|
3764
|
+
};
|
|
3765
|
+
};
|
|
3766
|
+
put?: never;
|
|
3767
|
+
post?: never;
|
|
3768
|
+
delete?: never;
|
|
3769
|
+
options?: never;
|
|
3770
|
+
head?: never;
|
|
3771
|
+
patch?: never;
|
|
3772
|
+
trace?: never;
|
|
3773
|
+
};
|
|
3774
|
+
"/v1/streets/{symUl}": {
|
|
3775
|
+
parameters: {
|
|
3776
|
+
query?: never;
|
|
3777
|
+
header?: never;
|
|
3778
|
+
path?: never;
|
|
3779
|
+
cookie?: never;
|
|
3780
|
+
};
|
|
3781
|
+
/**
|
|
3782
|
+
* Street detail by SYM_UL (occurrences, hierarchy, PRG aggregates)
|
|
3783
|
+
* @description One street's full record — the JSON mirror of the /ulice/:symUl page: identity (display name + CECHA), every locality where the SYM_UL is registered (with the inflated hierarchy, coordinates, population and citySlug), per-occurrence PRG aggregates (address count, postal codes, centroid, house-number sample) and the merged street-level `prg` block. SYM_UL ids are unique per county only, so same-id streets aggregate into one record with every locality listed. `occurrences` caps at 100 (reported via occurrenceCount/occurrencesTruncated); `prg` is null without the PRG dataset. 404 on an unknown id.
|
|
3784
|
+
*/
|
|
3785
|
+
get: {
|
|
3786
|
+
parameters: {
|
|
3787
|
+
query?: never;
|
|
3788
|
+
header?: never;
|
|
3789
|
+
path: {
|
|
3790
|
+
/** @description Street SYM_UL (5 digits, as returned by /v1/streets). */
|
|
3791
|
+
symUl: string;
|
|
3792
|
+
};
|
|
3793
|
+
cookie?: never;
|
|
3794
|
+
};
|
|
3795
|
+
requestBody?: never;
|
|
3796
|
+
responses: {
|
|
3797
|
+
/** @description Successful response. */
|
|
3798
|
+
200: {
|
|
3799
|
+
headers: {
|
|
3800
|
+
[name: string]: unknown;
|
|
3801
|
+
};
|
|
3802
|
+
content: {
|
|
3803
|
+
"application/json": {
|
|
3804
|
+
street: {
|
|
3805
|
+
id: string;
|
|
3806
|
+
cecha: string | null;
|
|
3807
|
+
name: string;
|
|
3808
|
+
};
|
|
3809
|
+
occurrenceCount: number;
|
|
3810
|
+
occurrences: {
|
|
3811
|
+
sym: string;
|
|
3812
|
+
localityName: string;
|
|
3813
|
+
province: string | null;
|
|
3814
|
+
county: string | null;
|
|
3815
|
+
municipality: string | null;
|
|
3816
|
+
provinceCode: string | null;
|
|
3817
|
+
countyCode: string | null;
|
|
3818
|
+
municipalityCode: string | null;
|
|
3819
|
+
citySlug: string | null;
|
|
3820
|
+
rm: string | null;
|
|
3821
|
+
population: number | null;
|
|
3822
|
+
lat: number | null;
|
|
3823
|
+
lon: number | null;
|
|
3824
|
+
prg: {
|
|
3825
|
+
addressCount: number;
|
|
3826
|
+
postalCodes: string[];
|
|
3827
|
+
centroidLat: number;
|
|
3828
|
+
centroidLon: number;
|
|
3829
|
+
houseNumbers: string[];
|
|
3830
|
+
} | null;
|
|
3831
|
+
}[];
|
|
3832
|
+
occurrencesTruncated?: boolean;
|
|
3833
|
+
prg: {
|
|
3834
|
+
addressCount: number;
|
|
3835
|
+
occurrenceCount: number;
|
|
3836
|
+
centroidLat: number;
|
|
3837
|
+
centroidLon: number;
|
|
3838
|
+
postalCodes: string[];
|
|
3839
|
+
} | null;
|
|
3840
|
+
};
|
|
3841
|
+
};
|
|
3842
|
+
};
|
|
3843
|
+
/** @description Invalid query parameters. */
|
|
3844
|
+
400: {
|
|
3845
|
+
headers: {
|
|
3846
|
+
[name: string]: unknown;
|
|
3847
|
+
};
|
|
3848
|
+
content: {
|
|
3849
|
+
"application/json": {
|
|
3850
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3851
|
+
error: string;
|
|
3852
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3853
|
+
message: string;
|
|
3854
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3855
|
+
code: string;
|
|
3856
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3857
|
+
details?: {
|
|
3858
|
+
path?: string;
|
|
3859
|
+
message?: string;
|
|
3860
|
+
}[];
|
|
3861
|
+
};
|
|
3862
|
+
};
|
|
3863
|
+
};
|
|
3864
|
+
/** @description Unknown street SYM_UL. */
|
|
3865
|
+
404: {
|
|
3866
|
+
headers: {
|
|
3867
|
+
[name: string]: unknown;
|
|
3868
|
+
};
|
|
3869
|
+
content: {
|
|
3870
|
+
"application/json": {
|
|
3871
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3872
|
+
error: string;
|
|
3873
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3874
|
+
message: string;
|
|
3875
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3876
|
+
code: string;
|
|
3877
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3878
|
+
details?: {
|
|
3879
|
+
path?: string;
|
|
3880
|
+
message?: string;
|
|
3881
|
+
}[];
|
|
3882
|
+
};
|
|
3883
|
+
};
|
|
3884
|
+
};
|
|
3885
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
3886
|
+
429: {
|
|
3887
|
+
headers: {
|
|
3888
|
+
[name: string]: unknown;
|
|
3889
|
+
};
|
|
3890
|
+
content: {
|
|
3891
|
+
"application/json": {
|
|
3892
|
+
statusCode: number;
|
|
3893
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3894
|
+
error: string;
|
|
3895
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3896
|
+
message: string;
|
|
3897
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
3898
|
+
code: string;
|
|
3899
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3900
|
+
details?: {
|
|
3901
|
+
path?: string;
|
|
3902
|
+
message?: string;
|
|
3903
|
+
}[];
|
|
3904
|
+
};
|
|
3905
|
+
};
|
|
3906
|
+
};
|
|
3907
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
3908
|
+
500: {
|
|
3909
|
+
headers: {
|
|
3910
|
+
[name: string]: unknown;
|
|
3911
|
+
};
|
|
3912
|
+
content: {
|
|
3913
|
+
"application/json": {
|
|
3914
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3915
|
+
error: string;
|
|
3916
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3917
|
+
message: string;
|
|
3918
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3919
|
+
code: string;
|
|
3920
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3921
|
+
details?: {
|
|
3922
|
+
path?: string;
|
|
3923
|
+
message?: string;
|
|
3924
|
+
}[];
|
|
3925
|
+
};
|
|
3926
|
+
};
|
|
3927
|
+
};
|
|
3928
|
+
/** @description Street dataset not available (fetch it via POST /admin/fetch-data?datasets=ulic). */
|
|
3929
|
+
503: {
|
|
3930
|
+
headers: {
|
|
3931
|
+
[name: string]: unknown;
|
|
3932
|
+
};
|
|
3933
|
+
content: {
|
|
3934
|
+
"application/json": {
|
|
3935
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
3936
|
+
error: string;
|
|
3937
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
3938
|
+
message: string;
|
|
3939
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
3940
|
+
code: string;
|
|
3941
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
3942
|
+
details?: {
|
|
3943
|
+
path?: string;
|
|
3944
|
+
message?: string;
|
|
3945
|
+
}[];
|
|
3946
|
+
};
|
|
3947
|
+
};
|
|
3948
|
+
};
|
|
3949
|
+
};
|
|
3950
|
+
};
|
|
3951
|
+
put?: never;
|
|
3952
|
+
post?: never;
|
|
3953
|
+
delete?: never;
|
|
3954
|
+
options?: never;
|
|
3955
|
+
head?: never;
|
|
3956
|
+
patch?: never;
|
|
3957
|
+
trace?: never;
|
|
3958
|
+
};
|
|
3959
|
+
"/v1/geocode/batch": {
|
|
3960
|
+
parameters: {
|
|
3961
|
+
query?: never;
|
|
3962
|
+
header?: never;
|
|
3963
|
+
path?: never;
|
|
3964
|
+
cookie?: never;
|
|
3965
|
+
};
|
|
3966
|
+
get?: never;
|
|
3967
|
+
put?: never;
|
|
3968
|
+
/**
|
|
3969
|
+
* Batch address validation (up to 50 GET /v1/geocode requests in one call)
|
|
3970
|
+
* @description The body is `{ requests: [...] }`; every item is exactly the GET endpoint's query fields (plus an optional echoed `id`) validated by the same schema, and each is resolved through the identical pipeline — the batch answers what fifty GETs would have, minus fifty round-trips and fifty rate-limit slots. A malformed envelope is one top-level 400; an individual bad item becomes a `status:"error"` row carrying the HTTP status the single GET would have answered (400/404/503) — one wrong address never discards the rest. Rows preserve request order; the HTTP status is 200 whenever the envelope parsed. One batch call consumes one rate-limit slot; execution is sequential to protect the database pool.
|
|
3971
|
+
*/
|
|
3972
|
+
post: {
|
|
3973
|
+
parameters: {
|
|
3974
|
+
query?: never;
|
|
3975
|
+
header?: never;
|
|
3976
|
+
path?: never;
|
|
3977
|
+
cookie?: never;
|
|
3978
|
+
};
|
|
3979
|
+
requestBody: {
|
|
3980
|
+
content: {
|
|
3981
|
+
"application/json": {
|
|
3982
|
+
requests: {
|
|
3983
|
+
id?: unknown;
|
|
3984
|
+
sym?: unknown;
|
|
3985
|
+
locality?: unknown;
|
|
3986
|
+
postalCode?: unknown;
|
|
3987
|
+
number?: unknown;
|
|
3988
|
+
street?: unknown;
|
|
3989
|
+
streetName?: unknown;
|
|
3990
|
+
address?: unknown;
|
|
3991
|
+
limit?: unknown;
|
|
3992
|
+
}[];
|
|
3993
|
+
};
|
|
3994
|
+
};
|
|
3995
|
+
};
|
|
3996
|
+
responses: {
|
|
3997
|
+
/** @description Successful response. */
|
|
3998
|
+
200: {
|
|
3999
|
+
headers: {
|
|
4000
|
+
[name: string]: unknown;
|
|
4001
|
+
};
|
|
4002
|
+
content: {
|
|
4003
|
+
"application/json": {
|
|
4004
|
+
results: ({
|
|
4005
|
+
/** @enum {string} */
|
|
4006
|
+
result: "exact" | "street" | "street-ambiguous" | "locality-ambiguous" | "none";
|
|
4007
|
+
matches: {
|
|
4008
|
+
lat: number;
|
|
4009
|
+
lon: number;
|
|
4010
|
+
number: string;
|
|
4011
|
+
streetId: string | null;
|
|
4012
|
+
postalCode: string | null;
|
|
4013
|
+
}[];
|
|
4014
|
+
query?: {
|
|
4015
|
+
city: string | null;
|
|
4016
|
+
street: string | null;
|
|
4017
|
+
number: string | null;
|
|
4018
|
+
numbers?: string[];
|
|
4019
|
+
range?: boolean;
|
|
4020
|
+
cityResolved: boolean;
|
|
4021
|
+
};
|
|
4022
|
+
nearestNumbers?: {
|
|
4023
|
+
number: string;
|
|
4024
|
+
distance: number;
|
|
4025
|
+
}[];
|
|
4026
|
+
baseNumberMatch?: {
|
|
4027
|
+
number: string;
|
|
4028
|
+
lat: number;
|
|
4029
|
+
lon: number;
|
|
4030
|
+
postalCode: string | null;
|
|
4031
|
+
};
|
|
4032
|
+
streets?: {
|
|
4033
|
+
id: string;
|
|
4034
|
+
name: string;
|
|
4035
|
+
sym?: string;
|
|
4036
|
+
city?: string;
|
|
4037
|
+
provinceCode?: string | null;
|
|
4038
|
+
}[];
|
|
4039
|
+
localities?: {
|
|
4040
|
+
sym: string;
|
|
4041
|
+
name: string;
|
|
4042
|
+
type: string | null;
|
|
4043
|
+
typeLabel: string | null;
|
|
4044
|
+
province: string | null;
|
|
4045
|
+
county: string | null;
|
|
4046
|
+
municipality: string | null;
|
|
4047
|
+
provinceCode: string | null;
|
|
4048
|
+
countyCode: string | null;
|
|
4049
|
+
municipalityCode: string | null;
|
|
4050
|
+
population: number | null;
|
|
4051
|
+
}[];
|
|
4052
|
+
localitiesTruncated?: boolean;
|
|
4053
|
+
id?: string;
|
|
4054
|
+
/** @constant */
|
|
4055
|
+
status: "ok";
|
|
4056
|
+
} | {
|
|
4057
|
+
id?: string;
|
|
4058
|
+
/** @constant */
|
|
4059
|
+
status: "error";
|
|
4060
|
+
httpStatus: number;
|
|
4061
|
+
error: string;
|
|
4062
|
+
details?: {
|
|
4063
|
+
path: string;
|
|
4064
|
+
message: string;
|
|
4065
|
+
}[];
|
|
4066
|
+
})[];
|
|
4067
|
+
};
|
|
4068
|
+
};
|
|
4069
|
+
};
|
|
4070
|
+
/** @description Invalid query parameters. */
|
|
4071
|
+
400: {
|
|
4072
|
+
headers: {
|
|
4073
|
+
[name: string]: unknown;
|
|
4074
|
+
};
|
|
4075
|
+
content: {
|
|
4076
|
+
"application/json": {
|
|
4077
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
4078
|
+
error: string;
|
|
4079
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
4080
|
+
message: string;
|
|
4081
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
4082
|
+
code: string;
|
|
4083
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
4084
|
+
details?: {
|
|
4085
|
+
path?: string;
|
|
4086
|
+
message?: string;
|
|
4087
|
+
}[];
|
|
4088
|
+
};
|
|
4089
|
+
};
|
|
4090
|
+
};
|
|
4091
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
4092
|
+
429: {
|
|
4093
|
+
headers: {
|
|
4094
|
+
[name: string]: unknown;
|
|
4095
|
+
};
|
|
4096
|
+
content: {
|
|
4097
|
+
"application/json": {
|
|
4098
|
+
statusCode: number;
|
|
4099
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
4100
|
+
error: string;
|
|
4101
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
4102
|
+
message: string;
|
|
4103
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
4104
|
+
code: string;
|
|
4105
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
4106
|
+
details?: {
|
|
4107
|
+
path?: string;
|
|
4108
|
+
message?: string;
|
|
4109
|
+
}[];
|
|
4110
|
+
};
|
|
4111
|
+
};
|
|
4112
|
+
};
|
|
4113
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
4114
|
+
500: {
|
|
4115
|
+
headers: {
|
|
4116
|
+
[name: string]: unknown;
|
|
4117
|
+
};
|
|
4118
|
+
content: {
|
|
4119
|
+
"application/json": {
|
|
4120
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
4121
|
+
error: string;
|
|
4122
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
4123
|
+
message: string;
|
|
4124
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
4125
|
+
code: string;
|
|
4126
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
4127
|
+
details?: {
|
|
4128
|
+
path?: string;
|
|
4129
|
+
message?: string;
|
|
4130
|
+
}[];
|
|
4131
|
+
};
|
|
4132
|
+
};
|
|
4133
|
+
};
|
|
4134
|
+
};
|
|
4135
|
+
};
|
|
4136
|
+
delete?: never;
|
|
4137
|
+
options?: never;
|
|
4138
|
+
head?: never;
|
|
4139
|
+
patch?: never;
|
|
4140
|
+
trace?: never;
|
|
4141
|
+
};
|
|
4142
|
+
"/v1/postal-codes/bulk": {
|
|
4143
|
+
parameters: {
|
|
4144
|
+
query?: never;
|
|
4145
|
+
header?: never;
|
|
4146
|
+
path?: never;
|
|
4147
|
+
cookie?: never;
|
|
4148
|
+
};
|
|
4149
|
+
get?: never;
|
|
4150
|
+
put?: never;
|
|
4151
|
+
/**
|
|
4152
|
+
* Bulk postal-code detail (up to 100 GET /v1/postal-codes/:code requests in one call)
|
|
4153
|
+
* @description The body is `{ codes: [...] }` (display or digits form); every code is answered through the same resolution as the detail endpoint, so a bulk row is byte-identical to the single lookup. A malformed envelope is one top-level 400; an individual malformed or unknown code becomes a `status:"error"` row (with the HTTP status the single GET would have answered). Rows preserve request order; ok rows carry the canonical display code.
|
|
4154
|
+
*/
|
|
4155
|
+
post: {
|
|
4156
|
+
parameters: {
|
|
4157
|
+
query?: never;
|
|
4158
|
+
header?: never;
|
|
4159
|
+
path?: never;
|
|
4160
|
+
cookie?: never;
|
|
4161
|
+
};
|
|
4162
|
+
requestBody: {
|
|
4163
|
+
content: {
|
|
4164
|
+
"application/json": {
|
|
4165
|
+
codes: string[];
|
|
4166
|
+
};
|
|
4167
|
+
};
|
|
4168
|
+
};
|
|
4169
|
+
responses: {
|
|
4170
|
+
/** @description Per-code results in request order: `status:"ok"` rows carry the detail endpoint's body (code, rows, prg); `status:"error"` rows carry the error the single GET would have answered with. */
|
|
4171
|
+
200: {
|
|
4172
|
+
headers: {
|
|
4173
|
+
[name: string]: unknown;
|
|
4174
|
+
};
|
|
4175
|
+
content: {
|
|
4176
|
+
"application/json": {
|
|
4177
|
+
results: {
|
|
4178
|
+
/** @description The raw input echoed (display form on ok rows). */
|
|
4179
|
+
code: string;
|
|
4180
|
+
/** @enum {string} */
|
|
4181
|
+
status: "ok" | "error";
|
|
4182
|
+
/** @description Error rows: the status the single GET would have answered. */
|
|
4183
|
+
httpStatus?: number;
|
|
4184
|
+
error?: string;
|
|
4185
|
+
details?: Record<string, never>[];
|
|
4186
|
+
rows?: {
|
|
4187
|
+
code: string;
|
|
4188
|
+
city: string;
|
|
4189
|
+
province: string | null;
|
|
4190
|
+
county: string | null;
|
|
4191
|
+
municipality: string | null;
|
|
4192
|
+
municipalityKind: string | null;
|
|
4193
|
+
lat: number | null;
|
|
4194
|
+
lon: number | null;
|
|
4195
|
+
sym: string | null;
|
|
4196
|
+
citySlug: string | null;
|
|
4197
|
+
type: string | null;
|
|
4198
|
+
typeLabel: string | null;
|
|
4199
|
+
population: number | null;
|
|
4200
|
+
}[];
|
|
4201
|
+
prg?: {
|
|
4202
|
+
addressCount: number;
|
|
4203
|
+
streetCount: number;
|
|
4204
|
+
centroidLat: number;
|
|
4205
|
+
centroidLon: number;
|
|
4206
|
+
streets: string[];
|
|
4207
|
+
streetsTruncated?: boolean;
|
|
4208
|
+
};
|
|
4209
|
+
}[];
|
|
4210
|
+
};
|
|
4211
|
+
};
|
|
4212
|
+
};
|
|
4213
|
+
/** @description Invalid query parameters. */
|
|
4214
|
+
400: {
|
|
4215
|
+
headers: {
|
|
4216
|
+
[name: string]: unknown;
|
|
4217
|
+
};
|
|
4218
|
+
content: {
|
|
4219
|
+
"application/json": {
|
|
4220
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
4221
|
+
error: string;
|
|
4222
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
4223
|
+
message: string;
|
|
4224
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
4225
|
+
code: string;
|
|
4226
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
4227
|
+
details?: {
|
|
4228
|
+
path?: string;
|
|
4229
|
+
message?: string;
|
|
4230
|
+
}[];
|
|
4231
|
+
};
|
|
4232
|
+
};
|
|
4233
|
+
};
|
|
4234
|
+
/** @description Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. */
|
|
4235
|
+
429: {
|
|
4236
|
+
headers: {
|
|
4237
|
+
[name: string]: unknown;
|
|
4238
|
+
};
|
|
4239
|
+
content: {
|
|
4240
|
+
"application/json": {
|
|
4241
|
+
statusCode: number;
|
|
4242
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
4243
|
+
error: string;
|
|
4244
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
4245
|
+
message: string;
|
|
4246
|
+
/** @description rate_limit_exceeded for the per-minute limit; monthly_quota_exceeded (with a `quota` block: limit, used, remaining, period, timezone, resetAt, and an upgradeUrl) when a plan's monthly quota is exhausted. */
|
|
4247
|
+
code: string;
|
|
4248
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
4249
|
+
details?: {
|
|
4250
|
+
path?: string;
|
|
4251
|
+
message?: string;
|
|
4252
|
+
}[];
|
|
4253
|
+
};
|
|
4254
|
+
};
|
|
4255
|
+
};
|
|
4256
|
+
/** @description Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic (`code: internal_error`) — error detail lives in the server logs, never in the response. */
|
|
4257
|
+
500: {
|
|
4258
|
+
headers: {
|
|
4259
|
+
[name: string]: unknown;
|
|
4260
|
+
};
|
|
4261
|
+
content: {
|
|
4262
|
+
"application/json": {
|
|
4263
|
+
/** @description The HTTP status text (e.g. "Not Found"). */
|
|
4264
|
+
error: string;
|
|
4265
|
+
/** @description A human-readable sentence. Clients must not branch on it — the wording changes without notice. */
|
|
4266
|
+
message: string;
|
|
4267
|
+
/** @description The machine-readable identifier to branch on. The published table of codes lives in docs/API-COMPATIBILITY.md §5. */
|
|
4268
|
+
code: string;
|
|
4269
|
+
/** @description Field-level validation details (400 answers with parameter errors). */
|
|
4270
|
+
details?: {
|
|
4271
|
+
path?: string;
|
|
4272
|
+
message?: string;
|
|
4273
|
+
}[];
|
|
4274
|
+
};
|
|
4275
|
+
};
|
|
4276
|
+
};
|
|
4277
|
+
};
|
|
4278
|
+
};
|
|
4279
|
+
delete?: never;
|
|
4280
|
+
options?: never;
|
|
4281
|
+
head?: never;
|
|
4282
|
+
patch?: never;
|
|
4283
|
+
trace?: never;
|
|
4284
|
+
};
|
|
4285
|
+
}
|
|
4286
|
+
export type webhooks = Record<string, never>;
|
|
4287
|
+
export interface components {
|
|
4288
|
+
schemas: never;
|
|
4289
|
+
responses: never;
|
|
4290
|
+
parameters: never;
|
|
4291
|
+
requestBodies: never;
|
|
4292
|
+
headers: never;
|
|
4293
|
+
pathItems: never;
|
|
4294
|
+
}
|
|
4295
|
+
export type $defs = Record<string, never>;
|
|
4296
|
+
export type operations = Record<string, never>;
|