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.
- arfigyelo_api-0.1.0/.gitignore +39 -0
- arfigyelo_api-0.1.0/API.md +430 -0
- arfigyelo_api-0.1.0/CONTEXT.md +43 -0
- arfigyelo_api-0.1.0/LICENSE +21 -0
- arfigyelo_api-0.1.0/PKG-INFO +141 -0
- arfigyelo_api-0.1.0/README.md +116 -0
- arfigyelo_api-0.1.0/docs/adr/0001-money-as-decimal.md +34 -0
- arfigyelo_api-0.1.0/docs/adr/0002-dual-sync-async-clients.md +30 -0
- arfigyelo_api-0.1.0/docs/adr/0003-client-side-prevalidation.md +35 -0
- arfigyelo_api-0.1.0/pyproject.toml +79 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/__init__.py +61 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/_version.py +3 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/cache.py +37 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/client.py +785 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/errors.py +51 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/mapping.py +124 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/models.py +198 -0
- arfigyelo_api-0.1.0/src/arfigyelo_api/py.typed +0 -0
- arfigyelo_api-0.1.0/tests/conftest.py +21 -0
- arfigyelo_api-0.1.0/tests/fixtures/categories.json +186 -0
- arfigyelo_api-0.1.0/tests/fixtures/chain_stores.json +13 -0
- arfigyelo_api-0.1.0/tests/fixtures/empty_page.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/error_bad_request.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/error_not_found_product.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/error_search_input.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/product_2000000853635.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/product_2148180000002.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/product_5999550782526.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/product_shop_prices.json +14 -0
- arfigyelo_api-0.1.0/tests/fixtures/products_by_category_47.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/products_by_category_5.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/search_tejfol.json +132 -0
- arfigyelo_api-0.1.0/tests/fixtures/shops.json +58 -0
- arfigyelo_api-0.1.0/tests/fixtures/spring_404.json +1 -0
- arfigyelo_api-0.1.0/tests/fixtures/waf_403.html +8 -0
- arfigyelo_api-0.1.0/tests/test_cache.py +58 -0
- arfigyelo_api-0.1.0/tests/test_client.py +389 -0
- arfigyelo_api-0.1.0/tests/test_iterators.py +115 -0
- arfigyelo_api-0.1.0/tests/test_mapping.py +138 -0
- arfigyelo_api-0.1.0/tests/test_models.py +224 -0
- 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).
|