GIAP services API client

A TypeScript library for interacting with the GIAP services APIs.

Installation

npm i @giapspzoo/giap-services-api-client

Documentation

Import the library

import {
  getParcelById,
  getParcelsByPoint,
  getParcelsByDistrict,
  getCommunesWithLoadedParcels,
  getParcelsUpdateLogs,
} from "@giapspzoo/giap-services-api-client/parcels";

Get Parcel by ID

// Get a parcel by its unique ID
const parcel = await getParcelById({ id: "123456_1.0001.12/3" });

// With specific fields
const parcel = await getParcelById({
  id: "123456_1.0001.12/3",
  fields: ["obreb", "numer"],
});

Get Parcels by Point

// Get parcels at specific coordinates
const parcels = await getParcelsByPoint({
  x: 123456.789,
  y: 987654.321,
});

// With custom SRID (coordinate reference system)
const parcels = await getParcelsByPoint({
  x: 12.345,
  y: 54.321,
  srid: 4326,
});

// With limit
const parcels = await getParcelsByPoint({
  x: 123456.789,
  y: 987654.321,
  limit: 2,
});

// With specific fields
const parcels = await getParcelsByPoint({
  x: 123456.789,
  y: 987654.321,
  fields: ["obreb", "numer", "geom_wkt"],
});

Get Parcels by District

// Get all parcels in a district (obręb)
const parcels = await getParcelsByDistrict({
  district: "123456_1.0001",
});

// With limit
const parcels = await getParcelsByDistrict({
  district: "123456_1.0001",
  limit: 100,
});

// With specific fields
const parcels = await getParcelsByDistrict({
  district: "123456_1.0001",
  fields: ["numer", "geom_wkt"],
});

Get Communes with Loaded Parcels

// Get list of communes (gminy) TERYT codes with parcel data loaded
const communes = await getCommunesWithLoadedParcels(); // ["0201011", "0201022", ...]

Get Parcels Update Logs

// Get parcel update logs for a commune (TERYT)
const updateLogs = await getParcelsUpdateLogs({ teryt: "1465011" });

// Example: first run status
const latestStatus = updateLogs.runs[0]?.status; // "SUCCESS" | "FAILED"

Advanced Usage

fields parameter

This parameter specifies which fields are included in the response. The iddzialki field is always included, regardless of the value passed to this parameter.

Examples:

fields: ["numer", "obreb"]; // [{ iddzialki: "123456_1.0001.12/3’, numer: "12/3’, obreb: "123456_1.0001’ }]
fields: ["numer"]; // [{ iddzialki: "123456_1.0001.12/3’, numer: "12/3’ }]
fields: ["iddzialki"]; // [{ iddzialki: "123456_1.0001.12/3" }]
fields: []; // displays all fields

Custom HTTP Getter

Each function accepts its own HTTP getter.

import axios from "axios";
import { getParcelById } from "@giapspzoo/giap-services-api-client/parcels";

const parcel = await getParcelById({
  id: "123456_1.0001.12/3",
  getter: async (url) => {
    const { data } = await axios.get(url);
    return data;
  },
});

Custom Service URL

Each function accepts a custom service address.

const parcel = await getParcelById({
  id: "123456_1.0001.12/3",
  serviceUrl: "https://example.com/api/parcels",
});

API Reference

Parcel (TParcel)

| Property | Type | Description | | ------------ | -------- | --------------------------- | | iddzialki | string | Unique parcel identifier | | obreb | string | District (obręb) identifier | | numer | string | Parcel number | | geom_wkt | string | Geometry in WKT format | | updated_at | string | Last update timestamp |

getCommunesWithLoadedParcels(params?) => Promise<TGetCommunesWithLoadedParcelsApiResponse>

| Parameter | Type | Required | Description | | ------------ | -------------------------------------------------------------------- | -------- | --------------------------- | | getter | (url: string) => Promise<TGetCommunesWithLoadedParcelsApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getParcelById(params) => Promise<TGetParcelByIdResponse>

| Parameter | Type | Required | Description | | ------------ | -------------------------------------------------- | -------- | -------------------------------------- | | id | string | Yes | Unique parcel identifier | | fields | Array<keyof TParcel> | No | Fields to return (default: all fields) | | getter | (url: string) => Promise<TGetParcelByIdResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getParcelsByCommune(params) => Promise<TGetParcelsByCommuneApiResponse>

