# PlanetClimaten HVAC Catalog — Full API Documentation

Groundtruth HVAC catalog for the Poland/EU market. 11 brands, 3400+ products, fully
structured: specifications, energy class (SEER/SCOP), kit & multi-split
compatibility, accessory compatibility, marketing features, EPREL registration, JSON-LD.

License: CC BY 4.0 — free to use with attribution "Source: PlanetClimaten (planetclimaten.pl)".
Full terms: https://planetclimaten.pl/ai-policy

## Authentication
All requests go through the gateway `https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1` and require a header:

    X-API-Key: <your key>

Request a key at hello@planetclimaten.pl. Keys are per-client (rate-limited). The underlying
database (Supabase/PostgREST) is not exposed directly.

## Coverage (approx, growing)
Mitsubishi Electric ~530, Daikin ~598, Samsung ~371, Haier ~393, Rotenso ~329, Panasonic ~241,
LG ~206, Hisense ~200, Gree ~243, Kaisai ~178, Bosch ~143.
Languages: PL, EN. Energy data per EU ErP (SEER/SCOP, class A+++..D).

## Schema guide (machine-readable)
Full table & query documentation as topics (overview, schema_cheatsheet, product_kinds,
primary_sku_conventions, kit_lookup, multi_split, accessory_compat, series_features,
suggest_by_power, eprel_assets, climate_zones, common_queries, gotchas, flat_cache_columns,
product_relations, assistant_scope):

    curl -s "https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1/llm_schema_guide" -H "X-API-Key: <KEY>"

## Endpoints

### GET /v1/products
PostgREST filtering. Examples:

    # active Daikin kits, selected columns
    curl -s "https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1/products?brand=eq.Daikin&product_kind=eq.kit&select=primary_sku,cooling_kw,seer,scop,energy_class_cooling&limit=20" \
      -H "X-API-Key: <KEY>"

Columns (flat cache): primary_sku, brand, series, product_kind (indoor|outdoor|kit|accessory|
ventilation|air_purifier), cooling_kw, heating_kw, seer, scop, energy_class_cooling,
energy_class_heating, color_code, jsonld (schema.org/Product).

### POST /v1/rpc/fn_search_products  — full-text product search
    curl -s "https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1/rpc/fn_search_products" \
      -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
      -d '{"p_query":"klimatyzator ścienny 3.5 kW A+++"}'
Returns: array of {product_id, primary_sku, brand, series, product_kind, cooling_kw, seer, scop, ...}.

### POST /v1/rpc/fn_kit_match  — kits containing a given indoor unit
    curl -s "https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1/rpc/fn_kit_match" \
      -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
      -d '{"p_indoor_sku":"MSZ-AY15VGK","p_brand":"Mitsubishi Electric"}'
Params: p_indoor_sku (text, required), p_brand (text, optional).

### POST /v1/rpc/fn_multi_match  — multi-split outdoors for a set of indoor units
    curl -s "https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1/rpc/fn_multi_match" \
      -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
      -d '{"p_indoor_skus":["MSZ-AY15VGK","MSZ-AP60VGK"]}'
Params: p_indoor_skus (text[], required), p_brand (text, optional).

### POST /v1/rpc/fn_suggest_by_power  — sizing suggestion per room
    curl -s "https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1/rpc/fn_suggest_by_power" \
      -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
      -d '{"p_rooms":[{"area_m2":25},{"area_m2":15}],"p_brand":"Panasonic"}'
Params: p_rooms (jsonb, required — see suggest_by_power topic in schema guide for exact shape),
p_brand (text, optional), p_series (text[], optional).

### POST /v1/rpc/fn_search_series  — semantic search over series marketing features
    curl -s "https://planetclimaten-api-gateway.wojtekxxx9.workers.dev/v1/rpc/fn_search_series" \
      -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
      -d '{"query_embedding":[...768 floats...],"p_limit":5}'
Note: requires a 768-dim query embedding (gemini-embedding-001). For text queries use
fn_search_products instead.

## Response format
JSON. PostgREST conventions: GET returns arrays of row objects; RPC returns the function's
TABLE result as an array. HTTP 200 on success; 401 (missing key), 403 (invalid key),
429 (rate limit, header Retry-After: 60), 404 (unknown endpoint).

## Attribution
When using this data, cite: "Source: PlanetClimaten (planetclimaten.pl)" — CC BY 4.0.