# PlanningValue

Informacje planistyczne o działce w jednym żądaniu: odpowiedzi o planie ogólnym, MPZP i WZ (każda jako pełne LayerAnswer z własnym coverage, source i note) oraz stan planowania gminy. Bez stwierdzenia „brak planu” bez wskazania rodzaju planu i źródła.

Layer keys: `planning`.

## Cost and inputs

`x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md).

Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty.

## Value schema

| Field | Required | Schema / constraints | Description |
| --- | --- | --- | --- |
| `gmina` | yes | `{"properties": {"as_of": {"format": "date", "type": "string"}, "gmina_name": {"type": "string"}, "gmina_teryt": {"description": "Kod gminy administracyjnej z ostatnią cyfrą 1, 2 lub 3.", "pattern": "^[0-9]{6}[123]$", "type": "string"}, "mpzp_count": {"type": ["integer", "null"]}, "mpzp_coverage_pct": {"type": ["number", "null"]}, "pog_adopted_on": {"format": "date", "type": ["string", "null"]}, "pog_effective_from": {"format": "date", "type": ["string", "null"]}, "pog_resolution_url": {"type": ["string", "null"]}, "pog_status": {"enum": ["draft", "adopted", "in_force", "none", "unknown"], "type": "string"}, "sources": {"items": {"$ref": "./envelope.json#/$defs/SourceRef"}, "type": "array"}, "studium_expired": {"type": ["boolean", "null"]}, "wz_regime": {"type": ["string", "null"]}}, "required": ["gmina_teryt", "gmina_name", "pog_status", "as_of", "sources"], "type": "object"}` | not specified in the source contract |
| `mpzp` | yes | `{"additionalProperties": false, "allOf": [{"else": {"properties": {"value": {"type": "object"}}}, "if": {"properties": {"coverage": {"enum": ["not_covered", "not_computed"]}}}, "then": {"properties": {"value": {"type": "null"}}}}, {"if": {"properties": {"coverage": {"enum": ["covered", "covered_no_data"]}, "layer": {"const": "mpzp"}}}, "then": {"properties": {"value": {"$ref": "#/$defs/MpzpValue"}}}}], "properties": {"as_of": {"format": "date", "type": ["string", "null"]}, "basis": {"description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": ["string", "null"]}, "confidence": {"maximum": 1, "minimum": 0, "type": "number"}, "coverage": {"$ref": "#/$defs/Coverage"}, "hash": {"description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": ["string", "null"]}, "layer": {"$ref": "#/$defs/LayerKey"}, "layer_version": {"description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string"}, "licence": {"$ref": "#/$defs/Licence"}, "method": {"$ref": "#/$defs/Method"}, "note": {"description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string"}, "scope": {"$ref": "#/$defs/Scope"}, "source": {"$ref": "#/$defs/SourceRef"}, "threshold": {"maximum": 1, "minimum": 0, "type": "number"}, "value": {"description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": ["object", "null"]}}, "required": ["layer", "coverage", "value", "note", "source", "as_of", "layer_version"], "type": "object"}` | Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml). |
| `pog` | yes | `{"additionalProperties": false, "allOf": [{"else": {"properties": {"value": {"type": "object"}}}, "if": {"properties": {"coverage": {"enum": ["not_covered", "not_computed"]}}}, "then": {"properties": {"value": {"type": "null"}}}}, {"if": {"properties": {"coverage": {"enum": ["covered", "covered_no_data"]}, "layer": {"const": "mpzp"}}}, "then": {"properties": {"value": {"$ref": "#/$defs/MpzpValue"}}}}], "properties": {"as_of": {"format": "date", "type": ["string", "null"]}, "basis": {"description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": ["string", "null"]}, "confidence": {"maximum": 1, "minimum": 0, "type": "number"}, "coverage": {"$ref": "#/$defs/Coverage"}, "hash": {"description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": ["string", "null"]}, "layer": {"$ref": "#/$defs/LayerKey"}, "layer_version": {"description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string"}, "licence": {"$ref": "#/$defs/Licence"}, "method": {"$ref": "#/$defs/Method"}, "note": {"description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string"}, "scope": {"$ref": "#/$defs/Scope"}, "source": {"$ref": "#/$defs/SourceRef"}, "threshold": {"maximum": 1, "minimum": 0, "type": "number"}, "value": {"description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": ["object", "null"]}}, "required": ["layer", "coverage", "value", "note", "source", "as_of", "layer_version"], "type": "object"}` | Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml). |
| `wz` | yes | `{"additionalProperties": false, "allOf": [{"else": {"properties": {"value": {"type": "object"}}}, "if": {"properties": {"coverage": {"enum": ["not_covered", "not_computed"]}}}, "then": {"properties": {"value": {"type": "null"}}}}, {"if": {"properties": {"coverage": {"enum": ["covered", "covered_no_data"]}, "layer": {"const": "mpzp"}}}, "then": {"properties": {"value": {"$ref": "#/$defs/MpzpValue"}}}}], "properties": {"as_of": {"format": "date", "type": ["string", "null"]}, "basis": {"description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": ["string", "null"]}, "confidence": {"maximum": 1, "minimum": 0, "type": "number"}, "coverage": {"$ref": "#/$defs/Coverage"}, "hash": {"description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": ["string", "null"]}, "layer": {"$ref": "#/$defs/LayerKey"}, "layer_version": {"description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string"}, "licence": {"$ref": "#/$defs/Licence"}, "method": {"$ref": "#/$defs/Method"}, "note": {"description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string"}, "scope": {"$ref": "#/$defs/Scope"}, "source": {"$ref": "#/$defs/SourceRef"}, "threshold": {"maximum": 1, "minimum": 0, "type": "number"}, "value": {"description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": ["object", "null"]}}, "required": ["layer", "coverage", "value", "note", "source", "as_of", "layer_version"], "type": "object"}` | Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml). |

```json
{
  "description": "Informacje planistyczne o działce w jednym żądaniu: odpowiedzi o planie ogólnym, MPZP i WZ (każda jako pełne LayerAnswer z własnym coverage, source i note) oraz stan planowania gminy. Bez stwierdzenia „brak planu” bez wskazania rodzaju planu i źródła.",
  "properties": {
    "gmina": {
      "$ref": "#/components/schemas/GminaPlanning"
    },
    "mpzp": {
      "$ref": "./envelope.json#/$defs/LayerAnswer"
    },
    "pog": {
      "$ref": "./envelope.json#/$defs/LayerAnswer"
    },
    "wz": {
      "$ref": "./envelope.json#/$defs/LayerAnswer"
    }
  },
  "required": [
    "pog",
    "mpzp",
    "wz",
    "gmina"
  ],
  "type": "object"
}
```

## Empty answer: covered_no_data

not specified in the source contract. The contract does not define a complete empty value for this schema.

## Coverage states

Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem.

States: `covered` | `covered_no_data` | `not_covered` | `not_computed`.

`LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`.

## Billing rule

Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów.

Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`.

## curl example

```sh
curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \
  -H "X-Api-Key: ${LANDFEED_API_KEY}" \
  --data-urlencode 'id=141803_2.0001.12/3'
```