| Parameter | Type | Required | Description | | -------------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------------- | | communeTeryt | string | Yes | Commune (gmina) identifier | | parcelNumber | string | Yes | Parcel identifier (full or phrase) | | limit | number | No | Maximum number of results (default: 1000, minimum: 1, maximum: 50000) | | fields | Array<keyof TParcel> | No | Fields to return (default: all fields) | | getter | (url: string) => Promise<TGetParcelsByCommuneApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getParcelsByDistrict(params) => Promise<TGetParcelsByDistrictApiResponse>

| Parameter | Type | Required | Description | | ------------ | ------------------------------------------------------------ | -------- | --------------------------------------------------------------------- | | district | string | Yes | District (obręb) identifier | | limit | number | No | Maximum number of results (default: 1000, minimum: 1, maximum: 50000) | | fields | Array<keyof TParcel> | No | Fields to return (default: all fields) | | getter | (url: string) => Promise<TGetParcelsByDistrictApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getParcelsByPoint(params) => Promise<TGetParcelsByPointApiResponse>

| Parameter | Type | Required | Description | | ------------ | --------------------------------------------------------- | -------- | ------------------------------------------------------------------ | | x | number | Yes | X coordinate (longitude) | | y | number | Yes | Y coordinate (latitude) | | srid | number | No | Spatial Reference System ID (default: 2180) | | limit | number | No | Maximum number of results (default: 10, minimum: 1, maximum: 1000) | | fields | Array<keyof TParcel> | No | Fields to return (default: all fields) | | getter | (url: string) => Promise<TGetParcelsByPointApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getParcelsUpdateLogs(params) => Promise<TGetParcelsUpdateLogsResponse>

| Parameter | Type | Required | Description | | ------------ | --------------------------------------------------------- | -------- | --------------------------- | | teryt | string | Yes | Commune (gmina) TERYT code | | getter | (url: string) => Promise<TGetParcelsUpdateLogsResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

Import the library

import { getCommuneImage } from "@giapspzoo/giap-services-api-client/commune-images";

Get Commune Image

// Get commune coat of arms image as Blob
const imageBlob = await getCommuneImage({ teryt: "1465011" });

// With optional size query parameter
const smallImageBlob = await getCommuneImage({
  teryt: "1465011",
  size: "small", // "small" | "medium" | "large"
});

Advanced Usage

Custom HTTP Getter

import axios from "axios";
import { getCommuneImage } from "@giapspzoo/giap-services-api-client/commune-images";

const imageBlob = await getCommuneImage({
  teryt: "1465011",
  getter: async (url) => {
    const { data } = await axios.get(url, { responseType: "blob" });
    return data;
  },
});

Custom Service URL

const imageBlob = await getCommuneImage({
  teryt: "1465011",
  serviceUrl: "https://example.com/herby/gminy/1465011.png",
});

API Reference

getCommuneImage(params) => Promise<Blob>

| Parameter | Type | Required | Description | | ------------ | -------------------------------- | -------- | ------------------------------------------------------- | | teryt | string | Yes | Commune (gmina) TERYT code | | size | 'small' \| 'medium' \| 'large' | No | Optional image size query parameter | | getter | (url: string) => Promise<Blob> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL (base URL or full URL to image file) |

Import the library

import {
  getVoivodeships,
  getCounties,
  getCommunes,
  getDistricts,
} from "@giapspzoo/giap-services-api-client/prg";

Get Voivodeships

// Get all voivodeships
const voivodeships = await getVoivodeships();

// Get voivodeship by TERYT code
const masovian = await getVoivodeships({ teryt: "14" });

// Search by name
const voivodeships = await getVoivodeships({ name: "mazow" });

Get Counties

// Get all counties
const counties = await getCounties();

// Get county by TERYT code
const county = await getCounties({ countyTeryt: "1465" });

// Get counties in a voivodeship
const counties = await getCounties({ voivodeshipTeryt: "14" });

// Search by name
const counties = await getCounties({ name: "warsz" });

Get Communes

// Get all communes
const communes = await getCommunes();

// Get commune by TERYT code
const commune = await getCommunes({ communeTeryt: "1465011" });

// Get communes in a county
const communes = await getCommunes({ countyTeryt: "1465" });

// Search by name
const communes = await getCommunes({ name: "warsz" });

