endpoint

Read-only HTTP API over catalog database generated by converter.

Install

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Run

export ENDPOINT_CATALOG_DB='sqlite:///../converter/data/catalog.db'
./.venv/bin/python main.py

Public endpoints

• GET /healthz
• GET /products
• GET /products/count
• GET /products/{canonical_product_id}
• GET /products/{canonical_product_id}/sources
• GET /products/{canonical_product_id}/snapshots
• GET /products/{canonical_product_id}/dynamics
• GET /products/common/count
• GET /categories
• GET /categories/{category_id}
• GET /settlements
• GET /settlements/{settlement_id}
• GET /sync/cursors

All routes are read-only (GET only).

Products count endpoint

GET /products/count

Query params:

• store (repeatable): фильтр по магазину (parser_name)
• region (repeatable): фильтр по региону (catalog_settlements.region_normalized/region)

Response:

• products_count: количество уникальных товаров (COUNT(DISTINCT canonical_product_id))

Common products count endpoint

GET /products/common/count

Query params:

• scope: stores | regions
• store (repeatable): optional for scope=stores and scope=regions; если не передан при scope=stores, берутся все магазины
• region (repeatable): optional filter for scope=stores; for scope=regions limits comparison to selected regions

Dynamics endpoint

GET /products/{canonical_product_id}/dynamics

Required query params:

• parser_name
• source_id
• field: price, discount_price, loyal_price, available_count
• date_from (ISO8601 with timezone)
• date_to (ISO8601 with timezone)
• interval: 1h, 6h, 1d, 7d

Response shape:

{
  "dates": ["2026-02-01T00:00:00Z", "2026-02-02T00:00:00Z"],
  "values": [99.9, null],
  "meta": {
    "canonical_product_id": "prod-1",
    "parser_name": "fixprice",
    "source_id": "receiver:run-1:1",
    "field": "price",
    "interval": "1d",
    "date_from": "2026-02-01T00:00:00Z",
    "date_to": "2026-02-02T23:59:59Z"
  }
}

dynamics учитывает интервальный контракт converter: если у snapshot есть valid_from_at/valid_to_at, значение распространяется на весь интервал. Для старых данных без этих колонок используется observed_at.

Recommended DB index

CREATE INDEX idx_catalog_snapshots_series_interval
ON catalog_product_snapshots(
  canonical_product_id,
  parser_name,
  source_id,
  valid_from_at,
  valid_to_at,
  observed_at
);