cnovatech-datamarket
Official Python SDK for the Cnovatech Data Market API: daily prices, availability and assortment of more than 150,000 products across 240+ online supermarkets in 23 Brazilian states.
- Synchronous and asynchronous clients with the same surface
- Every response carries its quota cost; pagination can be capped by cost
- Retries only where a repeat cannot be billed twice
- Typed end to end: pydantic models,
py.typed,mypy --strict
Status: 0.x. Every read endpoint of the API is implemented, validated against production and tested offline against recorded responses. Until 1.0 a minor release may change the public surface; every such change is listed in the changelog.
Installation
pip install cnovatech-datamarket
Add [pandas] for to_dataframe() on list responses. Python 3.10 or newer.
Quick start
from cnovatech.datamarket import DataMarket
client = DataMarket() # reads DATAMARKET_API_KEY
product = client.products.get("7894900011517", state="SP")
product.product_name # "Refrigerante Coca-Cola 2L"
product.market.median_price # 9.49
product.offers[0].store_name # "Supermercado Modelo"
product.offers[0].price # 8.99
product.offers[0].available # True
product.usage.query_cost # 1
product.usage.remaining # 994
Get a key at https://datamarket.cnovatech.com.br. client.health() checks
the API without a key and without cost.
The first lookup of a product the API has not cached yet can take up to 90 seconds; after that it answers in under a second. The default timeout allows for it.
Quota
Every call is billed in quota units, and every response says what it cost:
page = client.products.catalog(search="azeite", limit=50)
page.usage.query_cost # 1
page.usage.remaining # 993
client.usage.spent # 2, through this client
Paginated responses can be walked page by page or item by item, with a ceiling on how much to spend:
position = client.stores.market_position(store_id, limit=1000) # 8 units per page
position.meta.pages # 4
position.estimate_remaining_cost() # 24, for the three pages not fetched yet
items = list(position.iter_all(max_units=40))
items[0].product_name # "Azeite Extra Virgem 500ml"
items[0].price_position # "above"
iter_all never requests again the page you already paid for. It stops quietly
at max_pages and raises BudgetExceededError before a page that would cross
max_units. To refuse any single call above a budget, build the client with
DataMarket(max_units_per_request=20).
Stores and competitors
store = client.stores.find("Supermercado Modelo", state="SP") # 1 unit
store.store_id # "0f8c7d2e-6b1a-4f3e-9c5d-2a7b8e1f4c63"
competitors = client.stores.competitors(store.store_id, limit=5) # 1 unit each
competitors.data[0].store_name # "Mercado Vizinho"
competitors.data[0].overlap_pct # 62.5, share of the assortment in common
comparison = client.stores.compare(store.store_id, competitors.data[0].store_id)
comparison.data[0].product_name # "Azeite Extra Virgem 500ml"
comparison.data[0].price_position # "above"
comparison.data[0].price_diff_pct # 12.3
Errors
from cnovatech.datamarket import DataMarket, errors
client = DataMarket()
try:
product = client.products.get("0000000000000")
except errors.EANNotFoundError as exc:
exc.hint # what the API suggests doing next
except errors.QuotaExceededError as exc:
exc.code # "monthly_limit_exceeded"
exc.upgrade_url # where to change plan
except errors.APITimeoutError:
... # may have been billed; check client.account.usage() before repeating
except errors.DataMarketError as exc:
str(exc) # "HTTP 503 service_unavailable: ... [correlation_id=...]"; never the key
Connection errors, 502/503 and the per-minute 429 are retried with backoff. Read timeouts, 504 and quota errors never are: the request may already have been processed and billed.
Async
import asyncio
from cnovatech.datamarket import AsyncDataMarket
async def main() -> None:
async with AsyncDataMarket() as client:
product = await client.products.get("7894900011517")
product.market.median_price # 9.49
asyncio.run(main())
pandas
assortment = client.stores.assortment(store.store_id, limit=1000)
frame = assortment.to_dataframe() # one row per item; usage and meta as columns
Configuration
| Argument | Environment variable | Default |
|---|---|---|
api_key |
DATAMARKET_API_KEY |
required, except for health() |
base_url |
DATAMARKET_BASE_URL |
https://datamarket.cnovatech.com.br |
timeout |
150 s read timeout; pass httpx.Timeout to set every phase. Applies per request, also through your own http_client |
|
max_retries |
2 | |
max_units_per_request |
no limit | |
http_client |
your own httpx.Client, for proxies, certificates or a shared pool; never closed, redirects never followed |
Guides
- Quota and costs: the tariff, what each response reports, estimates and caps.
- Pagination: pages, walks,
max_pagesandmax_units. - Errors: the hierarchy, what is retried, how to handle each case.
- Recipes: coverage of a list, competitors, exports to pandas, when to use
getand when to export.
Logging
The SDK logs through the standard logging module under the cnovatech
namespace and installs no handler of its own. At DEBUG it records each request's
method, path, status and duration; retries are logged at INFO, and a WARNING is
emitted when the remaining quota drops below 10%. Keys, headers and bodies are
never logged. The httpx logger, if the application enables it at INFO, prints
the full URL with its query string; the key is sent as a header and is not in it.
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("cnovatech").setLevel(logging.DEBUG)
Resources
| Resource | Methods | Cost |
|---|---|---|
client.products |
catalog, departments, brands, by_brand, get, price_history |
1 unit |
coverage |
ceil(codes / 250) units; up to 500 codes per call | |
client.stores |
list, find |
1 unit |
competitors, competitiveness |
1 unit per competitor | |
assortment, compare, market_position, opportunities |
ceil(rows / 250) × 2 units per page | |
client.brands |
stores |
1 unit |
client.account |
profile, usage, logs, api_keys |
free |
client |
health, usage, rate_limit, close |
free |
Each method's docstring states its cost. The API reference is at https://datamarket.cnovatech.com.br/redoc.
Support
- Issues and feature requests: https://github.com/cnovatech-br/sdks/issues
- Email: suporte@cnovatech.com.br
License
MIT. The API terms of use are at https://cnovatech.com.br/termos-de-uso.
Metadata
Release files for cnovatech-datamarket 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cnovatech_datamarket-0.1.0.tar.gz | 74.8 kB | With provenance | Details for cnovatech_datamarket-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cnovatech_datamarket-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for cnovatech_datamarket-0.1.0-py3-none-any.whl |
Total release size: 107.3 kB
Release files / cnovatech_datamarket-0.1.0.tar.gz
| Download URL | cnovatech_datamarket-0.1.0.tar.gz |
|---|---|
| Size | 74.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ea29d77aa056baa0a2b51a873648caa8c61cca7a160606823463ca691cdf8baf
|
|
BLAKE2b-256 checksum How to use checksums |
8a29de8cb9487c0bff51867bc7e7691769c7041cfd0eba8a174223547edb1f93
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / cnovatech_datamarket-0.1.0-py3-none-any.whl
| Download URL | cnovatech_datamarket-0.1.0-py3-none-any.whl |
|---|---|
| Size | 32.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
25f633d604ea3124377a9492d08c653944c16c4b1a8bbca7067186fc3d5520f6
|
|
BLAKE2b-256 checksum How to use checksums |
1d54bbda9d54a222ed72bdfe36964f6e76c9af7e3e7b0408ac21637418689658
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for cnovatech-datamarket 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cnovatech_datamarket-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.