// With limit
const communes = await getCommunes({ name: "warsz", limit: 10 });

Get Districts

// Get all districts (obręby)
const districts = await getDistricts();

// Get district by TERYT code
const district = await getDistricts({ districtTeryt: "1465011_1.0001" });

// Get districts in a commune
const districts = await getDistricts({ communeTeryt: "1465011" });

// Search by name
const districts = await getDistricts({ name: "0001" });

// With limit
const districts = await getDistricts({ communeTeryt: "1465011", limit: 50 });

Including geometry (WKT)

Pass includeGeometry: true to receive geom_wkt (WKT string) on each item. By default it is null.

// Voivodeships with geometry – result type has geom_wkt: string
const voivodeships = await getVoivodeships({ includeGeometry: true });
// e.g. voivodeships[0].geom_wkt === "MULTIPOLYGON((...))"

// Same option is available for getCounties, getCommunes, and getDistricts
const counties = await getCounties({
  voivodeshipTeryt: "14",
  includeGeometry: true,
});
const communes = await getCommunes({
  countyTeryt: "1465",
  includeGeometry: true,
});
const districts = await getDistricts({
  communeTeryt: "1465011",
  includeGeometry: true,
});

Advanced Usage

Custom HTTP Getter

Each function accepts its own HTTP getter.

import axios from "axios";
import { getVoivodeships } from "@giapspzoo/giap-services-api-client/prg";

const voivodeships = await getVoivodeships({
  getter: async (url) => {
    const { data } = await axios.get(url);
    return data;
  },
});

Custom Service URL

Each function accepts a custom service address.

const voivodeships = await getVoivodeships({
  serviceUrl: "https://example.com/api/wojewodztwa",
});

API Reference

Voivodeship (TPrgVoivodeship)

| Property | Type | Description | | ---------- | ---------------- | --------------------- | | nazwa | string | Voivodeship name | | teryt | string | TERYT code (2 digits) | | geom_wkt | string \| null | Geometry (WKT format) |

County (TPrgCounty)

| Property | Type | Description | | ---------- | ---------------- | --------------------- | | nazwa | string | County name | | teryt | string | TERYT code (4 digits) | | geom_wkt | string \| null | Geometry (WKT format) |

Commune (TPrgCommune)

| Property | Type | Description | | ---------- | ---------------- | --------------------- | | nazwa | string | Commune name | | teryt | string | TERYT code (7 digits) | | geom_wkt | string \| null | Geometry (WKT format) |

District (TPrgDistrict)

| Property | Type | Description | | ---------- | ---------------- | -------------------------------- | | nazwa | string | District name | | teryt | string | TERYT code (e.g. 1465011_1.0001) | | geom_wkt | string \| null | Geometry (WKT format) |

getVoivodeships(params?) => Promise<TPrgGetVoivodeshipsApiResponse>

| Parameter | Type | Required | Description | | ------------------ | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------- | | teryt | string | No | Filter by TERYT code (mutually exclusive with name) | | name | string | No | Search by name (full name or phrase; mutually exclusive with teryt) | | includeGeometry | boolean | No | Specifies whether to return object geometries (default: false) | | getter | (url: string) => Promise<TPrgGetVoivodeshipsApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getCounties(params?) => Promise<TPrgGetCountiesApiResponse>

| Parameter | Type | Required | Description | | ------------------ | ------------------------------------------------------ | -------- | ------------------------------------------------------------------------ | | countyTeryt | string | No | Filter by county TERYT code (mutually exclusive with voivodeshipTeryt) | | voivodeshipTeryt | string | No | Filter by voivodeship TERYT code (mutually exclusive with countyTeryt) | | name | string | No | Search by name (full name or phrase) | | includeGeometry | boolean | No | Specifies whether to return object geometries (default: false) | | getter | (url: string) => Promise<TPrgGetCountiesApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getCommunes(params?) => Promise<TPrgGetCommunesApiResponse>

| Parameter | Type | Required | Description | | ------------------ | ------------------------------------------------------ | -------- | --------------------------------------------------------------------- | | communeTeryt | string | No | Filter by commune TERYT code (mutually exclusive with countyTeryt) | | countyTeryt | string | No | Filter by county TERYT code (mutually exclusive with communeTeryt) | | name | string | No | Search by name (full name or phrase) | | includeGeometry | boolean | No | Specifies whether to return object geometries (default: false) | | limit | number | No | Maximum number of results (default: 1000, minimum: 1, maximum: 50000) | | getter | (url: string) => Promise<TPrgGetCommunesApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

