# landfeed

> The source of truth for Polish land parcels (działki), for agents. One request turns whatever a
> person typed into a parcel and a sourced answer: plan ogólny, MPZP, whether a WZ decision is
> possible, flood, landslides, protected areas, buildings, road access, permits and prices nearby.
> REST and MCP return the same JSON envelope. Draft 2026-10-13; costs and rules below are the v1
> contract (contracts/openapi.yaml, contracts/envelope.json).

## Conventions

- Every read takes exactly one of `q` (free text as typed: "pogorzelec dziłaka 284/5",
  "Lesnowola 25/18", "Marcinowice 221"), `id` (EGiB id in slash or dash form:
  `146501_1.0101.12/3` or `146501_1.0101.12-3`) or `point` (`lat,lng`; or `lat` and `lng`).
  You never need to resolve first.
- Ambiguous input returns HTTP 200, `status: "ambiguous"` and `candidates` with confidence. Show
  them or re-call with a candidate `id`; never pick one silently. `needs_obreb: true` means ask
  which obręb.
- Every layer answer has `coverage`, `note`, `source` (with `attribution`) and `as_of`:
  - `covered`: the source holds a record here; `value` is it.
  - `covered_no_data`: the source covers this place and records nothing; `value` is the empty
    answer (false, 0, [], "none"). This is a real negative, and it is charged.
  - `not_covered`: the state does not publish it or we hold no data here; `value` is null.
    Say so; do not infer.
  - `not_computed`: we hold the source but have not computed it here yet; `value` is null.
- Plans carry `status` `draft | adopted | in_force | none` and `effective_from`. Drafts are shown
  and labelled.
- Do not tell a user a parcel is "safe". Do not say "no plan": name the plan (plan ogólny or
  MPZP), its status and the source.
- Quote `note`; cite `source.attribution` and `as_of`.
- Ids we return are canonical (slash form). Field names are snake_case.
- Never returned: land registry (KW) numbers, owner or holder data, investor names,
  address-level transaction prices (price aggregates need at least 5 transactions).

## Costs (requests per call, `x-request-cost` in the OpenAPI)

| Operation | Cost |
|---|---|
| GET /v1/check | 1 (verdict, named checks and the full record in one call) |
| GET /v1/parcel | 1 |
| POST /v1/parcel/batch | 1 per item, up to 1,000 items |
| GET /v1/layer/{layer} | 1 (`planning` answers plan ogólny, MPZP, WZ and gmina status at once) |
| GET /v1/resolve | 1 |
| GET or POST /v1/search | 1 |
| GET /v1/events | 1 |
| GET /v1/gminy/{teryt}/planning, GET /v1/gminy/planning | 1 |
| GET /v1/sources | 0 |
| GET /v1/openapi.json | 0 |

## Billing and refunds

Every response carries `billing {cost, charged, refunded, rule}` and the headers
`X-Request-Cost`, `X-Credits-Charged` and `X-Credits-Refunded`.

- Charged: answers, informative negatives (`covered_no_data`), candidate lists (`ambiguous`).
- Free: invalid input (HTTP 400, `rule: free_invalid_input`), a missing or wrong key (401),
  `If-None-Match` that matches (304), and operations that cost 0.
- Refunded: not found (404), other 4xx, every 5xx, `status: not_covered`, and a single-layer
  answer that is `not_covered` or `not_computed`.
- Batch counts per item (`rule: batch_mixed` when items differ).

## Errors

Every error body has `code`, `message`, `hint` and `docs`; `example_id` when the input was a
parcel; `signup_url` on 401. Codes: invalid_input (400), unauthorized (401), not_found (404),
rate_limited (429), source_unavailable (503), internal (500).

## Caching

GET by id returns an `ETag`; send it as `If-None-Match` to get 304, free. Authenticated
responses are `Cache-Control: private`; caching, embedding and keeping answers in session memory
are allowed with attribution.

## Tools (MCP, structured JSON)

check, parcel, layer, resolve, search, events. Six tools keep `tools/list` small. Each returns
the REST envelope as structured content.

## Docs

- OpenAPI: /v1/openapi.json
- Sources, licences and freshness: /v1/sources (free)

## This site (landfeed.pl)

- Home: https://landfeed.pl/
- Use with Claude: https://landfeed.pl/claude.html
- Use with ChatGPT: https://landfeed.pl/chatgpt.html
- API, costs, billing and refunds: https://landfeed.pl/api.html
- Data, sources and licences: https://landfeed.pl/data.html
- Use cases: https://landfeed.pl/use-cases.html
- Pricing (planned, subject to change) and waitlist: https://landfeed.pl/pricing.html
- How we keep it true: https://landfeed.pl/truth.html
- OpenAPI (contract copy): https://landfeed.pl/openapi.json
- Envelope schema: https://landfeed.pl/envelope.json

Status 2026-10-13: the hosted MCP (https://mcp.landfeed.pl/mcp) and the public API host are not
live yet. v1 data covers one voivodeship, mazowieckie.