API

Poprzez API jest możliwość wykorzystania silnika cieplo.app we własnej aplikacji, która może wyglądać i być zorganizowana prawie w dowolny sposób.

Uwagi, życzenia, skargi, pytania i zażalenia odnośnie API można kierować zwyczajowymi drogami kontaktu.

Autoryzacja

Każdy użytkownik posiada indywidualny klucz dostępu do API, który należy dołączyć do każdego żądania jako parametr GET o nazwie token. Klucz dostępu do API można znaleźć w panelu konta.

Jeśli użytkownik ma aktywną subskrypcję z dostępme do API – jego klucz jest w pełni funkcjonalny. W przeciwnym wypadku klucz działa w trybie testowym – do celów wdrożeniowych. Obliczenia przesłane za pomocą testowego klucza API przechodzą walidację, ale nie są zapisywane na serwerze. Zwracane w odpowiedzi wartości są losowe.

Nowe wyliczenie

POST https://cieplo.app/api/calculation

Żądanie

Treść żądania należy przesłać jako application/json.

Wszystkie parametry są obowiązkowe – poza opisanymi jako warunkowe lub opcjonalne. Poniższy przykład dla ilustracji zawiera wszystkie parametry, także te, które w tym typie budynku nie są potrzebne.

{
	"building_type": "single_house",
	"construction_year": 2020,
	"construction_type": "traditional",
	"latitude": 51.4453433,
	"longitude": 16.2334445,
	"building_length": 12.5,
	"building_width": 6,
	"floor_area": 45,
	"floor_perimeter": 125,
	"building_floors": 1,
	"building_heated_floors": [0, 1],
	"floor_height": 2.6,
	"building_roof": "steep",
	"has_basement": true,
	"has_balcony": true,
	"has_garage": false,
	"wall_size": 65,
	"primary_wall_material": 57,
	"secondary_wall_material": null,
	"internal_wall_isolation": {
		"material": 88,
		"size": 5
	},
	"external_wall_isolation": {
		"material": 88,
		"size": 15
	},
	"top_isolation": {
		"material": 68,
		"size": 35
	},
	"bottom_isolation": {
		"material": 71,
		"size": 5
	},
	"number_doors": 2,
	"number_balcony_doors": 2,
	"number_windows": 12,
	"number_huge_windows": 0,
	"doors_type": "new_metal",
	"windows_type": "new_double_glass",
	"indoor_temperature": 21,
	"ventilation_type": "natural",
	"include_hot_water": true,
	"hot_water_persons": 3,
	"hot_water_usage": "shower_bath",
	"whats_over": "heated_room",
	"whats_under": "heated_room",
	"whats_north": "heated_room",
	"whats_south": "unheated_room",
	"whats_east": "heated_room",
	"whats_west": "outdoor",
	"on_corner": true,
	"unheated_space_under_type": "worst",
	"unheated_space_over_type": "great"
}
Parametr Typ danych Jednostka Opis
building_type enum - Rodzaj budynku:
  • single_house – Dom jednorodzinny wolnostojący
  • double_house – Zabudowa bliźniacza
  • row_house – Dom w zabudowie szeregowej
  • apartment – Mieszkanie
construction_year enum/integer - Rok budowy; wartość według poniższej listy:
  • 2021 – lata 2021+
  • 2011 – lata 2011 – 2020
  • 2000 – lata 2000 – 2010
  • 1990 – lata 90-te
  • 1980 – lata 80-te
  • 1970 – lata 70-te
  • 1960 – lata 60-te
  • 1950 – lata 50-te
  • 1940 – lata 40-te
  • 1939 – gdzieś przed II wojną
  • 1914 – gdzieś przed I wojną
construction_type enum - Rodzaj konstrukcji budynku:
  • traditional – budynek tradycyjny, murowany lub z drewna
  • canadian – dom szkieletowy (kanadyjski)
latitude, longitude double - Współrzędne przybliżonej lokalizacji budynku.
building_length, building_width
warunkowe
double m Długość i szerokość obrysu budynku. Alternatywnie można podać powierzchnię zabudowy.
floor_area
warunkowe
double m2 Powierzchnia zabudowy. Alternatywnie można podać długość i szerokość obrysu budynku.
floor_perimeter
warunkoweopcjonalne
double m Obwód budynku. Nie jest wymagany, ale w przypadku skomplikowanej bryły pomaga doprecyzować wymiary.
building_floors integer - Liczba pełnych kondygnacji naziemnych – nie licząc poddasza i piwnic.
building_heated_floors array[integer] - Lista ogrzewanych kondygnacji, tutaj dla odmiany licząc piwnicę i poddasze:
  • 0 – piwnica
  • 1 – parter
  • 2 – 1. piętro
  • ...