getDistricts(params?) => Promise<TPrgGetDistrictsApiResponse>

| Parameter | Type | Required | Description | | ------------------ | ------------------------------------------------------- | -------- | ---------------------------------------------------------------------- | | districtTeryt | string | No | Filter by district TERYT code (mutually exclusive with communeTeryt) | | communeTeryt | string | No | Filter by commune TERYT code (mutually exclusive with districtTeryt) | | name | string | No | Search by name (full name or phrase) | | includeGeometry | boolean | No | Specifies whether to return object geometries (default: false) | | limit | number | No | Maximum number of results (default: 1000, minimum: 1, maximum: 50000) | | getter | (url: string) => Promise<TPrgGetDistrictsApiResponse> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

Import the library

import proxyRequest from "@giapspzoo/giap-services-api-client/proxy";

GET request (WFS GetCapabilities)

Include all request query parameters directly in the target URL.

const result = await proxyRequest({
  url: "https://mapy.geoportal.gov.pl/wss/service/PZGIK/PRG/WFS/AdministrativeBoundaries?service=WFS&request=GetCapabilities",
  method: "GET",
});

POST request

const result = await proxyRequest({
  url: "https://example.com/geoserver/wfs",
  method: "POST",
  body: {
    service: "WFS",
    request: "GetFeature",
    typeName: "example_layer",
  },
});

Advanced Usage

Custom HTTP Getter

Use a custom getter when the proxied response is not JSON (for example XML in WMS/WFS/WMTS).

const capabilitiesXml = await proxyRequest({
  url: "https://mapy.geoportal.gov.pl/wss/service/PZGIK/PRG/WFS/AdministrativeBoundaries?service=WFS&request=GetCapabilities",
  method: "GET",
  getter: async (url) => {
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error("Failed to fetch proxied response");
    }

    return response.text();
  },
});

Custom Service URL

const result = await proxyRequest({
  url: "https://example.com/geoserver/wms?service=WMS&request=GetCapabilities",
  serviceUrl: "https://example.com/api/proxy",
});

API Reference

proxyRequest(params) => Promise<string>

| Parameter | Type | Required | Description | | ------------ | ----------------------------------- | -------- | ---------------------------------------------------------------------------- | | url | string | Yes | Full target URL to proxy. Include all query parameters directly in this URL. | | method | 'GET' \| 'POST' | No | Proxied request method (default: GET) | | body | Record<string, unknown> \| string | No | Optional request body (used when method is POST) | | getter | (url: string) => Promise<string> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom proxy service URL |

Import the library

import {
  getCity,
  getStreet,
  getAddress,
  getAddressInCommune,
} from "@giapspzoo/giap-services-api-client/uug";

Search for Cities

// Basic city search
const warsaw = await getCity({ name: "Warszawa" }); // full name
const cities = await getCity({ name: "warsz" }); // or phrase

// With fuzzy matching
const cities = await getCity({
  name: "warsz",
  fuzzy: {
    enabled: true,
    threshold: 0.8,
  },
});

// With limit
const cities = await getCity({
  name: "warsz",
  limit: 10,
});

// With sorting
const cities = await getCity({
  name: "warsz",
  sort: "type", // or "type"
});

// With TERYT code - limit results to an area by specifying TERYT
const cities = await getCity({
  name: "warsz",
  teryt: "14", // get results for Masovian Voivodeship
});

// Remove duplicate cities
const cities = await getCity({
  name: "warsz",
  removeDuplicates: true,
});

Get Streets for a City

// Get all streets for a city (using SIMC code from city search)
const streets = await getStreet({ simc: "0918123" });

// Remove duplicate streets
const streets = await getStreet({
  simc: "0918123",
  removeDuplicates: true,
});

Get Address Points

// Get all address points for a city
const addresses = await getAddress({ simc: "0918123" });

// Get address points for a specific street
const addresses = await getAddress({
  simc: "0918123",
  ulic: "1234567", // Street code from street search
});

// Remove duplicate address points
const addresses = await getAddress({
  simc: "0918123",
  removeDuplicates: true,
});

Get Address Points in Commune

