Immoledo Client

Getting Started

Installation

pnpm add @readydataag/immoledo-public-client

Initialize Client

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

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:

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

E.g:

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:

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

This will return the building with the egid 209890.

Available Endpoints

FindBuildings

Query Data Shape:

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

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

Return Data Shape:

{
    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;
}[]

• 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

Example

import { serve } from "@hono/node-server";
import {
  authenticateFetchio,
  createFetchio,
  FindBuildings,
  query,
} from "@readydataag/immoledo-public-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);