floor_height enum/double m Wysokość pięter przeważająca w budynku.
  • 2.3 – niska
  • 2.6 – standardowa
  • 3.1 – wysoka
building_roof enum - Rodzaj dachu
  • flat – płaski
  • oblique – skośny bez poddasza (lub poddasze niewielkie gdzie nie mieści się człowiek)
  • steep – skośny z pełnowymiarowym poddaszem
has_basement boolean - Czy budynek posiada piwnicę?
has_balcony boolean - Czy budynek posiada balkon(y)?
has_garage boolean - Czy jest garaż w bryle budynku?
wall_size integer cm Całkowita grubość ściany zewnętrznej.
primary_wall_material
warunkowe Wymagane tylko dla construction_type = traditional
Materiał - Podstawowy materiał konstrukcyjny ścian (ten, który przeważa).
secondary_wall_material
opcjonalne
Materiał - Dodatkowy materiał konstrukcyjny ścian (jeśli ściana jest zbudowana np. z mixu pustaków i cegieł).
internal_wall_isolation[material]
warunkowe Wymagane przy construction_type = canadian
Materiał - Materiał wewnętrznej warstwy izolacji w ścianie zewnętrznej.
internal_wall_isolation[size]
warunkowe Wymagane przy construction_type = canadian
integer cm Grubość wewnętrznej warstwy izolacji w ścianie zewnętrznej.
external_wall_isolation[material]
opcjonalne
Materiał - Materiał zewnętrznego docieplenia ścian zewnętrznych.
external_wall_isolation[size]
opcjonalne
integer cm Grubość zewnętrznego docieplenia ścian zewnętrznych.
top_isolation[material]
opcjonalne
Materiał - Materiał ew. docieplenia przestrzeni ogrzewanej od góry. Może to być strop najwyższego ogrzewanego pomieszczenia lub dach – zależnie od konstrukcji budynku oraz od tego, które piętra są ogrzewane, a które nie.
top_isolation[size]
opcjonalne
integer cm Grubość w/w docieplenia (jeśli jest takowe).
bottom_isolation[material]
opcjonalne
Materiał - Materiał ew. docieplenia przestrzeni ogrzewanej od dołu. Może to być podłoga piwnicy, podłoga parteru albo strop parteru – zależnie od tego, które piętra są ogrzewane, a które nie.
bottom_isolation[size]
opcjonalne
integer cm Grubość w/w docieplenia (jeśli jest takowe).
number_doors integer - Liczba drzwi zewnętrznych w budynku.
number_balcony_doors integer - Liczba drzwi balkonowych w budynku.
number_windows integer - Liczba okien w budynku. Typowe okno = ok. 130x150cm.
number_huge_windows integer - Liczba dużych przeszkleń w budynku. Duże przeszklenie = np. 3x3m.
doors_type enum - Rodzaj drzwi zewnętrznych.
  • old_wooden – stare drewniane
  • old_metal – stare metalowe
  • new_wooden – nowe drewniane
  • new_metal – nowe metalowe
windows_type enum - Rodzaj okien.
  • old_single_glass – Stare z pojedynczą szybą
  • old_double_glass – Stare z min. dwiema szybami
  • semi_new_double_glass – Starsze (10+ lat) ale z szybami zespolonymi
  • new_double_glass – Współczesne dwuszybowe
  • new_triple_glass – Współczesne trójszybowe
indoor_temperature double °C Średnia dobowa temperatura w pomieszczeniach ogrzewanych zimą.
ventilation_type enum - Rodzaj wentylacji
  • natural – Naturalna lub grawitacyjna
  • mechanical – Mechaniczna
  • mechanical_recovery – Mechaniczna z odzyskiem ciepła
include_hot_water boolean - Czy wyliczamy dodatkową moc na potrzeby podgrzewania ciepłej wody użytkowej (CWU)?
hot_water_persons
warunkowe Wymagane tylko dla include_hot_water = true
integer - Liczba osób korzystających z ciepłej wody użytkowej (CWU).
hot_water_usage
warunkowe Wymagane tylko dla include_hot_water = true
enum - Intensywność wykorzystania ciepłej wody użytkowej (CWU):
  • shower – Tylko prysznice
  • shower_bath – Głównie prysznice, czasem wanna
  • bath – Tylko wanna
whats_over
warunkowe Wymagane tylko dla building_type = apartment
enum - Co znajduje się powyżej mieszkania?
  • heated_room – Ogrzewany lokal
  • unheated_room – Nieogrzewany lokal
  • outdoor – Świat zewnętrzny
whats_under
warunkowe Wymagane tylko dla building_type = apartment
enum - Co znajduje się poniżej mieszkania?
  • heated_room – Ogrzewany lokal
  • unheated_room – Nieogrzewany lokal
  • outdoor – Świat zewnętrzny
  • ground – Grunt
