Calendar Weekly Context API

Calendar Weekly Context API

API udostępnia derived payload kalendarzowy pod późniejsze użycie w zbiorczym payloadzie LLM.

To API:

• nie generuje summary tekstowych
• nie wywołuje LLM
• zwraca tylko dane z kalendarza i agregaty rule-based

Endpoint

/calendar/merged/api/weekly-context.php

Tryby zapytania

1. Query po `week_iso`

/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14

2. Query po dokładnym zakresie dat

/calendar/merged/api/weekly-context.php?market=PL&date_from=2026-03-30&date_to=2026-04-05

Parametry

Wymagane

• market

- kod rynku, np. PL, CO, BA, GB - alias UK jest akceptowany i normalizowany do GB

Wariant A: tydzień ISO

• week_iso

- format: YYYY-Www - przykład: 2026-W14

Wariant B: dokładny zakres

• date_from

- format: YYYY-MM-DD

• date_to

- format: YYYY-MM-DD

Zasady dla zakresu dat:

• date_to >= date_from
• obie daty muszą należeć do tego samego roku kalendarzowego

Opcjonalne

• save=1

- działa tylko dla wariantu week_iso - zapisuje payload do: - data/calendar/weekly_llm_inputs/{MARKET}/{YEAR}/{WEEK_ISO}.json

• include

- opcjonalny filtr odpowiedzi - dozwolone wartości: - all - flights - travel - domyślnie: all

Przykłady

Week ISO

curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14"

Week ISO + save

curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14&save=1"

Exact range

curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&date_from=2026-03-30&date_to=2026-04-05"

Flights only

curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14&include=flights"

Travel only

curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14&include=travel"

Response Shape

Top-level:

{
  "market": "PL",
  "summary_scope": "week_market",
  "input_version": "weekly_llm_payload_v1",
  "schema_version": "weekly_calendar_context_v1",
  "generated_at": "2026-04-03T00:00:00Z",
  "week_iso": "2026-W14",
  "date_from": "2026-03-30",
  "date_to": "2026-04-05",
  "calendar_context": {},
  "commercial_calendar_context": null,
  "ads_context": null,
  "product_context": null,
  "sales_context": null,
  "pricing_context": null,
  "search_context": null,
  "supply_context": null,
  "confidence_inputs": {},
  "llm_constraints": {}
}

`summary_scope`

Możliwe wartości:

• week_market

- gdy zapytanie dotyczy pełnego tygodnia ISO

• date_range_market

- gdy zapytanie dotyczy arbitralnego zakresu dat

`include`

`include=all`

Zwraca pełny payload.

`include=flights`

Zostawia:

• metadane top-level
• minimalny kontekst eventów
• commercial_calendar_context.payday.flights_signal dla UK
• product_impact.flights
• priority_events.flights
• aggregated_impacts.flights
• time_off, timing_effects i podstawowy travel_signal, żeby nie stracić kontekstu lotniczego

`include=travel`

Zostawia:

• metadane top-level
• commercial_calendar_context.payday.travel_signal dla UK
• time_off
• travel_signal
• timing_effects
• week_flags
• time_off_summary
• dominant_patterns

Pomija agregaty stricte produktowe.

Błędy

`invalid_market`

Brak parametru market albo nieobsługiwany kod rynku.

`missing_range`

Brak:

• week_iso

oraz jednocześnie brak:

• date_from
• date_to

`invalid_week_iso`

week_iso nie ma formatu YYYY-Www.

`invalid_date_range`

Zakres dat jest niepoprawny:

• zły format
• date_to < date_from
• daty w różnych latach

`invalid_include`

include nie jest jedną z dozwolonych wartości:

• all
• flights
• travel

Implementacja

Endpoint:

• [weekly-context.php](/var/www/news.netkam.online/calendar/merged/api/weekly-context.php)

Builder:

• [weekly_calendar_context.php](/var/www/news.netkam.online/calendar/merged/lib/calendar/summary/weekly_calendar_context.php)

Preview UI:

• [weekly-contexts.php](/var/www/news.netkam.online/calendar/merged/weekly-contexts.php)