arfigyelo-api 0.1.0__tar.gz

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.
Files changed (41) hide show
  1. arfigyelo_api-0.1.0/.gitignore +39 -0
  2. arfigyelo_api-0.1.0/API.md +430 -0
  3. arfigyelo_api-0.1.0/CONTEXT.md +43 -0
  4. arfigyelo_api-0.1.0/LICENSE +21 -0
  5. arfigyelo_api-0.1.0/PKG-INFO +141 -0
  6. arfigyelo_api-0.1.0/README.md +116 -0
  7. arfigyelo_api-0.1.0/docs/adr/0001-money-as-decimal.md +34 -0
  8. arfigyelo_api-0.1.0/docs/adr/0002-dual-sync-async-clients.md +30 -0
  9. arfigyelo_api-0.1.0/docs/adr/0003-client-side-prevalidation.md +35 -0
  10. arfigyelo_api-0.1.0/pyproject.toml +79 -0
  11. arfigyelo_api-0.1.0/src/arfigyelo_api/__init__.py +61 -0
  12. arfigyelo_api-0.1.0/src/arfigyelo_api/_version.py +3 -0
  13. arfigyelo_api-0.1.0/src/arfigyelo_api/cache.py +37 -0
  14. arfigyelo_api-0.1.0/src/arfigyelo_api/client.py +785 -0
  15. arfigyelo_api-0.1.0/src/arfigyelo_api/errors.py +51 -0
  16. arfigyelo_api-0.1.0/src/arfigyelo_api/mapping.py +124 -0
  17. arfigyelo_api-0.1.0/src/arfigyelo_api/models.py +198 -0
  18. arfigyelo_api-0.1.0/src/arfigyelo_api/py.typed +0 -0
  19. arfigyelo_api-0.1.0/tests/conftest.py +21 -0
  20. arfigyelo_api-0.1.0/tests/fixtures/categories.json +186 -0
  21. arfigyelo_api-0.1.0/tests/fixtures/chain_stores.json +13 -0
  22. arfigyelo_api-0.1.0/tests/fixtures/empty_page.json +1 -0
  23. arfigyelo_api-0.1.0/tests/fixtures/error_bad_request.json +1 -0
  24. arfigyelo_api-0.1.0/tests/fixtures/error_not_found_product.json +1 -0
  25. arfigyelo_api-0.1.0/tests/fixtures/error_search_input.json +1 -0
  26. arfigyelo_api-0.1.0/tests/fixtures/product_2000000853635.json +1 -0
  27. arfigyelo_api-0.1.0/tests/fixtures/product_2148180000002.json +1 -0
  28. arfigyelo_api-0.1.0/tests/fixtures/product_5999550782526.json +1 -0
  29. arfigyelo_api-0.1.0/tests/fixtures/product_shop_prices.json +14 -0
  30. arfigyelo_api-0.1.0/tests/fixtures/products_by_category_47.json +1 -0
  31. arfigyelo_api-0.1.0/tests/fixtures/products_by_category_5.json +1 -0
  32. arfigyelo_api-0.1.0/tests/fixtures/search_tejfol.json +132 -0
  33. arfigyelo_api-0.1.0/tests/fixtures/shops.json +58 -0
  34. arfigyelo_api-0.1.0/tests/fixtures/spring_404.json +1 -0
  35. arfigyelo_api-0.1.0/tests/fixtures/waf_403.html +8 -0
  36. arfigyelo_api-0.1.0/tests/test_cache.py +58 -0
  37. arfigyelo_api-0.1.0/tests/test_client.py +389 -0
  38. arfigyelo_api-0.1.0/tests/test_iterators.py +115 -0
  39. arfigyelo_api-0.1.0/tests/test_mapping.py +138 -0
  40. arfigyelo_api-0.1.0/tests/test_models.py +224 -0
  41. arfigyelo_api-0.1.0/tests/test_validation.py +159 -0
