# PogValue

Plan ogólny. Projekty są pokazywane i oznaczane jako projekty. covered_no_data oznacza, że źródło obejmuje gminę, ale nie zawiera rekordu planu ogólnego: {status: none, zone_symbol: null, zones: []}.

Layer keys: `pog`.

## 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 |
| --- | --- | --- | --- |
| `adopted_on` | no | `{"format": "date", "type": ["string", "null"]}` | not specified in the source contract |
| `effective_from` | yes | `{"format": "date", "type": ["string", "null"]}` | Data wejścia planu w życie; null dla draft i none. |
| `in_ouz` | no | `{"type": ["boolean", "null"]}` | W granicach obszaru uzupełnienia zabudowy. |
| `plan_id` | no | `{"type": ["string", "null"]}` | not specified in the source contract |
| `resolution_url` | no | `{"type": ["string", "null"]}` | not specified in the source contract |
| `status` | yes | `{"enum": ["draft", "adopted", "in_force", "none"], "type": "string"}` | Status planu ogólnego lub MPZP: draft (projekt, nieuchwalony), adopted (uchwalony, jeszcze nie obowiązuje), in_force (obowiązuje), none (źródło nie zawiera rekordu takiego planu dla tego miejsca). Statusom adopted i in_force towarzyszy effective_from. |
| `zone_name` | no | `{"type": ["string", "null"]}` | not specified in the source contract |
| `zone_symbol` | yes | `{"type": ["string", "null"]}` | Dominująca strefa o największym udziale, np. SW, SJ, SN, SR, SI, SH, SU, SK, SC, SG, SO, SP. |
| `zones` | yes | `{"items": {"properties": {"name": {"type": ["string", "null"]}, "parameters": {"properties": {"max_coverage_pct": {"type": ["number", "null"]}, "max_height_m": {"type": ["number", "null"]}, "max_intensity": {"type": ["number", "null"]}, "min_biologically_active_pct": {"type": ["number", "null"]}, "min_new_plot_area_m2": {"type": ["number", "null"]}}, "type": "object"}, "share_pct": {"type": "number"}, "symbol": {"type": "string"}}, "required": ["symbol", "share_pct"], "type": "object"}, "type": "array"}` | not specified in the source contract |

```json
{
  "description": "Plan ogólny. Projekty są pokazywane i oznaczane jako projekty. covered_no_data oznacza, że źródło obejmuje gminę, ale nie zawiera rekordu planu ogólnego: {status: none, zone_symbol: null, zones: []}.",
  "properties": {
    "adopted_on": {
      "format": "date",
      "type": [
        "string",
        "null"
      ]
    },
    "effective_from": {
      "description": "Data wejścia planu w życie; null dla draft i none.",
      "format": "date",
      "type": [
        "string",
        "null"
      ]
    },
    "in_ouz": {
      "description": "W granicach obszaru uzupełnienia zabudowy.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "plan_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "resolution_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "$ref": "./envelope.json#/$defs/PlanStatus"
    },
    "zone_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "zone_symbol": {
      "description": "Dominująca strefa o największym udziale, np. SW, SJ, SN, SR, SI, SH, SU, SK, SC, SG, SO, SP.",
      "type": [
        "string",
        "null"
      ]
    },
    "zones": {
      "items": {
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "parameters": {
            "properties": {
              "max_coverage_pct": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "max_height_m": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "max_intensity": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "min_biologically_active_pct": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "min_new_plot_area_m2": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "share_pct": {
            "type": "number"
          },
          "symbol": {
            "type": "string"
          }
        },
        "required": [
          "symbol",
          "share_pct"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "status",
    "zone_symbol",
    "zones",
    "effective_from"
  ],
  "type": "object"
}
```

## Empty answer: covered_no_data

The contract states this empty `value`:

```json
{
  "status": "none",
  "zone_symbol": null,
  "zones": []
}
```

The stated empty value omits required fields `effective_from`; a complete empty value is not specified in the source contract.

## 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'
```