Parcel API v1 · beta

Dane działek i eksporty (DXF, GeoJSON, SHP, arkusz mapy PDF) dla firm budowlanych, biur projektowych, agencji nieruchomości i integracji z CRM. Wyłącznie publiczne dane GUGiK.

Autoryzacja

Klucz utworzysz w Mój plan → Klucze API (plan Pro). Przesyłaj go w nagłówku:

X-API-Key: pk_live_…        lub        Authorization: Bearer pk_live_…

Klucz jest pokazywany tylko raz; przechowujemy tylko jego skrót SHA-256. Klucz można w każdej chwili unieważnić.

GET /api/v1/parcel

curl -H "X-API-Key: $PARCEL_KEY" "https://parcel-staging.imetroll.com/api/v1/parcel?id=141804_4.0006.9/5"

{ "parcel": { "parcel_id": "141804_4.0006.9/5", "parcel_no": "9/5", "region": "06", "commune": "Piaseczno", "area_m2": 2215.6, "vertices": 12, "pl2000_zone": 7, … },
  "geometry": { "type": "Polygon", "crs": "EPSG:4326", "coordinates": [[…]] },
  "mpzp": { "covered": true|false|null, "plans": [{ "nazwa": …, "uchwala": …, "tresc": "https://…" }], "zones": [{ "symbol": …, "opis": … }], "pog": […] },
  "exports": [ "/api/v1/export?id=…&fmt=dxf&crs=2180", … ] }

mpzp zawiera tylko to, co publikuje KIMP / Plany Ogólne Gmin w centroidzie działki; null = brak odpowiedzi usługi. Wiążąca jest uchwała gminy.

GET /api/v1/export

curl -H "X-API-Key: $PARCEL_KEY" -o dzialka.dxf "https://parcel-staging.imetroll.com/api/v1/export?id=141804_4.0006.9/5&fmt=dxf&crs=2000&nb=1"

GET / PATCH /api/v1/offers beta

Oferty = zamówione raporty działek Twojego konta lub firmy (zakres klucza API). Każda odpowiedź przechodzi przez centralny filtr prywatności.

Webhooks · /api/v1/webhooks

Zdarzenia: offer.created, offer.updated, offer.status_changed, webhook.test. Podpis: X-Parcel-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + raw_body)>. Odpowiedz 2xx w 10 s; inaczej ponowienia po 1 min, 5 min, 30 min, 2 h, 12 h (6 prób), potem status dead. Adres musi być publicznym HTTPS (blokada adresów prywatnych).

Konektory CRM · /api/v1/connectors

POST /api/v1/connectors?connector=enova365 {"mapping":{"Kod":"offer_id","Nazwa":"offer_title","Cecha_MPZP":"mpzp_symbols"},"options":{"separator":";"}} – własne mapowanie kolumn (właściciel/admin firmy).

Przykłady zastosowań / Usage examples

1. Eksport plikowy CSV / XML / JSON

• Excel: Dane → Z pliku tekstowego/CSV → kodowanie UTF-8, separator średnik. Google Sheets: Plik → Importuj → separator „;”, albo =IMPORTDATA() z własnego serwera pośredniczącego (klucz API nie może trafić do arkusza). LibreOffice Calc: Otwórz → zestaw znaków UTF-8, separator ;.
• Bazy pośredników / biur: import CSV lub XML (schemat parcel.offer.v1) cyklicznie albo po webhooku.

offer_id;offer_status;offer_title;offer_asking_price;parcel_id;parcel_no;commune;area_m2;mpzp_covered;mpzp_symbols;boundary_wkt_wgs84;map_url;agency_nip;agency_regon;owner_name;kw_number;kw_persons
10;active;"Działka budowlana 2216 m² (PRZYKŁAD)";789000;141804_4.0006.9/5;9/5;Piaseczno;2215.6;TAK/YES;MN;"POLYGON((21.02314272 52.08505105,…))";https://parcel-staging.imetroll.com/app.php?center=21.023562,52.084863&z=18;1234563218;123456785;***;WA1M/********/*;***

# Python
import csv, requests
r = requests.get("https://parcel-staging.imetroll.com/api/v1/offers", params={"id": "all", "fmt": "csv"}, headers={"X-API-Key": KEY})
rows = list(csv.DictReader(r.content.decode("utf-8-sig").splitlines(), delimiter=";"))
print(rows[0]["parcel_id"], rows[0]["area_m2"], rows[0]["mpzp_symbols"])

<?php // PHP
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: " . getenv('PARCEL_KEY')]]);
$o = json_decode(file_get_contents('https://parcel-staging.imetroll.com/api/v1/offers?id=10', false, $ctx), true);
echo $o['parcel']['parcel_id'], ' ', $o['parameters']['area_m2'], ' m², MPZP: ', $o['mpzp']['zones'][0]['symbol'] ?? '-';

2. Konektory CRM – jak oferta trafia do pipeline’u

