Dokumentace, WSDL

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>
<bindings>
<basicHttpBinding>
Stránka |4
<binding name="BasicHttpBinding_ICenoveMapyService" />
</basicHttpBinding>
</bindings>
<client>
<endpoint address=" https://ws.1cenovemapy.cz/CMService.svc"
binding="basicHttpBinding"
bindingConfiguration="BasicHttpBinding_ICenoveMapyService"
contract="CMReferenceWS.ICenoveMapyService"
name="BasicHttpBinding_ICenoveMapyService" />
</client>
</system.serviceModel>
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í