OctopusPro s.r.o.
Webové služby pro
služby OctopusPro 1 CENOVÉ MAPY Verze: 1.0
Datum vytvoření: Datum poslední aktualizace:
21.10.2015 21.10.2015
Copyright OctopusPro s.r.o, Praha, 2012-2015
Stránka |2
Obsah: 1
ÚVOD ............................................................................................................................................... 3 1.1
2
3
Popis práce s webovými službami ................................................................................................... 3 2.1
Základní třídy požadavku a odpovědi (RequestBase a ResponseBase) ................................... 3
2.2
Příklad použití WS.................................................................................................................... 3
Webové služby – 1. cenové mapy – popis funkcí ............................................................................ 5 3.1
4
5
Základní popis .......................................................................................................................... 3
wsCM_01 ................................................................................................................................. 5
Datové typy ..................................................................................................................................... 5 4.1
LocalityDTO.............................................................................................................................. 5
4.2
InputDataDTO.......................................................................................................................... 5
4.3
OutputDataDTO ....................................................................................................................... 6
Číselníky ........................................................................................................................................... 7 5.1
LocalityDefinitionDTO.............................................................................................................. 7
5.2
ccBuildingCondition ................................................................................................................. 7
5.3
ccBuildingType......................................................................................................................... 7
5.4
ccMonthInPast......................................................................................................................... 7
5.5
ccViewCM ................................................................................................................................ 7
Stránka |3
1 ÚVOD Úkolem webových služeb poskytovaných společností OctopusPro s.r.o. je zpřístupnění dat pro software třetích stran. Jejich využívání je podmíněno vytvořením aplikace na straně klienta, který bude poskytnutá data dále zpracovávat.
1.1
Základní popis
Webové služby jsou veřejně dostupné na následující adrese: https://ws.1cenovemapy.cz/CMService.svc?wsdl K úspěšnému přihlášení do webové služby je nutné mít zřízený účet na http://www.1cenovemapy.cz/ a povoleny webové služby.
2 POPIS PRÁCE S WEBOVÝMI SLUŽBAMI 2.1
Základní třídy požadavku a odpovědi (RequestBase a ResponseBase) Třídy RequestBase a ResponseBase jsou základní třidy. O těchto základních tříd dědí všechny další typy Request a Response v jednotlivých funkcích.
RequestBase – základní třída pro vstupní parametr web.služby Název elementu
Typ
Možné hodnoty
Poznámka
ClientUserName
string
Neprázdný string
ClientPassword
string
Neprázdný string
Uživatelské jméno, které je totožně s loginem do aplikace 1. CENOVÉ MAPY na http://aplikace.1cenovemapy.cz/ Heslo, které je totožné s loginem do aplikace na http://aplikace.1cenovemapy.cz/
ResponseBase – základní třída pro výstupní parametr web.služby
2.2
Název elementu
Typ
Možné hodnoty
Acknowledge
AcknowledgeType Success, Failed
Message
String
Prádný string v případě úspěchu
Poznámka
Udává výsledek volání webové služby. V případě chyby vrací Failed V případě chyby (Acknowledge) je zde možné nalézt detailnější popis, proč se volání nezdařilo
Příklad použití WS
Všechny příklady jsou uvedeny v jazyce C# (.NET Framework). Princip je ale stejný ve všech programovacích jazycích. Nejdříve je potřeba přidat WS do Service References v daném projektu. Ukázka nastavení připojení k WS z web.config <system.serviceModel>
Stránka |4
<endpoint address=" https://ws.1cenovemapy.cz/CMService.svc" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_ICenoveMapyService" contract="CMReferenceWS.ICenoveMapyService" name="BasicHttpBinding_ICenoveMapyService" />
V následujícím příkladu je ukázka volání funkce wsCM_01 wsCM_01_Request RQ = new wsCM_01_Request(); RQ.ClientUserName = tbJmeno.Text; RQ.ClientPassword = tbHeslo.Text;
var LocalityDefinitionEn = (ccLocalityDefinition)Enum.Parse(typeof(ccLocalityDefinition), ddlTypRuian.SelectedValue); var viewCm = (CM_StructuresccViewCM)Enum.Parse(typeof(CM_StructuresccViewCM), ddlViewCM.SelectedValue); var PastInMth = (MonthInPast)Enum.Parse(typeof(MonthInPast), ddlMonthInPast.SelectedValue);
RQ.Locality = new LocalityDTO() { KOD = Convert.ToInt32(tbRuaianKod.Text), LocalityDefinition = LocalityDefinitionEn }; RQ.PropertyData = new InputDataDTO() { viewCM = viewCm }; RQ.MonthInPathEnum = PastInMth; CMReferenceWS.CenoveMapyServiceClient Client = new CenoveMapyServiceClient();
wsCM_01_Response Response=Client.wsCM_01(RQ);
Stránka |5
3 WEBOVÉ SLUŽBY – 1. CENOVÉ MAPY – POPIS FUNKCÍ 3.1
wsCM_01
[OperationContract] [WebMethod(Description = "Vrátí informaci o tržní ceně nemovitosti v dané lokalitě")] public wsCM_01_Response wsCM_01(wsCM_01_Request Request);
wsCM_01_Request – vstupní parametry Název elementu
Typ
Poznámka
Locality
LocalityDTO
PropertyData
InputDataDTO
MonthInPathEnum
MonthInPast
Definice dotazované lokality nemovitosti, v které má být poskytnuta tržní cena. Viz 4. datové typy Definice dotazované nemovitosti a dalších parametrů pro zpřesnění ceny – Viz 4. datové typy Definice, v jaké časovém rozmezí realizovaných transakcí se bude prohledávat. Možnosti jsou 6, 12 a 24 měsíců zpětně.
4 DATOVÉ TYPY 4.1
LocalityDTO
LocalityDTO – informace o lokalitě Název elementu LocalityDefinition
Typ LocalityDefinitionDTO
Možné hodnoty Ulice Stavba
KOD
Int64
-
Poznámka Určuje, na jaké úrovni rozlišení oblasti (lokality) se bude tržní cena dotazovat, jedná se o enumerátor. V případě STAVBA, se bude dotazovat na cenu na úrovni adresního místa, v případě ULICE, se bude dotazovat na průměrnou cenu v rámci vybrané ulice. Jendná se o kód RUIAN (Ulice: ULICE_KOD, Stavby: STAVOBJ_KOD). Zda se jedná o kod ulice nebo stavby je určeno parametrem
LocalityDefinition
4.2
InputDataDTO
LocalityDTO – informace o lokalitě Název elementu viewCM
Povinný parametr ANO
Typ
Možné hodnoty
Poznámka
CM_Structures. ccViewCM
Byt_Prodej Byt_Prodej_Novostavba Byt_Prodej_NeNovostavba
výběr datové vrstvy (zdroje) pro poskytnutí tržní ceny. Detailní popis viz kapitola 5. Číselníky. Tento parametr definuje výběr kategorie nemovitost na kterou se dotazujeme + další související parametry.
Dum_Prodej Dum_Prodej_Novostavba Dum_Prodej_NeNovostavba Parcela_Stavebni Parcela_Pozemkova Parcela_Pozemkova_OrbnaPuda Parcela_Pozemkova_Zahrada
Stránka |6
Parcela_Pozemkova_Lesy usable_area
NE
int
estate_area
NE
int
rooms_count
NE
CM_Structures. iRooms
buildingCondition
NE
ccBuildingCondition
buildingType
NE
ccBuildingType
4.3
Obsahuje 3 int proměnné: kuchyn_count – počet kuchyní (zde se nejdená o kuchyňský kout, ale o místnost s oknem sloužící jako kuchyň.), pokoj_count – počet pokojů, a rooms_count - celkový počet obytných místnsotí VelmiDobry Dobry Spatny VeVystavbe Projekt Novostavba PredRekonstrukci PoRekonstrukci drevo cihla kamen montovany panel skelet smiseny
Užitná plocha, parametr využit pro nemovitosti z kategorie BYT, DŮM Plocha pozemku, parametr využit pro nemovitosti z kategorie POZEMKY, případně pro zpřesnění ceny u DOMU. Informace o tom, kolik obytných místností má dotazovaný byt. Pokud se zadá tento parametr, aplikace koriguje v rámci jedné stavby cenu pro různé typy dispozice.
Informace o stavu nemovitosti, jedná se o číselník – viz 5. Pokud se zadá tento parametr, aplikace koriguje cenu nemovitosti na základě významu vložené hodnoty. Informace, za jakého materiálu má být budova postavena, jedná se o číselník – viz 5. Pokud se zadá tento parametr, aplikace koriguje cenu nemovitosti na základě významu vložené hodnoty.
OutputDataDTO
Výstupní informace o ceně nemovitosti Název elementu Price_m2_mean
Typ Double
Price_m2_min
Double
Price_m2_max
Double
Price_m2_std
Double
Price_m2_median
Double
PropertyCount
int
PriceOfProperty
int
IsCalculatedByInterpolation
Boolean
Poznámka Podobně jako medián, ale jedná se o aritmetický průměr. Hodnota v Kč / m2. Minimální zjištěná tržní cena. Hodnota v Kč / m2. (statisticky výrazně odlehlé hodnoty se nezohledňují) Maximální zjisštěná tržní cena. Hodnota v Kč / m2. (statisticky výrazně odlehlé hodnoty se nezohledňují) Směrodatná odchylka z hodnot tržních cen, z kterých se počítá průměr a medián. Hodnota v Kč / m2. Tržní cena nemovitosti definovaná pro danou oblast, vstupní parametry a stáří dat. Obecně se jedná o hodnotu pořízenou z tržních cen více nemovitostí statistky vyhodnocenou jako medián. Zatím není implementováno. Hodnota v Kč / m2. Počet nemovitostí, jejichž tržní ceny jsou použity pro výpočet průměru a mediánu. Konečná tržní cena nemovitosti v Kč. Ta je k dispozici pouze pokud se zadá usable_area (byt, dům) nebo estate_area (pozemek) Pokud cena nemovitosti v aktuální adrese není k dispozici, je hodnota IsCalculatedByInterpolation=True. V takovém případě se hodnota tržní ceny získá ze 3 nejbližších staveb, u kterých je k dispozici tržní cena.
Stránka |7
5 ČÍSELNÍKY 5.1 Id 1 4
5.2 Id 1 2 3 4 5 6 8 9
5.3 Id 1 2 3 4 5 6 7
5.4 Id 6 12 24
5.5
LocalityDefinitionDTO Name Ulice Stavba
ccBuildingCondition Name VelmiDobry Dobry Spatny VeVystavbe Projekt Novostavba PredRekonstrukci PoRekonstrukci
ccBuildingType Name drevo cihla kamen montovany panel skelet smiseny
ccMonthInPast Name Month6 Month12 Month24
ccViewCM
Id 1 11
Name Byt_Prodej Byt_Prodej_Novostavba
12
Byt_Prodej_NeNovostavba
3 31
Dum_Prodej Dum_Prodej_Novostavba
Popis Základní kategorie – Byt, prodej, bez korekcí Kategorie – Byt, prodej, pouze pro stáří stavby do 3 let , cena je zpřesněna Kategorie – Byt, prodej, pouze pro stavby starší než 3 roky , cena je zpřesněna Základní kategorie – Dům, prodej, bez korekcí Kategorie – Dům, prodej, pouze pro stáří stavby do 3 let , cena je zpřesněna
Stránka |8
32
Dum_Prodej_NeNovostavba
Kategorie – Dům, prodej, pouze pro stavby starší než 3 roky , cena je zpřesněna
4 5 51 52 53
Parcela_Stavebni Parcela_Pozemkova Parcela_Pozemkova_OrbnaPuda Parcela_Pozemkova_Zahrada Parcela_Pozemkova_Lesy
Základní kategorie – Stavební parcela, prodej, bez korekcí Základní kategorie – Pozemková parcela, prodej, bez korekcí Pozemkový parcela, pouze Orná půda, prodej, bez korekcí Pozemkový parcela, pouze Zahrada, prodej, bez korekcí Pozemkový parcela, pouze Lesy, prodej, bez korekcí
