npm package: @giapspzoo/giap-uug-api-client
Description: GIAP UUG API client
Author: GIAP sp. z o.o.
Latest version: 1.2.1
Deprecated: Package is deprecated. Use @giapspzoo/giap-services-api-client instead.

# GIAP UUG API

A TypeScript library for interacting with the GIAP UUG services API.

## Installation

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

## Usage

### Import the library

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

### 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 getAddresses({ simc: "0918123" });

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

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

### Advanced Usage

#### Custom HTTP Getter

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

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

    return cities;
  },
});
```

#### Custom Service URL

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

## API Reference

#### `getCity(params) => Promise<TGiapUugCityList>`

| 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.3`)               |
| `teryt`            | `string`                                     | No       | TERYT code to limit search to specific area             |
| `limit`            | `number`                                     | No       | Maximum number of results to return                     |
| `sort`             | `'name' \| 'type'`                           | No       | Sort results by city name or type (default: `name`)     |
| `getter`           | `(url: string) => Promise<TGiapUugCityList>` | 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<TGiapUugStreetList>`

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

#### `getAddresses(params) => Promise<TGiapUugAddressPointList>`

| 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<TGiapUugAddressPointList>` | No       | Custom HTTP getter function                                     |
| `removeDuplicates` | `boolean`                                            | No       | Remove duplicate addresses by address number (default: `false`) |
| `serviceUrl`       | `string`                                             | No       | Custom service URL                                              |

## License

MIT © GIAP sp. z o.o.