Search address points (and related features like streets/cities) within a commune (gmina) by its TERYT code. Optionally pass simc to further narrow results to a specific city (SIMC).

// Search address points in a commune by phrase
const results = await getAddressInCommune({
  teryt: "0201022",
  query: "Bolesławice",
});

// Optionally narrow results to a specific city (SIMC)
const results = await getAddressInCommune({
  teryt: "0201022",
  simc: "0918123",
  query: "Bolesławice",
});

// Limit results to a selected feature type
const results = await getAddressInCommune({
  teryt: "0201022",
  query: "Bolesławice",
  featureType: "address",
});

// Limit results to selected feature types (single or multiple)
// Tip: use `as const` for best TypeScript return type inference
const results = await getAddressInCommune({
  teryt: "0201022",
  query: "Bolesławice",
  featureType: ["address", "street"] as const,
});

Advanced Usage

Custom HTTP Getter

Each function accepts its own HTTP getter and custom service address.

import axios from "axios";
import { getCity } from "@giapspzoo/giap-services-api-client/uug";

const cities = await getCity({
  name: "Warszawa",
  getter: async (url) => {
    const { cities } = await axios.get(url);

    return cities;
  },
});

Custom Service URL

Each function accepts a custom service address.

const cities = await getCity({
  name: "Warszawa",
  serviceUrl: "https://example.com/api/cities",
});

API Reference

getCity(params) => Promise<TUugCityList>

| Parameter | Type | Required | Description | | ------------------ | ---------------------------------------- | -------- | ------------------------------------------------------------------------------ | | name | string | Yes | City name or phrase to search for | | fuzzy | object | No | Fuzzy matching configuration | | fuzzy.enabled | boolean | No | Enable fuzzy matching (default: false) | | fuzzy.threshold | number | No | Similarity threshold 0-1 (default: 0.27, minimum: 0.1, maximum: 1) | | teryt | string | No | TERYT code to limit search to specific area | | limit | number | No | Maximum number of results to return (default: 1000, minimum: 1, maximum: 2000) | | sort | 'name' \| 'type' | No | Sort results by city name or type (default: name) | | getter | (url: string) => Promise<TUugCityList> | No | Custom HTTP getter function | | removeDuplicates | boolean | No | Remove duplicate cities by SIMC code (default: false) | | serviceUrl | string | No | Custom service URL |

getStreet(params) => Promise<TUugStreetList>

| Parameter | Type | Required | Description | | ------------------ | ------------------------------------------ | -------- | -------------------------------------------------------- | | simc | string | Yes | SIMC code of the city (from getCity results) | | getter | (url: string) => Promise<TUugStreetList> | No | Custom HTTP getter function | | removeDuplicates | boolean | No | Remove duplicate streets by ULIC code (default: false) | | serviceUrl | string | No | Custom service URL |

getAddress(params) => Promise<TUugAddressPointsList>

| Parameter | Type | Required | Description | | ------------------ | ------------------------------------------------- | -------- | --------------------------------------------------------------- | | simc | string | Yes | SIMC code of the city (from getCity results) | | ulic | string | No | Street code to filter addresses (from getStreet results) | | getter | (url: string) => Promise<TUugAddressPointsList> | No | Custom HTTP getter function | | removeDuplicates | boolean | No | Remove duplicate addresses by address number (default: false) | | serviceUrl | string | No | Custom service URL |

getAddressInCommune(params) => Promise<TUugAddressPointsInCommuneList>

When featureType is provided, the TypeScript return type is narrowed to match the selected feature type(s).

| Parameter | Type | Required | Description | | ------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------ | | teryt | string | Yes | Commune (gmina) TERYT code (7 digits) | | simc | string | No | Optional city (SIMC) code to narrow results | | query | string | Yes | Search phrase (e.g. city/street/name) | | featureType | 'address' \| 'street' \| 'city' \| Array<'address' \| 'street' \| 'city'> | No | Filter results by feature type(s) (default: all) | | getter | (url: string) => Promise<TUugAddressPointsInCommuneList> | No | Custom HTTP getter function | | serviceUrl | string | No | Custom service URL |

Library preview

To run the library in preview mode, use npm run build (or npm run dev if you need watch mode) and npm run preview at the same time (in separate terminals). The preview is served at http://localhost:8080 by default.

License

MIT © GIAP sp. z o.o.