flipzi 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 (67) hide show
  1. flipzi-0.1.0/.gitignore +9 -0
  2. flipzi-0.1.0/CHANGELOG.md +19 -0
  3. flipzi-0.1.0/LICENSE +9 -0
  4. flipzi-0.1.0/PKG-INFO +259 -0
  5. flipzi-0.1.0/README.md +228 -0
  6. flipzi-0.1.0/examples/ebay_de_vs_uk.py +35 -0
  7. flipzi-0.1.0/examples/price_my_collection.py +51 -0
  8. flipzi-0.1.0/pyproject.toml +51 -0
  9. flipzi-0.1.0/scripts/generate.py +201 -0
  10. flipzi-0.1.0/scripts/unasync.py +48 -0
  11. flipzi-0.1.0/spec/openapi.yaml +7080 -0
  12. flipzi-0.1.0/src/flipzi/__init__.py +54 -0
  13. flipzi-0.1.0/src/flipzi/_async_client.py +689 -0
  14. flipzi-0.1.0/src/flipzi/_base.py +227 -0
  15. flipzi-0.1.0/src/flipzi/_sync_client.py +688 -0
  16. flipzi-0.1.0/src/flipzi/_version.py +1 -0
  17. flipzi-0.1.0/src/flipzi/enums.py +211 -0
  18. flipzi-0.1.0/src/flipzi/errors.py +56 -0
  19. flipzi-0.1.0/src/flipzi/models.py +1889 -0
  20. flipzi-0.1.0/src/flipzi/py.typed +0 -0
  21. flipzi-0.1.0/tests/__init__.py +0 -0
  22. flipzi-0.1.0/tests/fixtures/README.md +19 -0
  23. flipzi-0.1.0/tests/fixtures/analytics.json +44 -0
  24. flipzi-0.1.0/tests/fixtures/bulk-analytics.json +91 -0
  25. flipzi-0.1.0/tests/fixtures/bulk-cardmarket.json +70 -0
  26. flipzi-0.1.0/tests/fixtures/bulk.json +132 -0
  27. flipzi-0.1.0/tests/fixtures/card.json +49 -0
  28. flipzi-0.1.0/tests/fixtures/cardmarket-history.json +100 -0
  29. flipzi-0.1.0/tests/fixtures/cardmarket.json +63 -0
  30. flipzi-0.1.0/tests/fixtures/err-invalid-input.json +22 -0
  31. flipzi-0.1.0/tests/fixtures/err-invalid-uuid.json +25 -0
  32. flipzi-0.1.0/tests/fixtures/err-key-invalid.json +23 -0
  33. flipzi-0.1.0/tests/fixtures/err-key-required.json +26 -0
  34. flipzi-0.1.0/tests/fixtures/err-not-found.json +25 -0
  35. flipzi-0.1.0/tests/fixtures/err-plan-locked.json +30 -0
  36. flipzi-0.1.0/tests/fixtures/err-rate-limited.json +34 -0
  37. flipzi-0.1.0/tests/fixtures/games.json +115 -0
  38. flipzi-0.1.0/tests/fixtures/health.json +20 -0
  39. flipzi-0.1.0/tests/fixtures/history.json +154 -0
  40. flipzi-0.1.0/tests/fixtures/lookup.json +26 -0
  41. flipzi-0.1.0/tests/fixtures/marketplaces-de.json +108 -0
  42. flipzi-0.1.0/tests/fixtures/marketplaces-uk.json +148 -0
  43. flipzi-0.1.0/tests/fixtures/marketplaces.json +491 -0
  44. flipzi-0.1.0/tests/fixtures/movers.json +157 -0
  45. flipzi-0.1.0/tests/fixtures/population.json +50 -0
  46. flipzi-0.1.0/tests/fixtures/price-2.json +399 -0
  47. flipzi-0.1.0/tests/fixtures/price.json +69 -0
  48. flipzi-0.1.0/tests/fixtures/printings.json +240 -0
  49. flipzi-0.1.0/tests/fixtures/sales.json +136 -0
  50. flipzi-0.1.0/tests/fixtures/sealed-cardmarket.json +45 -0
  51. flipzi-0.1.0/tests/fixtures/sealed-comparison.json +77 -0
  52. flipzi-0.1.0/tests/fixtures/sealed-comparisons.json +1011 -0
  53. flipzi-0.1.0/tests/fixtures/search.json +102 -0
  54. flipzi-0.1.0/tests/fixtures/set-analytics.json +193 -0
  55. flipzi-0.1.0/tests/fixtures/set-cards.json +106 -0
  56. flipzi-0.1.0/tests/fixtures/sets-p1.json +62 -0
  57. flipzi-0.1.0/tests/fixtures/sets-p2.json +62 -0
  58. flipzi-0.1.0/tests/fixtures/sets-p3.json +41 -0
  59. flipzi-0.1.0/tests/fixtures/sold.json +207 -0
  60. flipzi-0.1.0/tests/fixtures/updates-p1.json +48 -0
  61. flipzi-0.1.0/tests/fixtures/updates-p2.json +47 -0
  62. flipzi-0.1.0/tests/fixtures/usage.json +33 -0
  63. flipzi-0.1.0/tests/mock_server.py +144 -0
  64. flipzi-0.1.0/tests/test_client.py +358 -0
  65. flipzi-0.1.0/tests/test_enums.py +57 -0
  66. flipzi-0.1.0/tests/test_generated.py +38 -0
  67. flipzi-0.1.0/tests/test_live.py +41 -0