@@ -0,0 +1,39 @@
1
+ # Python bytecode and caches
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ .pytest_cache/
6
+ .mypy_cache/
7
+ .ruff_cache/
8
+ .hypothesis/
9
+ .tox/
10
+ .nox/
11
+ .cache/
12
+
13
+ # Coverage
14
+ .coverage
15
+ .coverage.*
16
+ coverage.xml
17
+ htmlcov/
18
+
19
+ # Build artifacts
20
+ build/
21
+ dist/
22
+ site/
23
+ *.egg
24
+ *.egg-info/
25
+ .eggs/
26
+
27
+ # Virtual environments and local secrets
28
+ .venv/
29
+ venv/
30
+ .env
31
+ .env.*
32
+
33
+ # Editors and OS
34
+ .idea/
35
+ .vscode/
36
+ .DS_Store
37
+ Thumbs.db
38
+
39
+ # Keep uv.lock committed: CI uses `uv sync --locked` for reproducible builds.
@@ -0,0 +1,430 @@
1
+ # arfigyelo.gvh.hu — API map
2
+
3
+ Public, anonymous price-comparison API behind the Árfigyelő SPA.
4
+
5
+ - **Base URL:** `https://arfigyelo.gvh.hu/api`
6
+ - **Auth:** none (no cookies, tokens, or API keys)
7
+ - **Format:** JSON, UTF-8; prices are HUF as floats
8
+ - **Methods:** `GET` only (`HEAD` also allowed)
9
+ - **Sources:** HAR `arfigyelo.gvh.hu_Archive [26-11-19 14-13-45].har`, live probing on 2026-11-19, SPA bundle `/assets/index-5baaf084.js` (410 KB)
10
+
11
+ All seven endpoints below were found by decompiling the SPA bundle (`axios.create({baseURL:"/api"})`) and were verified live. There are no other `/api/*` routes: every non-matching path falls through to the SPA HTML or a Spring 404.
12
+
13
+ ---
14
+
15
+ ## Endpoint summary
16
+
17
+ | # | Method | Path | Purpose |
18
+ |---|--------|------|---------|
19
+ | 1 | GET | `/api/categories` | Full category tree |
20
+ | 2 | GET | `/api/chain-stores` | Retail chains (9) |
21
+ | 3 | GET | `/api/shops` | Physical shops (1,831) |
22
+ | 4 | GET | `/api/products-by-category/{categoryId}` | Product list for a category (incl. descendants) |
23
+ | 5 | GET | `/api/search` | Text search |
24
+ | 6 | GET | `/api/product/{productId}` | Product detail, chain-level prices, shop availability |
25
+ | 7 | GET | `/api/product/{productId}/shop/{shopUuids}` | Per-shop prices for one product |
26
+
27
+ All are cacheable: `cache-control: public, max-age=299` (5 min), served through Azure CDN (`x-cache`, `x-azure-ref`).
28
+ Nothing sets `Access-Control-Allow-Origin`; cross-origin browser calls are blocked (an `OPTIONS` preflight with `Origin` is rejected with 403). Use it server-side.
29
+
30
+ ---
31
+
32
+ ## 1. `GET /api/categories`
33
+
34
+ Returns the whole category tree in one response (~24.6 KB).
35
+
36
+ ```json
37
+ {"categories":[{
38
+ "id": 1001,
39
+ "name": "Tejtermék, sajt, tojás",
40
+ "path": "tejtermek_sajt_tojas",
41
+ "icon": null,
42
+ "categoryNodes": [ /* recursive */ ]
43
+ }]}
44
+ ```
45
+
46
+ 2026-11-19 snapshot: **9 root nodes, 212 nodes total, max depth 2** (root → group → leaf). `icon` was `null` on every node.
47
+
48
+ Root nodes:
49
+
50
+ | id | path | name | children |
51
+ |---:|---|---|---:|
52
+ | 1001 | `tejtermek_sajt_tojas` | Tejtermék, sajt, tojás | 8 |
53
+ | 1015 | `hus_hal_felvagott` | Hús, hal, felvágott | 8 |
54
+ | 1028 | `zoldseg_gyumolcs` | Zöldség, gyümölcs | 3 |
55
+ | 1046 | `pekaru` | Pékáru | 2 |
56
+ | 1050 | `tartos_elelmiszer_ital` | Tartós élelmiszerek, italok | 8 |
57
+ | 1068 | `specialis_etrend` | Speciális étrend | 4 |
58
+ | 1123 | `baba` | Baba | 3 |
59
+ | 1126 | `haztartas` | Háztartás | 3 |
60
+ | 1138 | `szepseg_higienia` | Szépség és higiénia | 3 |
61
+
62
+ `path` is the slug used by the web routes (`/k/{path}`). `id` is what the product endpoints take. They are not the same hierarchy: **root IDs return 0 products**, while depth-1 IDs aggregate all descendants (e.g. `2001` "Tej" = 85 products = sum of its four leaf children; `2010` "Sajt" = 648).
63
+
64
+ ---
65
+
66
+ ## 2. `GET /api/chain-stores`
67
+
68
+ ```json
69
+ {"chainStores":[{"uuid":"3ccc9f35-604c-4ccf-8376-64822ce4bc70","name":"Spar","imageUrl":"spar"}]}
70
+ ```
71
+
72
+ `imageUrl` is a slug, not a URL (assets live at `/assets/{slug}-logo-small-*.svg`).
73
+
74
+ | Chain | UUID | Shops |
75
+ |---|---|---:|
76
+ | Spar | `3ccc9f35-604c-4ccf-8376-64822ce4bc70` | 375 |
77
+ | Rossmann | `41e81400-3e3d-47b4-84f7-7dce01cc9b43` | 282 |
78
+ | dm | `555f7e7c-8229-4f4f-ba60-450925a5b308` | 259 |
79
+ | Penny | `53b66cb6-a24f-420d-9861-d38757467d07` | 248 |
80
+ | Lidl | `f95031d8-84a5-4edf-b4fa-18b2cbae2ea1` | 222 |
81
+ | Tesco | `792ea257-0af9-4588-ada7-81bd96c96400` | 197 |
82
+ | Aldi | `55b678e0-4e02-49d7-86da-ba6fba862a7e` | 188 |
83
+ | Müller | `e313905a-b57e-4016-b4d2-1d1f45e53157` | 34 |
84
+ | Auchan | `e9cc63fd-52e0-4c1e-ba8d-d135d7285c63` | 26 |
85
+
86
+ ## 3. `GET /api/shops`
87
+
88
+ Returns all 1,831 shops (~416 KB).
89
+
90
+ ```json
91
+ {"shops":[{
92
+ "uuid": "spar-110",
93
+ "postalCode": "1011",
94
+ "city": "Budapest I.",
95
+ "address": "Batthyány tér 5-6",
96
+ "chainStoreUuid": "3ccc9f35-604c-4ccf-8376-64822ce4bc70",
97
+ "location": {"latitude": 47.506062, "longitude": 19.038035},
98
+ "openingTime": ""
99
+ }]}
100
+ ```
101
+
102
+ `openingTime` is a human-readable string, usually empty; when present it uses `#` as a line separator, e.g. `Nyitvatartás: 06:30-21:30#Nyitvatartás - Vasárnap: 07:00-19:00`. `location` was present on all shops.
103
+
104
+ Shop UUIDs (`spar-110`, `auchan-002`, …) are the only valid values for the `shopIds` filter and the per-shop endpoint. Chain UUIDs are **not** accepted there.
105
+
106
+ ---
107
+
108
+ ## 4. `GET /api/products-by-category/{categoryId}`
109
+
110
+ Returns products for a category and all of its descendants.
111
+
112
+ ### Query parameters
113
+
114
+ | Param | Type | Default | Notes |
115
+ |---|---|---|---|
116
+ | `categoryId` | path, integer | — | from `/api/categories` |
117
+ | `limit` | integer | **12** | server caps at **48** |
118
+ | `offset` | integer | 0 | |
119
+ | `order` | string | `unitAmount_asc` | see below |
120
+ | `shopIds` | string | — | comma-separated shop UUIDs; filters products **and** returned prices |
121
+
122
+ `order` values:
123
+
124
+ | Value | Sort |
125
+ |---|---|
126
+ | `unitAmount_asc` *(default)* | ascending `minUnitPrice` |
127
+ | `unitAmount_desc` | descending `minUnitPrice` |
128
+ | `amount_asc` | ascending cheapest pack price (`productMinAmount`) |
129
+ | `amount_desc` | descending cheapest pack price |
130
+
131
+ `relevance` is **not** accepted here (500).
132
+
133
+ ### Example
134
+
135
+ ```bash
136
+ curl 'https://arfigyelo.gvh.hu/api/products-by-category/5?limit=24&offset=0&order=unitAmount_asc'
137
+ ```
138
+
139
+ ```json
140
+ {
141
+ "products": [{
142
+ "id": "penny-2076",
143
+ "name": "Sissy tejföl 20% 450g",
144
+ "imageUrl": "https://cdnarfigyeloprodweu.azureedge.net/images/product-image-penny-2076.jpg",
145
+ "unit": "kg",
146
+ "unitTitle": "db",
147
+ "bulk": false,
148
+ "returnType": null,
149
+ "returnFee": 0,
150
+ "packaging": "0.45",
151
+ "categoryPath": "tejtermek_sajt_tojas/tejfol/tejfol_20",
152
+ "minUnitPrice": 886.67,
153
+ "pricesOfChainStores": [{
154
+ "id": "53b66cb6-a24f-420d-9861-d38757467d07",
155
+ "name": "Penny",
156
+ "priceSameEverywhere": true,
157
+ "productMinAmount": 399.0,
158
+ "prices": [
159
+ {"type": "NORMAL", "amount": 449.0, "unitAmount": 997.78, "sameAmountEverywhere": true},
160
+ {"type": "DISCOUNTED", "amount": 399.0, "unitAmount": 886.67, "sameAmountEverywhere": true}
161
+ ]
162
+ }]
163
+ }],
164
+ "count": 40
165
+ }
166
+ ```
167
+
168
+ ### Pagination semantics (important)
169
+
170
+ - `count` is the total matching products **for a non-empty page**.
171
+ - **When the page is empty, `count` is `0`, not the total.** Stop paginating on `products: []`, not on `offset >= count`.
172
+ - `limit > 48` is silently clipped to 48 (verified: 48 → 48 items, 49/100/1000 → 48 items).
173
+ - The 48-item cap drops nothing: paging category `2001` (`count: 85`) with `limit=24` at `offset=0/24/48/72` returns 24+24+24+13 = 85, so it is a page-size cap, not silently discarded rows.
174
+ - Non-numeric/negative `limit` or `offset` → `500 INTERNAL_SERVER_ERROR`.
175
+ - Unknown/non-existent category → `200 {"products":[],"count":0}`.
176
+ - Non-numeric category path → 500 (or Spring 404 for a slash-containing path).
177
+
178
+ With `shopIds`, the response is filtered to prices available in those shops; `count` and `minUnitPrice` reflect the filter. Unknown shop IDs simply produce an empty result.
179
+
180
+ ---
181
+
182
+ ## 5. `GET /api/search`
183
+
184
+ ### Query parameters
185
+
186
+ | Param | Type | Default | Notes |
187
+ |---|---|---|---|
188
+ | `q` | string | — | required; trimmed; **min 3 characters**; accent-insensitive |
189
+ | `limit` | integer | **48** | capped at 48 |
190
+ | `offset` | integer | 0 | |
191
+ | `order` | string | `relevance` | `relevance`, `unitAmount_asc`, `unitAmount_desc`, `amount_asc`, `amount_desc` |
192
+ | `shopIds` | string | — | comma-separated shop UUIDs |
193
+
194
+ Search matches accents both ways: `q=tejfol` and `q=tejföl` both return the same 76 results. Digits and spaces are valid (`q=123`, `q=a b`). A single trailing space is ignored.
195
+
196
+ ### Example
197
+
198
+ ```bash
199
+ curl 'https://arfigyelo.gvh.hu/api/search?q=tejfol&limit=48&offset=0&order=relevance'
200
+ ```
201
+
202
+ Response shape is identical to endpoint 4 (`{"products":[...],"count":...}`).
203
+
204
+ ### Validation
205
+
206
+ | Case | Result |
207
+ |---|---|
208
+ | `q` missing | `500 INTERNAL_SERVER_ERROR` (backend bug) |
209
+ | `q` empty / blank / < 3 chars | `400 {"code":"SEARCH-INPUT-ERROR","message":"Invalid search parameter"}` |
210
+ | `order=bogus` | `500 INTERNAL_SERVER_ERROR` |
211
+ | SQL-injection-like input | 403 HTML (WAF "Hamarosan indul" page), not JSON |
212
+
213
+ Same pagination caveat as endpoint 4: `count` becomes `0` on an empty page.
214
+
215
+ ---
216
+
217
+ ## 6. `GET /api/product/{productId}`
218
+
219
+ `productId` is the `id` from list/search results (`5999550782526`, `lidl-0001534`, `penny-2076`, …).
220
+
221
+ ```json
222
+ {
223
+ "id": "5999550782526",
224
+ "name": "S-Budget friss csirkemellfilé",
225
+ "imageUrl": "https://cdnarfigyeloprodweu.azureedge.net/images/product-image-5999550782526.jpg",
226
+ "unit": "kg",
227
+ "unitTitle": "kg",
228
+ "bulk": true,
229
+ "returnType": null,
230
+ "returnFee": 0,
231
+ "packaging": "1",
232
+ "categoryId": "18",
233
+ "categoryPath": "hus_hal_felvagott/szarnyas/csirkemell",
234
+ "chainStores": [{
235
+ "uuid": "3ccc9f35-604c-4ccf-8376-64822ce4bc70",
236
+ "name": "Spar",
237
+ "imageUrl": "spar",
238
+ "prices": [
239
+ {"type": "NORMAL", "amount": 1924.0, "unitAmount": 1924.0}
240
+ ],
241
+ "pricesMax": [],
242
+ "priceSameEverywhere": true,
243
+ "availableInShops": ["spar-104", "spar-105", "spar-106", "..."]
244
+ }]
245
+ }
246
+ ```
247
+
248
+ Differences vs. the list model:
249
+
250
+ - `categoryId` is added (string).
251
+ - `pricesOfChainStores` → `chainStores`, each entry keyed by `uuid` (not `id`).
252
+ - Chain entries carry `pricesMax` and `availableInShops`.
253
+ - No `minUnitPrice` / `productMinAmount` at the top level.
254
+
255
+ `pricesMax` is populated only when the chain sells the product at different prices in different shops; it then holds the maximum variant(s). Example: Spar `prices` NORMAL 92.0, `pricesMax` NORMAL 99.0, `priceSameEverywhere: false`.
256
+
257
+ Unknown product:
258
+
259
+ ```http
260
+ HTTP 404
261
+ {"code":"NOT_FOUND_PRODUCT","message":"No product found based on the product UUID! [uuid: nope]"}
262
+ ```
263
+
264
+ ---
265
+
266
+ ## 7. `GET /api/product/{productId}/shop/{shopUuids}`
267
+
268
+ `shopUuids` = comma-separated shop UUIDs (from endpoint 3 or `availableInShops`).
269
+
270
+ ```bash
271
+ curl 'https://arfigyelo.gvh.hu/api/product/5999545594554/shop/spar-536,spar-622,spar-631'
272
+ ```
273
+
274
+ ```json
275
+ {"shops":[
276
+ {"uuid":"5999545594554","shopUuid":"spar-536","prices":[{"type":"NORMAL","amount":99.0,"unitAmount":66.0}]},
277
+ {"uuid":"5999545594554","shopUuid":"spar-622","prices":[{"type":"NORMAL","amount":92.0,"unitAmount":61.33}]}
278
+ ]}
279
+ ```
280
+
281
+ - The top-level `uuid` is the **product ID** (API quirk; naming suggests product, not shop).
282
+ - Only shops that actually have a price are returned; unknown/unavailable shop IDs are skipped.
283
+ - If no requested shop has a price (or the product is unknown):
284
+ ```http
285
+ HTTP 404
286
+ {"code":"PRODUCT-SHOP-PRICES-NOT-FOUND","message":"Not found prices by product and shops uuid! [productUuid : '...', shopUuids : [...]]"}
287
+ ```
288
+ - Prices include `NORMAL` and `DISCOUNTED`, but **not `LOYALTY`** — loyalty prices only appear in the product-detail endpoint.
289
+ - Result order is not the requested order.
290
+
291
+ ---
292
+
293
+ ## Data models
294
+
295
+ ### Product list item (endpoints 4, 5)
296
+
297
+ | Field | Type | Notes |
298
+ |---|---|---|
299
+ | `id` | string | numeric EAN-style or retailer-prefixed (`lidl-0001534`, `penny-2076`) |
300
+ | `name` | string | Hungarian product name |
301
+ | `imageUrl` | string | absolute CDN URL on `cdnarfigyeloprodweu.azureedge.net` |
302
+ | `unit` | `kg` \| `l` \| `db` \| `g` | base unit for unit price |
303
+ | `unitTitle` | string | sale-unit label, observed `db` and `csomag` |
304
+ | `bulk` | boolean | bulk/loose goods flag |
305
+ | `returnType` | `null` \| `"one-way-return-fee"` | deposit type |
306
+ | `returnFee` | number | HUF; `0` or `50` observed |
307
+ | `packaging` | string | numeric string, size in `unit` (e.g. `"0.45"`, `"1.5"`) |
308
+ | `categoryPath` | string | slug path |
309
+ | `minUnitPrice` | number | HUF per `unit`, cheapest non-loyalty price |
310
+ | `pricesOfChainStores` | array | see below |
311
+
312
+ `unitAmount = amount / packaging`. For unit `db` with `packaging: "5"` (multipack), `unitAmount` is the per-piece price. `minUnitPrice` is the minimum `unitAmount` across all `NORMAL` and `DISCOUNTED` prices — `LOYALTY` prices are excluded. `productMinAmount` is similarly the minimum `amount`, excluding `LOYALTY`.
313
+
314
+ ### `pricesOfChainStores[]`
315
+
316
+ | Field | Type | Notes |
317
+ |---|---|---|
318
+ | `id` | string | chain-store UUID |
319
+ | `name` | string | chain name |
320
+ | `priceSameEverywhere` | boolean | same price in all shops of that chain |
321
+ | `productMinAmount` | number | cheapest shelf price at that chain (excl. loyalty) |
322
+ | `prices` | array | `{type, amount, unitAmount, sameAmountEverywhere}` |
323
+
324
+ ### Price object
325
+
326
+ | Field | Type | Notes |
327
+ |---|---|---|
328
+ | `type` | `NORMAL` \| `DISCOUNTED` \| `LOYALTY` | |
329
+ | `amount` | number | shelf price in HUF |
330
+ | `unitAmount` | number | HUF per `unit` |
331
+ | `sameAmountEverywhere` | boolean | list responses only |
332
+
333
+ ### Product detail (endpoint 6)
334
+
335
+ | Field | Type |
336
+ |---|---|
337
+ | `id`, `name`, `imageUrl` | string |
338
+ | `unit`, `unitTitle` | string |
339
+ | `bulk` | boolean |
340
+ | `returnType` | string \| null |
341
+ | `returnFee` | number |
342
+ | `packaging` | string |
343
+ | `categoryId` | string |
344
+ | `categoryPath` | string |
345
+ | `chainStores[]` | `{uuid, name, imageUrl, prices[], pricesMax[], priceSameEverywhere, availableInShops[]}` |
346
+
347
+ Detail `prices` entries omit `sameAmountEverywhere`; the chain object carries `priceSameEverywhere` instead.
348
+
349
+ ### Category
350
+
351
+ `{id:number, name:string, path:string, icon:null, categoryNodes:Category[]}`
352
+
353
+ ### Chain store
354
+
355
+ `{uuid:string, name:string, imageUrl:string /* slug */}`
356
+
357
+ ### Shop
358
+
359
+ `{uuid, postalCode, city, address, chainStoreUuid, location:{latitude,longitude}, openingTime}`
360
+
361
+ ---
362
+
363
+ ## SPA route → API mapping
364
+
365
+ | Web route | API calls |
366
+ |---|---|
367
+ | `/` | `/api/categories`, `/api/chain-stores`, category endpoint for "most searched" |
368
+ | `/k/:categoryPath+` | `/api/categories` (resolve slug → id), then `/api/products-by-category/{id}` |
369
+ | `/k/:categoryPath+/t/:productId` | `/api/product/{id}`; optionally `/api/product/{id}/shop/{shopIds}` |
370
+ | `/kereses/:searchText` | `/api/search?q=...&limit=...&offset=...&order=...` |
371
+ | `/uzletek` | `/api/shops`, `/api/chain-stores` |
372
+ | `/bevasarlolista` | client-side only (localStorage) |
373
+
374
+ Order and paging are passed as URL query params (`?order=unitAmount_asc`) and forwarded to the API.
375
+
376
+ ---
377
+
378
+ ## Errors
379
+
380
+ Custom JSON envelope:
381
+
382
+ ```json
383
+ {"code":"...","message":"..."}
384
+ ```
385
+
386
+ | Code | HTTP | Cause |
387
+ |---|---:|---|
388
+ | `NOT_FOUND_PRODUCT` | 404 | unknown `productId` in endpoint 6 |
389
+ | `PRODUCT-SHOP-PRICES-NOT-FOUND` | 404 | no requested shop has the product (endpoint 7) |
390
+ | `SEARCH-INPUT-ERROR` | 400 | missing/short/blank `q` |
391
+ | `BAD_REQUEST` | 400 | non-GET method: `{"code":"BAD_REQUEST","message":"Request method 'POST' is not supported"}` |
392
+ | `INTERNAL_SERVER_ERROR` | 500 | invalid `order`, bad/negative `limit`/`offset`, missing `q` |
393
+
394
+ Unmatched paths get Spring's default shape instead:
395
+
396
+ ```json
397
+ {"timestamp":"2026-11-19T13:20:52.189+00:00","status":404,"error":"Not Found","path":"/api/products"}
398
+ ```
399
+
400
+ `OPTIONS` on a valid endpoint returns `200` with `Allow: GET,HEAD,OPTIONS`, but a CORS preflight (`Origin` + `Access-Control-Request-Method`) is rejected with 403.
401
+
402
+ ---
403
+
404
+ ## Adjacent non-API data
405
+
406
+ Found in the same SPA bundle (not JSON API):
407
+
408
+ | URL | Content |
409
+ |---|---|
410
+ | `https://cdnarfigyeloprodweu.azureedge.net/excel/arfigyelo_napi_termekadatok.xlsx` | Daily full dump, ~2.1 MB; sheet titled `Napi feltöltések - 2026-11-17`; 25,626 rows incl. header |
411
+ | `https://cdnarfigyeloprodweu.azureedge.net/excel/arfigyelo_20250313_napi_termekadatok.xlsx` | Frozen 2025-03-13 snapshot, ~220 KB |
412
+ | `https://cdnarfigyeloprodweu.azureedge.net/images/product-image-{id}.jpg` | Product images |
413
+ | `https://arfigyelo.gvh.hu/docs/archive/{filename}.pdf` | Archived legal documents |
414
+
415
+ XLSX columns: `Termék azonosító`, `Termék név`, `Kategória azonosító`, `Kategória név`, `Üzletlánc név`, `Egység`, `Kiszerelés`, `Minimum ár`, `Maximum ár`, `Minimum egységár`, `Maximum egységár`, `Hány üzletláncban elérhető`, `Hány boltban elérhető`, `Üzletlánc összes boltja` — one row per product × chain, with Hungarian decimal commas.
416
+
417
+ ---
418
+
419
+ ## Known quirks
420
+
421
+ 1. **`count: 0` on empty pages.** Don't use `count` to detect the end of pagination; test `products.length`.
422
+ 2. **Limit cap 48.** Anything larger is clipped; the app itself requests 12/24.
423
+ 3. **Different defaults:** category = 12, search = 48.
424
+ 4. **Root categories are empty.** Only depth-1 and leaf IDs return products; depth-1 aggregates descendants.
425
+ 5. **`shopIds` takes shop UUIDs, not chain UUIDs.** Chain UUIDs silently yield zero results.
426
+ 6. **Per-shop `uuid` is the product ID.**
427
+ 7. **Per-shop prices omit `LOYALTY`.**
428
+ 8. **`relevance` works only on `/api/search`.** Passing it to the category endpoint returns 500.
429
+ 9. **No CORS.** Server-side access only, unless you proxy.
430
+ 10. **Missing `q` returns 500** rather than 400.
@@ -0,0 +1,43 @@
1
+ # Árfigyelő
2
+
3
+ A Python client package for the public Árfigyelő (arfigyelo.gvh.hu) price-comparison API of Hungarian retail chains. This file is the glossary for the domain.
4
+
5
+ ## Language
6
+
7
+ ### Retail landscape
8
+
9
+ **Chain**:
10
+ A national retail chain (e.g. Spar, Lidl, Penny) that sets prices; identified by a chain UUID.
11
+ _Avoid_: Chain store, chainStore (wire name), retailer
12
+
13
+ **Shop**:
14
+ A single physical store of a Chain, with address and coordinates; identified by a shop UUID (e.g. `spar-110`). Chain UUIDs are never valid shop identifiers.
15
+ _Avoid_: Store, chain store, üzlet
16
+ **Category Path**:
17
+ The full slug path of a Category from the tree root (e.g. `tejtermek_sajt_tojas/sajt/ementali`); identical to the web route after `/k/`. Identifies a Category uniquely.
18
+ _Avoid_: Category slug (for the full path)
19
+
20
+ **Category**:
21
+ A node in the product classification tree. Only depth-1 and leaf categories contain products; depth-1 categories aggregate their leaf descendants. Root categories return no products.
22
+ _Avoid_: Category node (wire name)
23
+
24
+ ### Products and prices
25
+
26
+ **ProductSummary**:
27
+ A product as returned by listing endpoints (category listing, search): has `minUnitPrice` and per-Chain price aggregates.
28
+ _Avoid_: Product list item, list model
29
+
30
+ **ProductDetail**:
31
+ A product as returned by the detail endpoint: has `categoryId`, per-Chain `pricesMax` and shop availability. A distinct model, not a superset of ProductSummary.
32
+ _Avoid_: Product (unqualified, when the endpoint shape matters)
33
+
34
+ **ShopPrice**:
35
+ One row of a per-shop price query: the price of one product in one Shop. The wire response mislabels the product id as `uuid`.
36
+ _Avoid_: Shop uuid (for the product id field)
37
+
38
+ **Price**:
39
+ A single price point of a product at a Chain or Shop. One of three types: `NORMAL`, `DISCOUNTED`, or `LOYALTY`. Amounts are exact forint (HUF) values with up to two decimals.
40
+
41
+ **Unit Price**:
42
+ The price per base `unit` (`kg`, `l`, `db`, `g`) computed as shelf price divided by packaging size. `minUnitPrice` excludes `LOYALTY` prices.
43
+ _Avoid_: unitAmount (wire name)
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aron
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,141 @@
1
+ Metadata-Version: 2.5
2
+ Name: arfigyelo-api
3
+ Version: 0.1.0
4
+ Summary: Python client for the Árfigyelő (arfigyelo.gvh.hu) price-comparison API.
5
+ Project-URL: Homepage, https://github.com/aronheredi/arfigyelo-api
6
+ Project-URL: Repository, https://github.com/aronheredi/arfigyelo-api
7
+ Project-URL: Issues, https://github.com/aronheredi/arfigyelo-api/issues
8
+ Project-URL: API map, https://arfigyelo.gvh.hu
9
+ Author-email: Aron <aronheredi346@gmail.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: arfigyelo,gvh,hungary,prices
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Framework :: Pydantic :: 2
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.14
22
+ Requires-Dist: httpx>=0.28
23
+ Requires-Dist: pydantic>=2.9
24
+ Description-Content-Type: text/markdown
25
+
26
+ # arfigyelo-api
27
+
28
+ Python client for the [Árfigyelő](https://arfigyelo.gvh.hu) price-comparison API —
29
+ the Hungarian Competition Authority's official retail price monitor.
30
+
31
+ Fully-typed [pydantic](https://docs.pydantic.dev/) models, sync and async
32
+ clients, a mapping layer (category paths, chains, shops), and safe pagination
33
+ iterators. All money values are exact `Decimal` forints (HUF).
34
+
35
+ Requires Python 3.14+.
36
+
37
+ ## Install
38
+
39
+ ```bash
40
+ pip install arfigyelo-api
41
+ ```
42
+
43
+ ## Usage
44
+
45
+ ### Sync
46
+
47
+ ```python
48
+ from decimal import Decimal
49
+
50
+ from arfigyelo_api import ArfigyeloClient
51
+
52
+ with ArfigyeloClient() as client:
53
+ # mapping layer: resolve by category path, never by numeric id
54
+ products = list(client.iter_products_by_path("tejtermek_sajt_tojas/sajt/ementali"))
55
+ cheapest = products[0] # default order: unitAmount_asc
56
+ print(cheapest.name, cheapest.min_unit_price) # exact Decimal HUF
57
+
58
+ detail = client.get_product(cheapest.id)
59
+ spar = client.get_chain(name="Spar")
60
+ shops = client.find_shops(city="Budapest", chain_uuid=spar.uuid)
61
+
62
+ # per-shop prices (shop uuids, not chain uuids)
63
+ prices = client.get_product_shop_prices(detail.id, [s.uuid for s in shops[:3]])
64
+ ```
65
+
66
+ ### Async
67
+
68
+ ```python
69
+ from arfigyelo_api import AsyncArfigyeloClient
70
+
71
+ async with AsyncArfigyeloClient() as client:
72
+ page = await client.search("tejföl", limit=48)
73
+ async for product in client.iter_search("sajt"):
74
+ ... # paginates safely until exhausted
75
+ ```
76
+
77
+ ### Caching
78
+
79
+ Structural indexes (categories, chains, shops) are cached in memory with a
80
+ 12-hour TTL (prices change daily). Price responses are never cached unless you
81
+ opt in:
82
+
83
+ ```python
84
+ # poll-friendly: identical price calls hit the network at most once per ttl
85
+ client = ArfigyeloClient(cache_prices=True, ttl=12 * 3600)
86
+ ```
87
+
88
+ Pass `ttl=0.0` to refetch on every call, `ttl=None` to cache for the lifetime
89
+ of the client instance.
90
+
91
+ ### Errors
92
+
93
+ All exceptions derive from `ArfigyeloError`:
94
+
95
+ - `ArfigyeloApiError` — the API's `{"code": ..., "message": ...}` envelope
96
+ (`.code`, `.message`, `.status_code`)
97
+ - `ArfigyeloValidationError` — invalid call arguments, raised *before* any
98
+ request (the API would answer these with a misleading 500)
99
+ - `ArfigyeloConnectionError` — transport failures
100
+ - `ArfigyeloUnexpectedResponseError` — non-JSON bodies (e.g. the WAF page) or
101
+ responses that fail schema validation
102
+
103
+ ## API surface
104
+
105
+ | Client method | Endpoint |
106
+ |---|---|
107
+ | `get_categories()` / `get_chains()` / `get_shops()` | structural lists |
108
+ | `get_products_by_category(id, *, limit, offset, order, shop_ids)` | category listing |
109
+ | `get_products_by_path(path, ...)` | category listing via path |
110
+ | `search(q, *, limit, offset, order, shop_ids)` | text search |
111
+ | `get_product(product_id)` | product detail |
112
+ | `get_product_shop_prices(product_id, shop_uuids)` | per-shop prices |
113
+ | `iter_products_by_category` / `iter_products_by_path` / `iter_search` | safe pagination (stop on empty page, not on `count`) |
114
+ | `get_category_by_path`, `get_chain`, `get_shop`, `find_shops`, `category_index`, `chain_index`, `shop_index` | mapping layer |
115
+
116
+ The same methods exist on `AsyncArfigyeloClient` as coroutines/async
117
+ generators. See [API.md](https://github.com/aronheredi/arfigyelo-api/blob/main/API.md)
118
+ for the full endpoint map, and
119
+ [docs/adr/](https://github.com/aronheredi/arfigyelo-api/tree/main/docs/adr)
120
+ for the design decisions.
121
+
122
+ ## Scope
123
+
124
+ The daily full-dump spreadsheet at
125
+ `https://cdnarfigyeloprodweu.azureedge.net/excel/arfigyelo_napi_termekadatok.xlsx`
126
+ is **not** part of this package — it is a CDN file, not an API endpoint; fetch
127
+ and parse it yourself if you need bulk data.
128
+
129
+ ## Development
130
+
131
+ ```bash
132
+ uv sync # install runtime + dev dependencies
133
+ uv run pytest # test suite (uses recorded fixtures, no network)
134
+ uv run ruff check . # lint
135
+ uv run mypy # strict type check
136
+ uv build # sdist + wheel in dist/
137
+ ```
138
+
139
+ ## License
140
+
141
+ MIT — see [LICENSE](https://github.com/aronheredi/arfigyelo-api/blob/main/LICENSE).