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",
	"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
}
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.
  • 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 – Kilkunastoletnie 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
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?

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,
		"annual_energy_consumption": 12345
	}
}
            

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,
		"annual_energy_consumption": 12345
	}
}
            

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"
}