1. Agent kupuje raport działki w Parcel → powstaje oferta (#id).
2. Webhook offer.created / offer.updated trafia do systemu biura (albo agent klika „Eksport do CRM”).
3. System biura pobiera /api/v1/offers?id=…&connector=esticrm (lub plik CSV dla enova365 / Symfonia) i zakłada/aktualizuje ofertę.
4. CRM publikuje na portalach (Otodom – WEB API CRM; OLX, Nieruchomosci-online, Nieruchomosci.pl, Gratka – eksporty CRM).
5. Zmiana statusu (rezerwacja, sprzedaż) w Parcel → offer.status_changed → CRM przesuwa etap.

Parcel (raport/oferta) --webhook--> CRM biura (EstiCRM / ASARI / enova365 / Symfonia) --eksport CRM--> Otodom · OLX · Nieruchomosci-online · Nieruchomosci.pl · Gratka

Zweryfikowane: format Parcel CSV/XML/JSON; istnienie API EstiCRM i ASARI (publiczna dokumentacja); publikacja na Otodom przez CRM (bazy wiedzy EstiCRM/ASARI). Koncepcyjne (wymaga partnerstwa / specyfikacji dostawcy): zapis bezpośrednio do enova365, Symfonia, ASARI, EstiCRM, Galactica Virgo oraz bezpośredni push na Otodom, OLX, Nieruchomosci-online, Nieruchomosci.pl, Gratka.

3. API – scenariusze

• Portale ogłoszeniowe (Otodom, OLX, Gratka): wzbogacenie ogłoszenia o granice, pow., MPZP i mapę – GET /api/v1/offers?id=…&view=buyer.
• Banki – analiza zabezpieczenia: tylko działka, MPZP, parametry i granice (GET /api/v1/parcel?id=…, view=buyer). Bez danych o obciążeniach, hipotekach i kredytach – tych danych Parcel nie udostępnia.
• Sieci franczyzowe biur: jeden klucz firmowy + webhook offer.* do centrali; oddziały jako członkowie konta firmowego.
• Deweloperzy z własnym CRM: PATCH statusu/ceny z CRM, webhook z powrotem, eksport DXF/SHP do projektu.

curl -H "X-API-Key: pk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "https://parcel-staging.imetroll.com/api/v1/offers?id=10&view=buyer"

{ "schema": "parcel.offer.v1",
  "offer_ref": { "id": 10, "status": "active", "title": "Działka budowlana 2216 m² (PRZYKŁAD)", "asking_price": 789000, "currency": "PLN" },
  "parcel": { "parcel_id": "141804_4.0006.9/5", "parcel_no": "9/5", "commune": "Piaseczno", "county": "powiat piaseczyński", "voivodeship": "mazowieckie" },
  "parameters": { "area_m2": 2215.6, "area_ha": 0.2216, "perimeter_m": 197.1, "vertices": 12, "pl2000_zone": 7 },
  "boundaries": { "wgs84_polygon": [[21.02314272, 52.08505105], …], "pl1992": [{ "nr": 1, "x_e": 641234.56, "y_n": 478901.23 }, …] },
  "mpzp": { "covered": true, "plans": [{ "nazwa": "…", "uchwala": "…" }], "zones": [{ "symbol": "MN", "opis": "zabudowa mieszkaniowa jednorodzinna (PRZYKŁAD)" }] },
  "map": { "parcel_map_url": "…/app.php?center=21.023562,52.084863&z=18", "geoportal_url": "https://mapy.geoportal.gov.pl/imap/Imgp_2.html?identifyParcel=141804_4.0006.9%2F5" },
  "photos": ["https://…/zdjecie-1.jpg"] }

# pełny widok (biuro) dodatkowo:
  "agency": { "company_name": "Przykładowa Agencja Nieruchomości (PRZYKŁAD)", "nip": "1234563218", "regon": "123456785", "legal_form": "sp. z o.o.", "seat_address": "ul. Przykładowa 1, 00-001 Warszawa" },
  "owner": { "name": "***", "anonymized": "***" },
  "land_register": { "kw_number": "WA1M/********/*", "kw_persons": "***" }

POST https://crm.example.com/parcel-webhook
Content-Type: application/json
X-Parcel-Event: offer.status_changed
X-Parcel-Event-Id: evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0
X-Parcel-Signature: t=1793554496,v1=5d41402abc4b2a76b9719d911017c592aa5b8c3e0e3f4a5b6c7d8e9f0a1b2c3d

{"id":"evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0","type":"offer.status_changed","created_at":"2026-11-01T18:34:56+01:00","api_version":"v1",
 "data":{"offer":{"schema":"parcel.offer.v1","offer_ref":{"id":10,"status":"reserved","asking_price":789000},"previous_status":"active",
   "parcel":{"parcel_id":"141804_4.0006.9/5"},"owner":{"name":"***"},"land_register":{"kw_number":"WA1M/********/*","kw_persons":"***"}, …}}}

# weryfikacja podpisu (Python)import hmac, hashlib, time
t, v1 = dict(p.split("=", 1) for p in request.headers["X-Parcel-Signature"].split(",")).values()
ok = abs(time.time() - int(t)) < 300 and hmac.compare_digest(v1, hmac.new(SECRET.encode(), f"{t}.".encode() + request.get_data(), hashlib.sha256).hexdigest())

Limity i błędy

Domyślnie 30 zapytań / min i 1000 / miesiąc na klucz. Nagłówki X-RateLimit-Limit, X-RateLimit-Remaining; po przekroczeniu 429 + Retry-After.

Zasady

Rozliczanie zapytań API: wkrótce (beta bez opłat na stagingu). · English

Piaskownica API (bez konta)

Baza /sandbox/v1, publiczny klucz pk_sandbox_demo_parcel, sekret podpisu webhooków whsec_sandbox_demo. Fikcyjne oferty SBX-1..3 i działki SBX_…; bez zapytań do GUGiK/EKW. Zmiany (PATCH) widoczne tylko z Twojego IP, reset codziennie o 03:00. Limity: 30 zapytań/min i 5 testów webhooka/godz. na IP; webhook tylko na publiczny https (443/8443). Uzyskaj własny klucz testowy →

curl -H "X-API-Key: pk_sandbox_demo_parcel" "https://parcel-staging.imetroll.com/sandbox/v1/offers"