npm package: @giapspzoo/giap-services-api-client
Description: GIAP services API client
Author: GIAP sp. z o.o.
Latest version: 1.3.0

# GIAP services API client

A TypeScript library for interacting with the GIAP services APIs.

## Installation

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

## Documentation

<details>
<summary>Parcels</summary>

### Import the library

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

### Get Parcel by ID

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

### Get Parcels Update Logs

```typescript
// 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:

```ts
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.

```typescript
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.

```typescript
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          |

</details>

<details>
<summary>Commune Images</summary>

### Import the library

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

### Get Commune Image

```typescript
// 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

```typescript
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

```typescript
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) |

</details>

<details>
<summary>PRG</summary>

### Import the library

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

### Get Voivodeships

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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`.

```typescript
// 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.

```typescript
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.

```typescript
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                                                     |

</details>

<details>
<summary>Proxy (WMS/WFS/WMTS)</summary>

### Import the library

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

### GET request (WFS GetCapabilities)

Include all request query parameters directly in the target URL.

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

### POST request

```typescript
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).

```typescript
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

```typescript
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                                                     |

</details>

<details>
<summary>UUG</summary>

### Import the library

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

### Search for Cities

```typescript
// 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

```typescript
// 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

```typescript
// 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,
});
```

### Advanced Usage

#### Custom HTTP Getter

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

```typescript
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.

```typescript
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                                              |

</details>

## 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.