whats_north, whats_east, whats_south, whats_west
warunkowe Wymagane tylko dla building_type = apartment
enum - Co znajduje się w sąsiedztwie mieszkania – z każdej z czterech stron osobno?
  • heated_room – Ogrzewany lokal
  • unheated_room – Nieogrzewany lokal / korytarz / klatka schodowa
  • outdoor – Świat zewnętrzny
on_corner
warunkowe Wymagane tylko dla building_type = row_house
boolean - Czy segment w zabudowie szeregowej znajduje się na końcu/początku szeregu?
unheated_space_under_type
opcjonalne
enum - Jakość zaizolowania przestrzeni nieogrzewanej znajdującej się poniżej ogrzewanej części budynku.
  • worst – Hula tam wiatr bo np. drzwi dziurawe / okno dla kota uchylone
  • medium – Wiatr nie hula ale ocieplenie ścian jest gorsze niż na reszcie domu
  • great – Ocieplenie jest podobne lub lepsze jak na ogrzewanej części domu
Pole jest brane pod uwagę tylko w przypadku gdy istnieje jakaś przestrzeń nieogrzewana poniżej części ogrzewanej (np. nieogrzewana piwnica). Jeżeli to pole nie zostanie przesłane w zapytaniu, standardowo przyjmowana jest wartość medium.
unheated_space_over_type
opcjonalne
enum - Jakość zaizolowania przestrzeni nieogrzewanej znajdującej się powyżej ogrzewanej części budynku.
  • worst – Hula tam wiatr bo np. drzwi dziurawe / okno dla kota uchylone
  • medium – Wiatr nie hula ale ocieplenie ścian jest gorsze niż na reszcie domu
  • great – Ocieplenie jest podobne lub lepsze jak na ogrzewanej części domu
Pole jest brane pod uwagę tylko w przypadku gdy istnieje jakaś przestrzeń nieogrzewana ponad częścią ogrzewaną (np. nieogrzewane poddasze). Jeżeli to pole nie zostanie przesłane w zapytaniu, standardowo przyjmowana jest wartość medium.

Odpowiedź – sukces

Póki co zwracane są tylko te podstawowe dane, które – jak się naszemu jednoosobowemu zespołowi wydawało – będą potrzebne użytkownikom API. Daj znać jeśli potrzebujesz czegoś więcej spośród treści, jakie znajdują się na stronie z wynikiem.

{
	"result": {
		"id": 12345,
		"total_area": 145,
		"heated_area": 145,
		"max_heating_power": 5.2,
		"avg_heating_power": 2.5,
		"bivalent_point_heating_power": 4.6,
		"hot_water_power": 0.5,
		"annual_energy_consumption": 12345,
		"annual_energy_consumption_factor": 123,
		"heating_power_factor": 155
	}
}
            
Parametr Typ danych Jednostka Opis
total_area double m2 Całkowita powierzchnia budynku
heated_area double m2 Ogrzewana powierzchnia budynku
max_heating_power double kW Maksymalna moc grzewcza na potrzeby wyłącznie ogrzewania budynku w najzimniejszym dniu zimy.
avg_heating_power double kW Przeciętna moc grzewcza na potrzeby wyłącznie ogrzewania budynku przy średniej zimowej temperaturze zewnętrznej.
bivalent_point_heating_power double kW Moc grzewcza w punkcie biwalentnym.
hot_water_power double kW Dodatkowa moc grzewcza na potrzeby przygotowania ciepłej wody użytkowej (CWU).
annual_energy_consumption integer kWh Całkowite roczne zużycie energii na potrzeby wyłącznie ogrzewania budynku (nie jest w to wliczone przygotowanie CWU).
annual_energy_consumption_factor double kWh/m2 Współczynnik zapotrzebowania na ciepło.
heating_power_factor double W/m2 Współczynnik zapotrzebowania na moc grzewczą.

Odpowiedź – błędy

{
	"errors": {
		"internal_wall_isolation": "Pole wymagane."
	}
}
            

Pobranie istniejących wyliczeń

GET https://cieplo.app/api/calculation/{id}

Odpowiedź

{
	"parameters": {
		...
	},
	"result": {
		"id": 12345,
		"total_area": 145,
		"heated_area": 145,
		"max_heating_power": 5.2,
		"avg_heating_power": 2.5,
		"bivalent_point_heating_power": 4.6,
		"annual_energy_consumption": 12345,
		"annual_energy_consumption_factor": 123,
		"heating_power_factor": 155
	}
}
            

Listy materiałów

GET https://cieplo.app/api/materials/{field}

Gdzie field to nazwa pola, w którym lista materiałów jest wykorzystywana, dla którego ma być zwrócona lista odpowiednich materiałów (dla każdego z pól lista materiałów jest/może być inna).

{
	"123": "Styropian",
	"125": "Wełna mineralna",
	"129": "Słoma"
}