npm package: @gemdat/gis-client
Description: Internal Immoledo Client
Author: readydata AG
Latest version: 1.5.16

# Immoledo Client

## Getting Started

### Installation

```
pnpm add @gemdat/gis-client
```

### Initialize Client

`createFetchio` is a factory function that returns a `fetchio` client. It takes an object with the following properties:

```ts
interface FetchioClientInit {
  apiUrl: string;
  options?: {
        debug: boolean;
      } | undefined;
}
```

- `debug`: If set to `true` the client will log endpoint queries to the console.

### Authenticate Client

`authenticateFetchio` is a function that takes a client and and credentials to create an authenticated client:

```ts
interface FetchioCredentials {
  apiKey: string;
  apiSecret: string;
}
```

E.g:

```ts
const client = await authenticateFetchio(
  createFetchio({ apiUrl: "https://service.immoledo.app/dev" }),
  {
    apiKey: <key>,
    apiSecret: <secret>,
  },
);
```

### Querying Endpoints

`query` is a function that takes a `fetchio` client, an `endpoint` and query `data`. It returns a promise that resolves to the endpoint's response.

The endpoints request schema defines the query data's shape.

Lets look at how to query the `FindBuildings` endpoint:

```ts
const buildings = await query(client, FindBuildings, {
  egids: ["209890"],
});
```

This will return the building with the `egid` `209890`.

## Available Endpoints

### `FindBuildings`

Query Data Shape:

```ts
{
  egids: [string, ...string[]];
}
```

- `egids`: An non-empty array of EGID's

Return Data Shape:

```ts
{
    id?: string | undefined;
    egid?: number | undefined;
    address?: {
        city?: string | undefined;
        canton?: {
            code?: string | undefined;
            name?: string | undefined;
        } | undefined;
        zip?: number | undefined;
    } | undefined;
    entrances?: {
        egaid?: number | undefined;
        edid?: number | undefined;
        address?: string | undefined;
    } | undefined;
    isInCity?: boolean | undefined;
    capabilities?: {
        solar?: boolean | undefined;
        recycling?: boolean | undefined;
    } | undefined;
    publicConnectivityClass?: number | undefined;
    contaminatedSite: number;
    minergie?: {
      standard: string;
    } | undefined;
    poisAvailability: number;
    radon?: {
      maxValue: number
    } | undefined,
    parcel: {
      hasProtectedBuildings?: boolean | undefined;
      geothermalPotential?: boolean | undefined;
      waterUsagePotential?: boolean | undefined;
      groundWaterUsagePotential?: boolean | undefined;
      districtHeatingPotential?: boolean | undefined;
    };
    travelTime?: number | undefined;
    naturalHazards?: {
      hail?: number | undefined;
      waterRunOff?: number| undefined;
      seismicZones?: string | undefined;
    } | undefined;
    noiseExposure?: {
      unit?: string | undefined;
      min?: number | undefined;
      max?: number | undefined;
    } | undefined;
    vacancyRates?: {
        commune?: number | undefined;
    } | undefined;
}[]
```

- `entrances`: a building can have multiple street and streetNo
- `isInCity`: a city has >= 10.000 residents vs. a village has < 10.000 residents
- `publicConnectivityClass`
  - `0` - very good connectivity
  - `1` - good connectivity
  - `2` - average connectivity
  - `3` - weak connectivity
- `travelTime`: to the next agglomeration using public transport
- `waterRunOff`
  - `0`: Low <= 10cm
  - `1`: Medium > 10-25cm
  - `2`: High >= 25cm  
  - `-1`: Unknown
- `seismicZones`: SIA 261 standard
- `minergie` Standards: 
  - Minergie-A-ECO, Minergie-ECO, Minergie,Minergie-P-ECO, Minergie-P, Minergie-A
- `contaminatedSite`:
  - `0` - no entry
  - `1` - landRegisterEntryHarmful
  - `2` - monitoringPollutedSite
  - `3` - remediation
- `poisAvailability`: Count indicates the score 
- `vacancyRates`: Indicates vacancy rates in commune 

## Example

```ts
import { serve } from "@hono/node-server";
import {
  authenticateFetchio,
  createFetchio,
  FindBuildings,
  query,
} from "@gemdat/gis-client";
import { Hono } from "hono";

const app = new Hono();
app.get("/", async (c) => {
  const client = await authenticateFetchio(
    createFetchio({
      apiUrl: "<api-url>",
    }),
    { apiKey: "<key>", apiSecret: "<secret>" },
  );

  const buildings = await query(client, FindBuildings, {
    egids: ["209890"],
  });

  return c.json(buildings);
});

serve(app);

```