@@ -0,0 +1,9 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .mypy_cache/
9
+ .env
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ This package follows [Semantic Versioning](https://semver.org/). Until 1.0.0, a minor
4
+ version may contain breaking changes; patch versions never do.
5
+
6
+ ## 0.1.0 (unreleased)
7
+
8
+ First release.
9
+
10
+ - `Flipzi` (sync) and `AsyncFlipzi` (async) clients on httpx, one method per Data API
11
+ endpoint (spec 1.19.0).
12
+ - TypedDict response models generated from the OpenAPI spec; `py.typed`.
13
+ - Enums for marketplace, currency, condition, Cardmarket grade, grader, game, finish,
14
+ language, period and movers window/direction, with `Literal` aliases.
15
+ - Retries on 429 and 5xx, honouring `Retry-After`, with `max_retries`.
16
+ - Generators for sets, set cards, search, sales and updates.
17
+ - Bulk helpers that split to the plan's bulk cap and merge the results.
18
+ - `FlipziError` with `status`, `code`, `details` and `request_id`.
19
+ - Quota and rate-limit headers through `last_response` and `on_response`.
flipzi-0.1.0/LICENSE ADDED
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Flipzi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
flipzi-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,259 @@
1
+ Metadata-Version: 2.5
2
+ Name: flipzi
3
+ Version: 0.1.0
4
+ Summary: Official Python client for the Flipzi Data API: trading card prices, eBay sold comps, Cardmarket conditions, price history and market movers for Pokémon, Magic, Yu-Gi-Oh!, One Piece, Lorcana and more.
5
+ Project-URL: Homepage, https://flipzi.io/docs/
6
+ Project-URL: Documentation, https://flipzi.io/docs/
7
+ Author-email: Flipzi <hello@flipzi.io>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: api client,card prices,cardmarket,ebay,flipzi,lorcana,mtg,one piece,pokemon,pokemon tcg,sdk,sold prices,tcg,trading cards,yugioh
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.9
23
+ Requires-Dist: httpx<1,>=0.23
24
+ Provides-Extra: dev
25
+ Requires-Dist: build>=1; extra == 'dev'
26
+ Requires-Dist: mypy>=1.5; extra == 'dev'
27
+ Requires-Dist: pytest>=7; extra == 'dev'
28
+ Requires-Dist: pyyaml>=6; extra == 'dev'
29
+ Requires-Dist: twine>=5; extra == 'dev'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # flipzi
33
+
34
+ The official Python client for the [Flipzi Data API](https://flipzi.io/docs/): trading
35
+ card prices, eBay sold prices across 8 marketplaces, Cardmarket offers by condition,
36
+ price history, PSA population and market movers. It covers Pokémon (English, Japanese and
37
+ Chinese), Magic, Yu-Gi-Oh!, One Piece, Lorcana, Riftbound, Dragon Ball, Digimon, Gundam,
38
+ Star Wars: Unlimited, Flesh and Blood and more.
39
+
40
+ - Sync and async clients (`Flipzi`, `AsyncFlipzi`), built on `httpx`.
41
+ - Fully typed: responses are `TypedDict`s generated from the API's OpenAPI spec, and the package ships `py.typed`.
42
+ - Retries on 429 and 5xx with backoff, and honours `Retry-After`.
43
+ - Generators for paged endpoints, and bulk helpers that split requests to your plan's cap.
44
+ - Python 3.9+.
45
+
46
+ ```sh
47
+ pip install flipzi
48
+ ```
49
+
50
+ ## First price in three lines
51
+
52
+ ```python
53
+ from flipzi import Flipzi
54
+ flipzi = Flipzi(api_key="fz_live_...")
55
+ print(flipzi.price("0908653a-ce24-4d7e-811e-78c2935bd822")["data"]["prices"][0]["price_formatted"])
56
+ ```
57
+
58
+ Get a free key (no card needed) at [flipzi.io/account/register?product=data](https://flipzi.io/account/register?product=data).
59
+ If you leave out `api_key`, the client reads `FLIPZI_API_KEY` from the environment.
60
+
61
+ Don't have a card id? Search for one:
62
+
63
+ ```python
64
+ card = flipzi.search("charizard ex", game="pokemon")["data"][0]
65
+ card["id"], card["name"], card["set"]["name"], card["number"]
66
+ ```
67
+
68
+ Async works the same way:
69
+
70
+ ```python
71
+ import asyncio
72
+ from flipzi import AsyncFlipzi
73
+
74
+ async def main():
75
+ async with AsyncFlipzi() as flipzi:
76
+ res = await flipzi.price("0908653a-ce24-4d7e-811e-78c2935bd822")
77
+ print(res["data"]["prices"][0]["price_formatted"])
78
+
79
+ asyncio.run(main())
80
+ ```
81
+
82
+ ## Methods
83
+
84
+ Every endpoint has one method. Each returns the API's JSON body as a dict, typed with a
85
+ `TypedDict` from `flipzi.models`.
86
+
87
+ | Method | Endpoint |
88
+ |---|---|
89
+ | `health()` | `GET /v1/meta/health` (no key needed) |
90
+ | `usage()` | `GET /v1/meta/usage` (free; still answers when you are over quota) |
91
+ | `games()` | `GET /v1/catalog/games` |
92
+ | `sets(game)` / `iter_sets(game)` | `GET /v1/catalog/sets` |
93
+ | `set_cards(set_id)` / `iter_set_cards(set_id)` | `GET /v1/catalog/sets/{set_id}/cards` |
94
+ | `set_analytics(set_id, game=)` | `GET /v1/catalog/sets/{set_id}/analytics` |
95
+ | `search(q, game=, ...)` / `iter_search(...)` | `GET /v1/cards/search` |
96
+ | `card(card_id)` | `GET /v1/cards/{card_id}` |
97
+ | `lookup(pokemontcg_id)` | `GET /v1/cards/lookup` |
98
+ | `price(card_id, grade=, currency=)` | `GET /v1/cards/{card_id}/price` |
99
+ | `history(card_id, period=)` | `GET /v1/cards/{card_id}/history` |
100
+ | `sold(card_id, ...)` | `GET /v1/cards/{card_id}/sold` |
101
+ | `marketplaces(card_id, marketplace=, ...)` | `GET /v1/cards/{card_id}/marketplaces` |
102
+ | `sales(card_id, ...)` / `iter_sales(card_id, ...)` | `GET /v1/cards/{card_id}/sales` |
103
+ | `printings(card_id)` | `GET /v1/cards/{card_id}/printings` |
104
+ | `analytics(card_id, grade=)` | `GET /v1/cards/{card_id}/analytics` |
105
+ | `cardmarket(card_id, language=)` | `GET /v1/cards/{card_id}/cardmarket` |
106
+ | `cardmarket_history(card_id, days=)` | `GET /v1/cards/{card_id}/cardmarket/history` |
107
+ | `population(card_id)` | `GET /v1/cards/{card_id}/population` |
108
+ | `updates(since)` / `iter_updates(since)` | `GET /v1/cards/updates` |
109
+ | `movers(game, window=, direction=)` | `GET /v1/market/movers` |
110
+ | `sealed_comparisons(game=, set=)` | `GET /v1/sealed/comparisons` |
111
+ | `sealed_comparison(slug)` | `GET /v1/sealed/comparisons/{slug}` |
112
+ | `sealed_cardmarket(sealed_id)` | `GET /v1/sealed/{sealed_id}/cardmarket` |
113
+ | `bulk_prices(ids, grade=, currency=)` | `POST /v1/cards/bulk` |
114
+ | `bulk_analytics(ids, ...)` | `POST /v1/cards/bulk/analytics` |
115
+ | `bulk_cardmarket(ids, language=)` | `POST /v1/cards/bulk/cardmarket` |
116
+ | `request(method, path, params, json)` | anything else |
117
+
118
+ Keyword arguments are the API's own parameter names (`page_size`, `grade`, `marketplace`),
119
+ so the [API reference](https://flipzi.io/docs/) applies word for word. Which plan each
120
+ endpoint needs, and what it costs in units, is listed there.
121
+
122
+ ## Enums
123
+
124
+ ```python
125
+ from flipzi import Marketplace, Condition, Currency, Game, Finish, Period, grade
126
+
127
+ flipzi.sold(card_id, marketplace=Marketplace.EBAY_DE, condition=Condition.NEAR_MINT)
128
+ flipzi.price(card_id, grade=grade("PSA", 10), currency=Currency.USD) # grade "PSA_10"
129
+ ```
130
+
131
+ Each enum is a `str` Enum, so `Marketplace.EBAY_DE == "ebay_de"`, and plain strings work
132
+ everywhere. Each also has a `Literal` alias (`MarketplaceLiteral` and so on) in
133
+ `flipzi.enums`. Grades are open-ended strings (`RAW`, `PSA_10`, `BGS_9.5`): build one with
134
+ `grade()`.
135
+
136
+ ## Pagination
137
+
138
+ ```python
139
+ for s in flipzi.iter_sets("pokemon"):
140
+ print(s["set_id"], s["name"])
141
+
142
+ # Every price that changed in the last hour, following the cursor.
143
+ from datetime import datetime, timedelta, timezone
144
+ since = (datetime.now(timezone.utc) - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%SZ")
145
+ for change in flipzi.iter_updates(since):
146
+ print(change["card_id"], change["grade"], change["price_cents"])
147
+ ```
148
+
149
+ Async: `async for s in flipzi.iter_sets("pokemon")`. Pass `max_items=n` to stop early.
150
+ Every page is one request and is billed as one.
151
+
152
+ ## Bulk
153
+
154
+ ```python
155
+ res = flipzi.bulk_prices(ids, grade="RAW", currency="eur") # any number of ids
156
+ res["data"] # one row per card found
157
+ res["not_found"] # ids with no card
158
+ ```
159
+
160
+ Ids are de-duplicated, then sent in chunks of your plan's bulk cap (basic 25, pro 100,
161
+ ultra 500 ids a request). The first call learns the cap from the API: an over-cap request
162
+ is refused before it is billed, and the refusal names the cap. To skip that probe, pass
163
+ `chunk_size=100`. The chunk responses are merged into one.
164
+
165
+ ## Errors
166
+
167
+ Every failure raises one exception, `FlipziError`:
168
+
169
+ ```python
170
+ from flipzi import FlipziError
171
+
172
+ try:
173
+ flipzi.sold(card_id)
174
+ except FlipziError as e:
175
+ e.status # 403
176
+ e.code # "PLAN_FEATURE_LOCKED"
177
+ e.message # "Your plan does not include 'sold_comps'. ..."
178
+ e.details # {"required_feature": ..., "your_plan": ..., "upgrade_url": ..., "next_step": ...}
179
+ e.request_id # quote it to support@flipzi.io
180
+ e.next_step # details["next_step"]
181
+ ```
182
+
183
+ It is built from the API's error body, `{"error": {code, message, details, request_id}}`.
184
+ When no response arrives at all, `status` is `0` and `code` is `NETWORK_ERROR` or `TIMEOUT`.
185
+
186
+ ## Retries
187
+
188
+ The client retries 429, 500, 502, 503 and 504 responses, and network errors, twice by
189
+ default. It waits `Retry-After` when the API sends one, and otherwise backs off
190
+ exponentially with jitter (0.5 s, 1 s, 2 s and so on, capped at 8 s).
191
+
192
+ - `QUOTA_EXCEEDED` is never retried: the monthly quota does not come back until the 1st.
193
+ - A `Retry-After` longer than `max_retry_after` (60 s) raises instead of sleeping.
194
+ - Refused requests are not billed.
195
+
196
+ ```python
197
+ Flipzi(max_retries=5, max_retry_after=120, timeout=10.0)
198
+ flipzi.request("GET", "/v1/catalog/games", max_retries=0) # per call
199
+ ```
200
+
201
+ ## Quota and rate limits
202
+
203
+ Metered responses carry your remaining units and requests in headers. The client parses them:
204
+
205
+ ```python
206
+ flipzi.price(card_id)
207
+ m = flipzi.last_response
208
+ m.quota_remaining, m.quota_limit, m.quota_period # 249876, 250000, "2026-10"
209
+ m.rate_limit_remaining, m.rate_limit_reset, m.request_id
210
+ ```
211
+
212
+ `quota_remaining` is the count when the request arrived, before its own cost. With
213
+ concurrent calls, use the hook instead, which sees every response:
214
+ `Flipzi(on_response=lambda m: print(m.quota_remaining))`. `flipzi.usage()` gives the same
215
+ numbers, per key, at no cost.
216
+
217
+ ## Options
218
+
219
+ | Option | Default | |
220
+ |---|---|---|
221
+ | `api_key` | `$FLIPZI_API_KEY` | Sent as `X-API-Key`. |
222
+ | `base_url` | `https://data.flipzi.io` | API origin. |
223
+ | `max_retries` | `2` | Retries after 429, 5xx or a network error. |
224
+ | `max_retry_after` | `60` | Longest `Retry-After` (seconds) to sleep through. |
225
+ | `timeout` | `30.0` | Seconds, per attempt. |
226
+ | `on_response` | | Called with a `ResponseMeta` after every response. |
227
+ | `http_client` | | Your own `httpx.Client` / `httpx.AsyncClient` (proxies, transports). |
228
+ | `tag_client` | `True` | Sends `X-Flipzi-Client: sdk-python/<version>` (SDK name and version only). |
229
+
230
+ Use the client as a context manager, or call `close()` (`await aclose()` for async), to
231
+ release connections.
232
+
233
+ ## Examples
234
+
235
+ - [`examples/price_my_collection.py`](examples/price_my_collection.py): values a list of
236
+ cards with quantities and grades, using bulk requests.
237
+ - [`examples/ebay_de_vs_uk.py`](examples/ebay_de_vs_uk.py): eBay Germany and UK sold
238
+ prices for one card, side by side, per grade and language.
239
+
240
+ ```sh
241
+ FLIPZI_API_KEY=fz_live_... python examples/ebay_de_vs_uk.py
242
+ ```
243
+
244
+ ## Development
245
+
246
+ ```sh
247
+ python -m venv .venv && .venv/bin/pip install -e ".[dev]"
248
+ .venv/bin/python scripts/generate.py # regenerate src/flipzi/models.py from spec/openapi.yaml
249
+ .venv/bin/python scripts/unasync.py # regenerate the sync client from the async one
250
+ .venv/bin/pytest # tests against a local mock server
251
+ FLIPZI_API_KEY=fz_live_... .venv/bin/pytest tests/test_live.py # also hits the real API (~6 units)
252
+ ```
253
+
254
+ The mock server replays real responses recorded into `tests/fixtures/` (see
255
+ `tests/fixtures/README.md`).
256
+
257
+ ## Licence
258
+
259
+ MIT. See [LICENSE](LICENSE).
flipzi-0.1.0/README.md ADDED
@@ -0,0 +1,228 @@
1
+ # flipzi
2
+
3
+ The official Python client for the [Flipzi Data API](https://flipzi.io/docs/): trading
4
+ card prices, eBay sold prices across 8 marketplaces, Cardmarket offers by condition,
5
+ price history, PSA population and market movers. It covers Pokémon (English, Japanese and
6
+ Chinese), Magic, Yu-Gi-Oh!, One Piece, Lorcana, Riftbound, Dragon Ball, Digimon, Gundam,
7
+ Star Wars: Unlimited, Flesh and Blood and more.
8
+
9
+ - Sync and async clients (`Flipzi`, `AsyncFlipzi`), built on `httpx`.
10
+ - Fully typed: responses are `TypedDict`s generated from the API's OpenAPI spec, and the package ships `py.typed`.
11
+ - Retries on 429 and 5xx with backoff, and honours `Retry-After`.
12
+ - Generators for paged endpoints, and bulk helpers that split requests to your plan's cap.
13
+ - Python 3.9+.
14
+
15
+ ```sh
16
+ pip install flipzi
17
+ ```
18
+
19
+ ## First price in three lines
20
+
21
+ ```python
22
+ from flipzi import Flipzi
23
+ flipzi = Flipzi(api_key="fz_live_...")
24
+ print(flipzi.price("0908653a-ce24-4d7e-811e-78c2935bd822")["data"]["prices"][0]["price_formatted"])
25
+ ```
26
+
27
+ Get a free key (no card needed) at [flipzi.io/account/register?product=data](https://flipzi.io/account/register?product=data).
28
+ If you leave out `api_key`, the client reads `FLIPZI_API_KEY` from the environment.
29
+
30
+ Don't have a card id? Search for one:
31
+
32
+ ```python
33
+ card = flipzi.search("charizard ex", game="pokemon")["data"][0]
34
+ card["id"], card["name"], card["set"]["name"], card["number"]
35
+ ```
36
+
37
+ Async works the same way:
38
+
39
+ ```python
40
+ import asyncio
41
+ from flipzi import AsyncFlipzi
42
+
43
+ async def main():
44
+ async with AsyncFlipzi() as flipzi:
45
+ res = await flipzi.price("0908653a-ce24-4d7e-811e-78c2935bd822")
46
+ print(res["data"]["prices"][0]["price_formatted"])
47
+
48
+ asyncio.run(main())
49
+ ```
50
+
51
+ ## Methods
52
+
53
+ Every endpoint has one method. Each returns the API's JSON body as a dict, typed with a
54
+ `TypedDict` from `flipzi.models`.
55
+
56
+ | Method | Endpoint |
57
+ |---|---|
58
+ | `health()` | `GET /v1/meta/health` (no key needed) |
59
+ | `usage()` | `GET /v1/meta/usage` (free; still answers when you are over quota) |
60
+ | `games()` | `GET /v1/catalog/games` |
61
+ | `sets(game)` / `iter_sets(game)` | `GET /v1/catalog/sets` |
62
+ | `set_cards(set_id)` / `iter_set_cards(set_id)` | `GET /v1/catalog/sets/{set_id}/cards` |
63
+ | `set_analytics(set_id, game=)` | `GET /v1/catalog/sets/{set_id}/analytics` |
64
+ | `search(q, game=, ...)` / `iter_search(...)` | `GET /v1/cards/search` |
65
+ | `card(card_id)` | `GET /v1/cards/{card_id}` |
66
+ | `lookup(pokemontcg_id)` | `GET /v1/cards/lookup` |
67
+ | `price(card_id, grade=, currency=)` | `GET /v1/cards/{card_id}/price` |
68
+ | `history(card_id, period=)` | `GET /v1/cards/{card_id}/history` |
69
+ | `sold(card_id, ...)` | `GET /v1/cards/{card_id}/sold` |
70
+ | `marketplaces(card_id, marketplace=, ...)` | `GET /v1/cards/{card_id}/marketplaces` |
71
+ | `sales(card_id, ...)` / `iter_sales(card_id, ...)` | `GET /v1/cards/{card_id}/sales` |
72
+ | `printings(card_id)` | `GET /v1/cards/{card_id}/printings` |
73
+ | `analytics(card_id, grade=)` | `GET /v1/cards/{card_id}/analytics` |
74
+ | `cardmarket(card_id, language=)` | `GET /v1/cards/{card_id}/cardmarket` |
75
+ | `cardmarket_history(card_id, days=)` | `GET /v1/cards/{card_id}/cardmarket/history` |
76
+ | `population(card_id)` | `GET /v1/cards/{card_id}/population` |
77
+ | `updates(since)` / `iter_updates(since)` | `GET /v1/cards/updates` |
78
+ | `movers(game, window=, direction=)` | `GET /v1/market/movers` |
79
+ | `sealed_comparisons(game=, set=)` | `GET /v1/sealed/comparisons` |
80
+ | `sealed_comparison(slug)` | `GET /v1/sealed/comparisons/{slug}` |
81
+ | `sealed_cardmarket(sealed_id)` | `GET /v1/sealed/{sealed_id}/cardmarket` |
82
+ | `bulk_prices(ids, grade=, currency=)` | `POST /v1/cards/bulk` |
83
+ | `bulk_analytics(ids, ...)` | `POST /v1/cards/bulk/analytics` |
84
+ | `bulk_cardmarket(ids, language=)` | `POST /v1/cards/bulk/cardmarket` |
85
+ | `request(method, path, params, json)` | anything else |
86
+
87
+ Keyword arguments are the API's own parameter names (`page_size`, `grade`, `marketplace`),
88
+ so the [API reference](https://flipzi.io/docs/) applies word for word. Which plan each
89
+ endpoint needs, and what it costs in units, is listed there.
90
+
91
+ ## Enums
92
+
93
+ ```python
94
+ from flipzi import Marketplace, Condition, Currency, Game, Finish, Period, grade
95
+
96
+ flipzi.sold(card_id, marketplace=Marketplace.EBAY_DE, condition=Condition.NEAR_MINT)
97
+ flipzi.price(card_id, grade=grade("PSA", 10), currency=Currency.USD) # grade "PSA_10"
98
+ ```
99
+
100
+ Each enum is a `str` Enum, so `Marketplace.EBAY_DE == "ebay_de"`, and plain strings work
101
+ everywhere. Each also has a `Literal` alias (`MarketplaceLiteral` and so on) in
102
+ `flipzi.enums`. Grades are open-ended strings (`RAW`, `PSA_10`, `BGS_9.5`): build one with
103
+ `grade()`.
104
+
105
+ ## Pagination
106
+
107
+ ```python
108
+ for s in flipzi.iter_sets("pokemon"):
109
+ print(s["set_id"], s["name"])
110
+
111
+ # Every price that changed in the last hour, following the cursor.
112
+ from datetime import datetime, timedelta, timezone
113
+ since = (datetime.now(timezone.utc) - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%SZ")
114
+ for change in flipzi.iter_updates(since):
115
+ print(change["card_id"], change["grade"], change["price_cents"])
116
+ ```
117
+
118
+ Async: `async for s in flipzi.iter_sets("pokemon")`. Pass `max_items=n` to stop early.
119
+ Every page is one request and is billed as one.
120
+
121
+ ## Bulk
122
+
123
+ ```python
124
+ res = flipzi.bulk_prices(ids, grade="RAW", currency="eur") # any number of ids
125
+ res["data"] # one row per card found
126
+ res["not_found"] # ids with no card
127
+ ```
128
+
129
+ Ids are de-duplicated, then sent in chunks of your plan's bulk cap (basic 25, pro 100,
130
+ ultra 500 ids a request). The first call learns the cap from the API: an over-cap request
131
+ is refused before it is billed, and the refusal names the cap. To skip that probe, pass
132
+ `chunk_size=100`. The chunk responses are merged into one.
133
+
134
+ ## Errors
135
+
136
+ Every failure raises one exception, `FlipziError`:
137
+
138
+ ```python
139
+ from flipzi import FlipziError
140
+
141
+ try:
142
+ flipzi.sold(card_id)
143
+ except FlipziError as e:
144
+ e.status # 403
145
+ e.code # "PLAN_FEATURE_LOCKED"
146
+ e.message # "Your plan does not include 'sold_comps'. ..."
147
+ e.details # {"required_feature": ..., "your_plan": ..., "upgrade_url": ..., "next_step": ...}
148
+ e.request_id # quote it to support@flipzi.io
149
+ e.next_step # details["next_step"]
150
+ ```
151
+
152
+ It is built from the API's error body, `{"error": {code, message, details, request_id}}`.
153
+ When no response arrives at all, `status` is `0` and `code` is `NETWORK_ERROR` or `TIMEOUT`.
154
+
155
+ ## Retries
156
+
157
+ The client retries 429, 500, 502, 503 and 504 responses, and network errors, twice by
158
+ default. It waits `Retry-After` when the API sends one, and otherwise backs off
159
+ exponentially with jitter (0.5 s, 1 s, 2 s and so on, capped at 8 s).
160
+
161
+ - `QUOTA_EXCEEDED` is never retried: the monthly quota does not come back until the 1st.
162
+ - A `Retry-After` longer than `max_retry_after` (60 s) raises instead of sleeping.
163
+ - Refused requests are not billed.
164
+
165
+ ```python
166
+ Flipzi(max_retries=5, max_retry_after=120, timeout=10.0)
167
+ flipzi.request("GET", "/v1/catalog/games", max_retries=0) # per call
168
+ ```
169
+
170
+ ## Quota and rate limits
171
+
172
+ Metered responses carry your remaining units and requests in headers. The client parses them:
173
+
174
+ ```python
175
+ flipzi.price(card_id)
176
+ m = flipzi.last_response
177
+ m.quota_remaining, m.quota_limit, m.quota_period # 249876, 250000, "2026-10"
178
+ m.rate_limit_remaining, m.rate_limit_reset, m.request_id
179
+ ```
180
+
181
+ `quota_remaining` is the count when the request arrived, before its own cost. With
182
+ concurrent calls, use the hook instead, which sees every response:
183
+ `Flipzi(on_response=lambda m: print(m.quota_remaining))`. `flipzi.usage()` gives the same
184
+ numbers, per key, at no cost.
185
+
186
+ ## Options
187
+
188
+ | Option | Default | |
189
+ |---|---|---|
190
+ | `api_key` | `$FLIPZI_API_KEY` | Sent as `X-API-Key`. |
191
+ | `base_url` | `https://data.flipzi.io` | API origin. |
192
+ | `max_retries` | `2` | Retries after 429, 5xx or a network error. |
193
+ | `max_retry_after` | `60` | Longest `Retry-After` (seconds) to sleep through. |
194
+ | `timeout` | `30.0` | Seconds, per attempt. |
195
+ | `on_response` | | Called with a `ResponseMeta` after every response. |
196
+ | `http_client` | | Your own `httpx.Client` / `httpx.AsyncClient` (proxies, transports). |
197
+ | `tag_client` | `True` | Sends `X-Flipzi-Client: sdk-python/<version>` (SDK name and version only). |
198
+
199
+ Use the client as a context manager, or call `close()` (`await aclose()` for async), to
200
+ release connections.
201
+
202
+ ## Examples
203
+
204
+ - [`examples/price_my_collection.py`](examples/price_my_collection.py): values a list of
205
+ cards with quantities and grades, using bulk requests.
206
+ - [`examples/ebay_de_vs_uk.py`](examples/ebay_de_vs_uk.py): eBay Germany and UK sold
207
+ prices for one card, side by side, per grade and language.
208
+
209
+ ```sh
210
+ FLIPZI_API_KEY=fz_live_... python examples/ebay_de_vs_uk.py
211
+ ```
212
+
213
+ ## Development
214
+
215
+ ```sh
216
+ python -m venv .venv && .venv/bin/pip install -e ".[dev]"
217
+ .venv/bin/python scripts/generate.py # regenerate src/flipzi/models.py from spec/openapi.yaml
218
+ .venv/bin/python scripts/unasync.py # regenerate the sync client from the async one
219
+ .venv/bin/pytest # tests against a local mock server
220
+ FLIPZI_API_KEY=fz_live_... .venv/bin/pytest tests/test_live.py # also hits the real API (~6 units)
221
+ ```
222
+
223
+ The mock server replays real responses recorded into `tests/fixtures/` (see
224
+ `tests/fixtures/README.md`).
225
+
226
+ ## Licence
227
+
228
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,35 @@
1
+ """eBay DE vs UK sold prices for one card, side by side, per grade and language.
2
+
3
+ FLIPZI_API_KEY=fz_live_... python examples/ebay_de_vs_uk.py [card_id]
4
+
5
+ One marketplaces() call (1 unit) returns every eBay marketplace; prices are
6
+ converted to the currency you ask for, and `native` keeps the sold currency.
7
+ Needs a plan with sold comps (pro and above).
8
+ """
9
+ import os
10
+ import sys
11
+
12
+ from flipzi import Flipzi, Marketplace
13
+
14
+ card_id = sys.argv[1] if len(sys.argv) > 1 else "0908653a-ce24-4d7e-811e-78c2935bd822" # Charizard ex, Obsidian Flames 125
15
+ PICK = [Marketplace.EBAY_DE, Marketplace.EBAY_UK]
16
+
17
+ with Flipzi(base_url=os.environ.get("FLIPZI_BASE_URL")) as flipzi: # key from FLIPZI_API_KEY
18
+ data = flipzi.marketplaces(card_id, currency="eur")["data"]
19
+
20
+ print(f"Card {card_id}, prices in EUR (native currency in brackets)\n")
21
+ print("grade lang " + "".join(f"{m.value:<26}" for m in PICK))
22
+ for g in data.get("grades", []):
23
+ rows = g.get("marketplaces", [])
24
+ for lang in dict.fromkeys(r["language"] for r in rows):
25
+ picked = [next((r for r in rows if r["marketplace"] == m and r["language"] == lang), None) for m in PICK]
26
+ if not any(picked):
27
+ continue
28
+ cells = []
29
+ for r in picked:
30
+ if r is None:
31
+ cells.append(f"{'-':<26}")
32
+ else:
33
+ native = f"{r['native']['price_minor'] / 100:.2f} {r['native']['currency']}"
34
+ cells.append(f"{r['price_cents'] / 100:.2f} ({native}, n={r['comps_30d']})".ljust(26))
35
+ print(f"{g['grade']:<9}{lang:<6}" + "".join(cells))
@@ -0,0 +1,51 @@
1
+ """Price my collection: value a list of cards, with quantities and grades.
2
+
3
+ FLIPZI_API_KEY=fz_live_... python examples/price_my_collection.py
4
+
5
+ One bulk request per grade (1 unit per card), split to your plan's bulk cap.
6
+ On the free sandbox plan, which has no bulk endpoint, it falls back to one
7
+ price() call per card.
8
+ """
9
+ import os
10
+ from collections import defaultdict
11
+
12
+ from flipzi import Flipzi, FlipziError
13
+
14
+ COLLECTION = [
15
+ {"card_id": "0908653a-ce24-4d7e-811e-78c2935bd822", "qty": 2}, # Charizard ex, Obsidian Flames 125
16
+ {"card_id": "bae3729e-4d27-4c7e-adf6-b7a6477552fe", "qty": 1}, # Charizard ex, Obsidian Flames 215
17
+ {"card_id": "bae3729e-4d27-4c7e-adf6-b7a6477552fe", "qty": 1, "grade": "PSA_10"},
18
+ ]
19
+ CURRENCY = "eur"
20
+
21
+
22
+ def prices_for(flipzi, grade, ids):
23
+ """card_id -> the price object for this grade."""
24
+ try:
25
+ res = flipzi.bulk_prices(ids, grade=grade, currency=CURRENCY)
26
+ rows = {row["card_id"]: row["prices"] for row in res["data"]}
27
+ except FlipziError as e:
28
+ if e.code != "PLAN_FEATURE_LOCKED":
29
+ raise
30
+ rows = {i: flipzi.price(i, grade=grade, currency=CURRENCY)["data"]["prices"] for i in ids}
31
+ return {cid: next((p for p in prices if p["grade"] == grade), None) for cid, prices in rows.items()}
32
+
33
+
34
+ with Flipzi(base_url=os.environ.get("FLIPZI_BASE_URL")) as flipzi: # key from FLIPZI_API_KEY
35
+ by_grade = defaultdict(list)
36
+ for item in COLLECTION:
37
+ by_grade[item.get("grade", "RAW")].append(item["card_id"])
38
+
39
+ total = 0
40
+ for grade, ids in by_grade.items():
41
+ prices = prices_for(flipzi, grade, list(dict.fromkeys(ids)))
42
+ for item in (i for i in COLLECTION if i.get("grade", "RAW") == grade):
43
+ p = prices.get(item["card_id"])
44
+ line = p["price_cents"] * item["qty"] if p else 0
45
+ total += line
46
+ each = f"{p['price_cents'] / 100:.2f} each {line / 100:.2f}" if p else "no price"
47
+ print(f"{item['card_id']} {grade:<7} x{item['qty']} {each}")
48
+
49
+ print(f"Total: {total / 100:.2f} {CURRENCY.upper()}")
50
+ left = flipzi.last_response.quota_remaining if flipzi.last_response else None
51
+ print(f"Units left this month: {left if left is not None else 'n/a'}")
@@ -0,0 +1,51 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "flipzi"
7
+ version = "0.1.0"
8
+ description = "Official Python client for the Flipzi Data API: trading card prices, eBay sold comps, Cardmarket conditions, price history and market movers for Pokémon, Magic, Yu-Gi-Oh!, One Piece, Lorcana and more."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Flipzi", email = "hello@flipzi.io" }]
13
+ requires-python = ">=3.9"
14
+ dependencies = ["httpx>=0.23,<1"]
15
+ keywords = ["flipzi", "tcg", "trading cards", "card prices", "pokemon", "pokemon tcg", "mtg", "yugioh", "one piece", "lorcana", "ebay", "sold prices", "cardmarket", "api client", "sdk"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: OS Independent",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.9",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Typing :: Typed",
27
+ "Topic :: Software Development :: Libraries",
28
+ ]
29
+
30
+ [project.urls]
31
+ Homepage = "https://flipzi.io/docs/"
32
+ Documentation = "https://flipzi.io/docs/"
33
+
34
+ [project.optional-dependencies]
35
+ dev = ["pytest>=7", "pyyaml>=6", "mypy>=1.5", "build>=1", "twine>=5"]
36
+
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["src/flipzi"]
39
+
40
+ [tool.hatch.build.targets.sdist]
41
+ include = ["src/flipzi", "tests", "examples", "spec", "scripts", "README.md", "CHANGELOG.md", "LICENSE"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
45
+ markers = ["live: hits the real API; runs only when FLIPZI_API_KEY is set"]
46
+
47
+ [tool.mypy]
48
+ # mypy no longer targets 3.9; tests/test_py39_syntax.py checks the 3.9 grammar.
49
+ python_version = "3.10"
50
+ strict = true
51
+ files = ["src/flipzi"]