OctopusPro s.r.o.
Webové služby pro párování inzerátů Verze: 1.0
Datum vytvoření: Datum poslední aktualizace:
8.7. 2013 11.7.2013
Copyright OctopusPro s.r.o, Praha, 2012-2013
Obsah: 1
Úvod ................................................................................................................................................ 4 1.1
2
3
Základní popis .......................................................................................................................... 4
Služby............................................................................................................................................... 9 2.1
Seznam použitých webových služeb ....................................................................................... 9
2.2
ws_octop_pairing - Párování inzerátů .................................................................................. 10
Datové typy – Data transfer objekty ............................................................................................. 12 3.1
tHitDTO .................................................................................................................................. 12
3.2
OfferTypeDTO........................................................................................................................ 12
3.3
CategoryDTO ......................................................................................................................... 13
3.4
SubCategoryDTO ................................................................................................................... 13
3.5
RegionDTO ............................................................................................................................. 13
3.6
SubRegionDTO ....................................................................................................................... 13
3.7
CommercialModeDTO ........................................................................................................... 13
3.8
CountryDTO ........................................................................................................................... 13
3.9
OwnershipDTO ...................................................................................................................... 14
3.10
PairingAttributeCategoryIdDTO ............................................................................................ 14
3.11
PairingAttributeSubCategoryIdDTO ...................................................................................... 14
3.11.1
SubCategoryBytDTO ...................................................................................................... 14
3.11.2
SubCategoryParcelaDTO................................................................................................ 14
3.11.3
SubCategoryKomercniProstorDTO ................................................................................ 14
3.12
PairingAttributeOfferTypeIdDTO........................................................................................... 15
3.13
PairingAttributeCommercialModeIdDTO .............................................................................. 15
3.14
PairingAttributeCountryIdDTO .............................................................................................. 15
3.15
PairingAttributeSubRegionIdDTO .......................................................................................... 15
3.16
PairingAttributeMunicipalityDTO .......................................................................................... 15
3.17
PairingAttributeStreetDTO .................................................................................................... 16
3.18
PairingAttributeBuildingNumberDTO.................................................................................... 16
3.19
PairingAttributeCoordinateDTO ............................................................................................ 16
3.20
PairingAttributeAreaDTO ...................................................................................................... 16
3.21
PairingAttributePriceDTO ...................................................................................................... 16
3.22
PairingAttributeOwnershipIdDTO ......................................................................................... 16
3.23
PairingAttributeFulltextDTO .................................................................................................. 17
Číselníky. ................................................................................................................................................ 18 3.24
CC_Category .......................................................................................................................... 18
3.25
CC_SubCategory .................................................................................................................... 18
3.26
CC_CommercialMode ............................................................................................................ 18
3.27
CC_OfferType ........................................................................................................................ 18
3.28
CC_Region.............................................................................................................................. 19
3.28.1
4
Abecední řazení ............................................................................................................ 19
3.29
CC_SubRegion........................................................................................................................ 19
3.30
CC_Country ............................................................................................................................ 21
3.31
CC_Vlastnictvi ........................................................................................................................ 21
3.32
CC_ProfileType ...................................................................................................................... 21
Příklady .......................................................................................................................................... 23 4.1
ASP.NET aplikace ................................................................................................................... 23
4.1.1
Pomocná třída pro vytváření jednotlivých requestů na webovou službu:.................... 23
4.1.2
Ukázka volání některých služeb z repository ASP.NET aplikace .................................... 23
4.1.3
Vytvoření XML z navrácených dat: ................................................................................ 25
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. http://publicws.octopuspro.cz/OctopusProService.svc?wsdl K úspěšnému přihlášení do webové služby je nutné zažádat o přístupové údaje přímo u společnosti OctopusPro s.r.o. Jedná se o WCF služby, které jsou přístupné pouze s platným SSL certifikátem. Správné nastavení služeb je dále popsáno v příkladech, případně v kapitole Nastavení služeb.
1.2
Algoritmus párování
Pomocí kolekce atributů (cPairingAttribute) definujících nemovitost se definuje zdrojová nemovitost (oHitsource). Tato kolekce univerzálně popisuje všechny typy nemovitostí. Atributy z kolekce cPairingAttribute jsou dvojího typu. Povinné a nepovinné. Povinné atributy cPairingAttributeRequired musí být vždy definovány jako jediná hodnota (bez intervalu hodnot), která nesmí být NULL. Ostatní atributy (cPairingAttributeOptional - nepovinné) nemusí být definovány vůbec a mohou být reprezentovány hodnotou NULL. Klíčový atribut pro párování je atribut s názvem OfferTypeId, s hodnotami (nabídka nebo poptávka). Pro potřeby párování je definována množina různých nemovitostí cHittarget , které mají být spárovány se zdrojovou nemovitostí oHitsource podle níže uvedených pravidel. Výsledkem procesu párování je seznam nemovitostí cHitpaired, jako podmnožina cHittarget, splňující podmínky pro párování. Podmnožinou atributů cPairingAttribute jsou tzv. klíčové atributy cPairingAttributeKEY. Tyto atributy nabývají pouze diskrétních hodnot (z číselníků) a v procesu párování musí být identické jak v oHitsource tak v oHittarget a nesmí nabývat hodnot NULL ani na jedné straně páru (source-target) 1.2.1
Párovací toleranční okno
Podmnožinu atributů z kolekce cPairingAttribute, které nejsou z kolekce cPairingAttributeRequired, definujeme jako cPairingAttributeOptional . Tyto atributy nabývají převážně libovolné hodnoty, vždy mohou mít hodnotu NULL. Obecně platným párovacím pravidlem pro tuto kolekci atributů je skutečnost, že hodnoty těchto atributů v páru (source-target) jsou identické nebo blízké. Míru "blízkosti" definuje pro každý atribut párovací okno (oAtributOptionalWindow), což je v podstatě interval nejnižší a nejvyšší povolené hodnoty oAtributOptionalWindow.low, oAtributOptionalWindow.high. Aby byl považován určitý Atribut (páru source-target) za zpárovaný musí být splněna podmínka: oAtributOptionaltarget ϵ oAtributOptionalWindow.low, oAtributOptionalWindow.high kde hodnoty oAtributOptionalWindow.low, oAtributOptionalWindow.high jsou derivovány od hodnoty oAtributOptionalsource podle následujícho pravidla: oAtributOptionalWindow.low = oAtributOptionalsource ● (1 - oAtributOptionalWindow.px)
oAtributOptionalWindow.high = oAtributOptionalsource ● (1 + oAtributOptionalWindow.px) kde hodnota oAtributOptionalWindow.px reprezentuje pro každý atribut z kolekce oAtributOptional procenta šířky tolerančního okna. Tyto hodnoty jsou určeny implicitně (automatická volba párování) nebo je nastavuje uživatel (manuální párování) 1.2.2
Lokalizační atributy nemovitosti
Pro mechanizmus párování hraje speciální roli vymezení lokality a řídí se jinými pravidly než ostatní atributy cPairingAttributeOptional popsané výše. Atributy lokalizace nemovitosti (lokalizační atributy) jsou detailně popsány v tabulce níže. Atribut IdCountry je vždy povinný (kolekce cPairingAttributeRequired). Ostatní lokalizační atributy nemovitosti jsou z kolekce cPairingAttributeOptional . Dále platí následující sekvenční pravidla definující hierarchii významu jednotlivých lokalizačních atributů nemovitosti: 1.2.2.1 Párování s hierarchickými lokalizačními atributy
Pokud není definován atribut coordinate (tedy coordinate.X a coordinate.Y jsou NULL), jsou pro párování použity tzv. hierarchické lokalizační atributy. Ty jsou seřazeny podle významu lokalizace nemovitosti následovně: IdCountry → subRegion → municipality → street → building_cp nebo building_co. Pokud oHitsource některý z těchto atributů nemá (je NULL), s tím, že se test realizuje seshora od IdCountry, započne proces párování se všemi lokalizačními atributy od IdCountry až do atributu předešlému od tohoto atributu. Během párování se v oHittarget sledují všechny tyto lokalizační atributy. Pokud je v sledovaném oHittarget některý z těchto atributů NULL, je nemovitost pro párování diskvalifikována. Z výše uvedeného vyplývá pro oHitsource : Pokud je atribut subRegion NULL, je lokalizace párována pouze na úrovni IdCountry. Pokud je atribut municipality NULL, je lokalizace párována pouze na úrovni subRegion. Pokud je atribut street NULL, je lokalizace párována pouze na úrovni municipality. Pokud je atribut building_cp and building_co NULL, je lokalizace párována pouze na úrovni street.
příklad: pro oHitsource jsou definovány lokalizační atributy: (IdCounty=1, subRegion=1, municipality='Praha', street='Americká') pro cHittarget budou například vyřazeny: oHittarget : (IdCounty=1, subRegion=1, municipality='Praha', street='Lodecká') oHittarget : (IdCounty=1, subRegion=1, municipality='Brno', street='Americká') oHittarget : (IdCounty=1, subRegion=1, municipality=NULL, street='Americká') oHittarget : (IdCounty=1, subRegion=2, municipality='Praha', street='Lodecká') oHittarget : (IdCounty=1, subRegion=NULL, municipality='Praha', street='Lodecká')
1.2.2.2 Párování s lokalizační atributem coordinate
Pokud je definován atribut coordinate (coordinate.X a coordinate.Y jsou různý od NULL), je realizováno párování s jediným lokalizačním atributem coordinate. Všechny nemovitosti z cHittarget, které neleží v oblasti definované kružnici se středem coordinate.X a coordinate.Y a poloměrem coordinate.radius nebudou zpárovány s oHitsource. 1.2.3
Pravidla párování
Každá z nemovitostí oHittarget v kolekci cHittarget , která má být párovatelná s oHitsource, musí splňovat následující kritéria: a) b) c) d)
atribut offerTypeId pro oHitsource musí být u všech zpárovaných oHittarget opačný atributy cPairingAttributeKEY pro oHitsource musí být u všech zpárovaných oHittarget identický všechny atributy cPairingAttributeRequired pro oHittarget nesmí být NULL všechny cPairingAttributeOptional v oHitsource, které nemají hodnotu NULL, nesmí mít hodnotu NULL také v oHittarget (v programu bude možné tuto podmínku volitelně ignorovat) e) všechny cPairingAttributeOptional (kromě Lokalizačních atributů) v oHitsource, které nemají hodnotu NULL, musejí splňovat podmínku: oAtributOptionaltarget ϵ oAtributOptionalWindow.low, oAtributOptionalWindow.high. Pokud některý atribut nepadne do tolerančního okna, k zpárování (source-target) nedojde. Pokud je podmínka d) ignorována, pak jsou testovány pouze ty atributy z cPairingAttributeOptional , které jsou v oHittarget různé od NULL a zároveň jsou v oHitsource různé od NULL.¨ f) Lokalizační atributy se párují speciálním algoritmem popsaným v kapitole: "Lokalizační atributy nemovitosti "
oAtribute CategoryId
popis kategorie nemovitosti
oAtributRequired
oAtributKEY
oAtributOptional
oAtributOptional Window.px
ano
ano
-
-
oAtributRequired
oAtributKEY
oAtributOptional
ano ano ano ano ano ano ano -
ano ano ano ano ano ano ano ano ano ano ano ano
ano ano ano ano ano
podkategorie (další dělení Kategorie):
lokalizační atributy
SubCategoryId
SubCategoryID
bit mask
Kategorie
CategoryID
význam
6 7 8 9 10 11 12 19 20 24 25 26
16 32 64 128 256 512 1024 1 2 1 2 4
byt
1 1 1 1 1 1 1 4 4 6 6 6
1+1 2+1 3+1 4+1 5+1 >5+1 Garsoniéra Stavební Ostatní Obchodní Sklad Výroba
parcela Komerční prostora
OfferTypeId
nabídka/poptávka
ano
-
-
-
CommercialModeId
prodej/pronájem
ano
ano
-
-
CountryId
kód země
ano
ano
-
-
kód pro okres nebo obvod (velké město) – číselník OctopusPro
-
ano
ano
-
jméno obce
-
ano
ano
-
Street
jméno ulice
-
ano
ano
-
BuildingNumber
číslo popisné, číslo orientační
-
ano
ano
-
X,Y souřadnice (WGS. JTSK - RUIAN) Poloměr (radius) v m od středu (X,Y)
-
-
ano
-
SubRegionId Municipality
Coordinate
Area2
plocha nemovitosti
-
-
ano
35
cena nemovitosti
-
-
ano
35
OwnershipId
kód vlastnictví
-
ano
ano
-
FullText
volný text
-
ano
ano
-
Price
3
1) atribut je kalkulován v procesu párování pouze pro IdCategory (byt, dům) 2) atribut je v jednotkách m2 3) atribut je platný pro všechny kategorie, pro commercialMode=Prodej jsou hodnoty atributu absolutní, pro commercialMode=Pronájem, jsou hodnoty relativní, vztažené na 1 měsíc.
2
SLUŽBY Všechny webové služby mají jeden vstupní a jeden výstupní parametr. Vstupní parametr tzv. „request“ parametr je odvozený od základní třídy RequestBase. Výstupní parametr tzv. „response“ je odvozený od třídy ResponseBase. Popis jednotlivých parametrů následuje:
RequestBase – základní třída pro vstupní parametr web.služby Název elementu
Typ
Možné hodnoty
Poznámka
ClientTag
string
-
ClientUsername
string
-
ClientPassword
string
-
RequestId
string
-
Identifikace klienta WS – ClientTag je přidělen společně s přístupovými údaji k WS Uživatelské jméno klienta – přístupové údaje k WS Uživatelské heslo klienta – přístupové údaje k WS Unikatni GUID requestu, který ho identifikuje
LoadOptions
string[]
-
Action
String
-
Nepovinné pole parametrů udávající doplňující požadavky na vrácená data. Např. načtení číselníku k vráceným datům atd. Nepovinné pole pomocí něhož je možné vyvolat speciální akce definované u jednotlivých služeb
ResponseBase – základní třída pro výstupní parametr web.služby Název elementu
Typ
Možné hodnoty
Poznámka
Acknowledge
AcknowledgeType
Success, Failed
Message
String
-
ComparationId
string
-
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 Unikatni GUID requestu, pro který byl votvořen tento response
RowsAffected
int
-
Počet navrácených záznamů, pokud to vzhledem k charakteru WS dává smysl
Version
string
-
Verze WS
Build
string
-
Build WS
ReservationId
string
-
ReservationExpires
Datetime
-
Vyhrazeno pro dlouhotrvající requesty, zatím nepoužito Vyhrazeno pro dlouhotrvající requesty, zatím nepoužito
2.1
Seznam použitých webových služeb
Jméno služby
Poznámka
ws_octop_pairing
Služba pro párování inzerce
2.2
ws_octop_pairing - Párování inzerátů
[WsdlDocumentation("Služba pro párování inzerátu podle daných pravidel s využitím PairingAttributes")] tHitResponse ws_octop_pairing(ws_pairing_Request request);
Služba pro párování nemovitostí. Vlastní párování probíhá podle dokumentu „Párování OCTOPUSPRO“. Ve ws_pairing_Request do metody vstupují párovací atributy, které popisují párovanou nemovitost. Prostřednictvím tHitResponse jsou následně vráceny napárované inzeráty. ws_pairing_Request – vstupní parametry
povinné atributy jsou označeny tučně Název elementu
Typ
IdUser
Int
ResultAgeDays
int
(0, 365>
PairingSourceType
Int
CategoryId
PairingAttributeCategoryIdDTO
1-soukromá inzerce, 2- inzerce RK 4 – obojí CC_Category
SubCategoryId
PairingAttributeSubCategoryIdDTO
OfferTypeId
PairingAttributeOfferTypeIdDTO
CC_OfferType
CommercialModeId
PairingAttributeCommercialModeIdDTO
CC_CommercialMode
CountryId SubRegionId
PairingAttributeCountryIdDTO PairingAttributeSubRegionIdDTO
CC_Country CC_SubRegion
Municipality Street BuildingNumber
PairingAttributeMunicipalityDTO PairingAttributeStreetDTO PairingAttributeBuildingNumberDTO
Coordinate
PairingAttributeCoordinateDTO
Area
PairingAttributeAreaDTO
Price OwnershipId
PairingAttributePriceDTO PairingAttributeOwnershipIdDTO
Fulltext
PairingAttributeFulltextDTO
tHitResponse – výstupní parametry
Možné hodnoty
CC_Vlastnictvi
Poznámka Identifikace uživatele, který provádí párování Maxilmální počet dní pro stáří párovaného inzerátu Zdroj inzerátů pro párování Párovací atribut – kategorie nemovitosti Nepovinný subkategorie nemovitosti Povinný atribut. Nabídka / poptávka Povinný atribut druh transakce. Prodej / pronájem Povinný atribut – země Nepovinný atribut – okres nebo obvod Nepovinný atribut – Obec Nepovinný atribut – Ulice Cislo popisné nebo evidenční stavby Nepovinný atribut – souřadnice nemovitosti. Tento atrbut má přednost před hledáním podle ostatních atributů lokality – SubRegionId, Municipality, Street, BuildingNumber Nepovinný atribut – plocha Nepovinný atribut – cena Nepovinný atribut – Vlastnictví Nepovinný atribut – Fulltext
Název elementu
Typ
Možné hodnoty
Poznámka
tHits TotalRecords
tHitDTO[] Int
-
Pole tHitDTO – seznam záznamů (inzerátů) Počet vrácených záznamů
3
DATOVÉ TYPY – DATA TRANSFER OBJEKTY
3.1
tHitDTO
Transfer objekt pro záznam monitoringu realit. Název elementu
Typ
Možné hodnoty
Poznámka
IdHit Type IdCategory
int int int
1 CC_Category
Id záznamu Typ záznamu – monitoring realit Kategorie nemovitosti
SubCategory
int
CC_SubCategory
Upřesnění kategorie nemovitosti
OfferType
int
CC_OfferType
Nabídka / poptávka
CommercialMode
int
CC_CommercialMode
Prodej / pronájem
IdRegion
Int?
CC_Region
Kraj
SubRegion IdPortal BodyText BodyStampHash Phone1 Phone2 Phone3 DateOfFirstRelease DateOfLastChange DetailURL ClientSMS Price DateOfGrab AdvertID IdRA Locality Area nameRA IdCountry IdVlastnictvi HitRepeatCount Email Publisher PhoneRepeatCount jtskx jtsky kodKatastralUzemi Obec
Int? int string int Long? Long? Long? DateTime? DateTime? string string int? Datetime string int? string int? string int? int? Int? string string int? Long? Long? Int? string
CC_SubRegion Číselník Číselník CC_Country CC_Vlastnictvi -
Část kraje Id zdroje Text inzerátu Hash textu inzerátu Telefon 1 Telefon 2 Telefon 3 Datum zadání inzerátu Datum poslední změny inzerátu Url inzerátu Volné pole Cena Datum vygrabování ID inzerátu na zdrojovém portálu Id realitní kanceláře Lokalita - ulice Plocha nemovitosti Název realitní kanceláře Země inzerátu Typ vlastnictví Počet opakování inzerátu Email Jméno vydavatele Počet opakování tel.čísla Souřadnice na mapě - X Souřadnice na mapě - Y Kód katastrálního území Obec
3.2
OfferTypeDTO
Transfer objekt pro záznam číselníku OfferType. Název elementu
Typ
Možné hodnoty
Poznámka
OfferType OfferTypeName
int string
CC_OfferType CC_OfferType
ID OfferType Název OfferType
3.3
CategoryDTO
Transfer objekt pro záznam číselníku Category. Název elementu
Typ
Možné hodnoty
Poznámka
IdCategory Category CategoryName CategoryAbbrev
int int string string
CC_Category CC_Category CC_Category CC_Category
Id kategorie Bitová hodnota kategorie Název kategorie Zkratka názvu kategorie
3.4
SubCategoryDTO
Transfer objekt pro záznam číselníku SubCategory. Název elementu
Typ
Možné hodnoty
Poznámka
IdSubCategory SubCategory
int int
CC_SubCategory CC_SubCategory
IdCategory SubCategoryName SubCategoryAbbrev
Int string string
CC_SubCategory CC_SubCategory CC_SubCategory
Id sub kategorie – vždy unikátní Bitová hodnota dané sub kategorie – unikátní v rámci jedné kategorie Id hlavní kategorie Název sub kategorie Zkratka názvu sub kategorie
3.5
RegionDTO
Transfer objekt pro záznam číselníku Region. Název elementu
Typ
Možné hodnoty
Poznámka
IdRegion Region RegionName
int int string
CC_Region CC_Region CC_Region
Id regionu Bitová hodnota regionu Název regionu
3.6
SubRegionDTO
Transfer objekt pro záznam číselníku SubRegion. Název elementu
Typ
Možné hodnoty
Poznámka
IdSubRegion IdRegion SubRegionName
int int string
CC_SubRegion CC_SubRegion CC_SubRegion
Id subregionu Id regionu Název subregionu
3.7
CommercialModeDTO
Transfer objekt pro záznam číselníku CommercialMode. Název elementu
Typ
Možné hodnoty
Poznámka
IdCommercialMode CommercialMode CommercialModeName
int int string
CC_CommercialMode CC_CommercialMode CC_CommercialMode
Id typu obchodu Bitová hodnota typu obchodu Název typu obchodu
3.8
CountryDTO
transfer objekt pro specifikaci země
Název elementu
Typ
Možné hodnoty
Poznámka
IdCountry CountryName
int string
CC_Country CC_Country
Id země Název země
3.9
OwnershipDTO
Transfer objekt objekt pro specifikaci vlastnictví Název elementu
Typ
Možné hodnoty
Poznámka
IdOwnership OwnershipName
int string
CC_Vlastnictvi CC_Vlastnictvi
Id vlastnictví Název vlastnictví
3.10 PairingAttributeCategoryIdDTO Transfer objekt pro párovací atribut – kategorie nemovitosti Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Category
string bool CategoryDTO
CategoryId true CC_Category
Název atributu Je vyžadovaný? Číselník kategorie nemovitosti
3.11 PairingAttributeSubCategoryIdDTO Transfer objekt pro párovací atribut – subkategorie nemovitosti Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired SubCategoryByt
string bool SubCategoryBytDTO
SubCategoryId false -
SubCategoryParcela
SubCategoryParcelaDTO
-
SubCategoryKomercniProstor
SubCategoryKomercniProstorDTO
-
Název atributu Je vyžadovaný? Subkategorie bytu viz. CC_SubCategory. Subkategorie parcely viz CC_SubCategory Subkategorie komerčního prostoru viz. CC_SubCategory.
3.11.1 SubCategoryBytDTO Transfer objekt pro párovací atribut – subkategorie bytu Název elementu
Typ
Možné hodnoty
Poznámka
DispositionGarsoniera Disposition11 Disposition21 Disposition31 Disposition41 Disposition51 DispositionGreaterThan51
bool bool bool bool bool bool bool
True/false True/false True/false True/false True/false True/false True/false
Párovat garsoniery Párovat 1+1 Párovat 2+1 Párovat 3+1 Párovat 4+1 Párovat 5+1 Párovat > 5+1
3.11.2 SubCategoryParcelaDTO Transfer objekt pro párovací atribut – subkategorie parcely Název elementu
Typ
Možné hodnoty
Poznámka
Stavebni Ostatni
Bool? Bool?
True/false/null True/false/null
Párovat stavební pozemky Párovat ostatní pozemky
3.11.3 SubCategoryKomercniProstorDTO Transfer objekt pro párovací atribut – subkategorie komerční prostory
Název elementu
Typ
Možné hodnoty
Poznámka
Obchodni Sklad Vyroba
Bool? Bool? Bool?
True/false/null True/false/null True/false/null
Párovat obchodní prostory Párovat sklady Párovat výrobu
3.12 PairingAttributeOfferTypeIdDTO Transfer objekt pro párovací atribut – offer type (nabídka / poptávka) Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired OfferType
string bool OfferTypeDTO
OfferTypeId true
Název atributu Je vyžadovaný? Číselník offerType viz. CC_OfferType
3.13 PairingAttributeCommercialModeIdDTO Transfer objekt pro párovací atribut – commercialMode nemovitosti (prodej / pronájem) Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired CommercialMode
string bool CommercialModeDTO
CommercialModeId true
Název atributu Je vyžadovaný? Číselník CommercialMode viz. CC_CommercialMode
3.14 PairingAttributeCountryIdDTO Transfer objekt pro párovací atribut – země nemovitosti Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Country
string bool CountryDTO
CountryId true
Název atributu Je vyžadovaný? Číselník zemí viz. CC_Country
3.15 PairingAttributeSubRegionIdDTO Transfer objekt pro párovací atribut – commercialMode nemovitosti (prodej / pronájem) Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired SubRegions
string bool SubRegionDTO[]
SubRegionId false
Název atributu Je vyžadovaný? Číselník SubRegionDTO viz.3.10.
3.16 PairingAttributeMunicipalityDTO Transfer objekt pro párovací atribut – Obec Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Municipality
string bool string
Municipality false
Název atributu Je vyžadovaný? Název obce
3.17 PairingAttributeStreetDTO Transfer objekt pro párovací atribut – ulice Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Street
string bool string
Street false
Název atributu Je vyžadovaný? Název ulice
3.18 PairingAttributeBuildingNumberDTO Transfer objekt pro párovací atribut – číslo popisné/orientační Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Cp Co
string bool string string
BuildingCpCo false
Název atributu Je vyžadovaný? Číslo popisné Číslo orientační
3.19 PairingAttributeCoordinateDTO Transfer objekt pro párovací atribut – souřadnice nemovitosti Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired X Y CoordinateType Radius
string bool Double Double iCoordinateType double
Coordinate false
Název atributu Je vyžadovaný? Souřadnice X Souřadnice Y Typ zadaných souřadnic Radius v (m)
JTSK,WSG84
3.20 PairingAttributeAreaDTO Transfer objekt pro párovací atribut – plocha Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Area WindowPx
string bool int double
Area false
Název atributu Je vyžadovaný? Plocha Odchylka v procentech od zadané hdontoy (defaultně 35%}
3.21 PairingAttributePriceDTO Transfer objekt pro párovací atribut – cena Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Price WindowPx
string bool decimal double
Price false
Název atributu Je vyžadovaný? Cena Odchylka v procentech od zadané hdontoy (defaultně 35%}
Možné hodnoty
Poznámka
3.22 PairingAttributeOwnershipIdDTO Transfer objekt pro párovací atribut – vlastnictví Název elementu
Typ
AttributeName IsRequired OfferType
string bool OfferTypeDTO
OwnershipId false
Název atributu Je vyžadovaný? Číselník vlastnictví viz. CC_Vlastnictvi
3.23 PairingAttributeFulltextDTO Transfer objekt pro párovací atribut – fulltext Název elementu
Typ
Možné hodnoty
Poznámka
AttributeName IsRequired Fulltext
string bool string
OwnershipId false
Název atributu Je vyžadovaný? Volný text pro párování
ČÍSELNÍKY. 3.24 CC_Category IdCategory
Category
CategoryName
CategoryAbbrev
1 2 4 5 6 7 8 9
1 2 4 8 16 32 64 128
Byty Domy Pozemky Chaty Komerční prostory Kanceláře Garáže Developerské projekty
BYT DUM POZ CHAT KP KANC GAR DEV
CategoryDescription Rodinné domy, činžovní domy, hotely Stavební pozemky, pole, lesy
3.25 CC_SubCategory IdSubCategory
SubCategory
IdCategory
SubCategoryName
SubCategoryAbbrev
2 3 4 5 6 7 8 9 10 11 12 16 17 18 13 14 15 19 20 21 22 23 24 25 26 27 28
1 2 4 8 16 32 64 128 256 512 1024 2048 4096 8192 1 2 4 1 2 1 2 4 1 2 4 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 4 4 5 5 5 6 6 6 7 8
< 40 m2 40 - 60 m2 60 - 100 m2 > 100 m2 1+1 2+1 3+1 4+1 5+1 >5+1 Garsoniera < 10 tis. 10 - 20 tis. > 20 tis. < 2 mil. 2 - 5 mil. > 5 mil. Stavební Ostatní < 0.5 mil. 0.5 - 1 mil. > 1 mil. Obchodní Sklad Výroba
B40 B40_60 B60_100 B100 B1a1 B2a1 B3a1 B4a1 B5a1 Bup5a1 Bgars R10 R10_20 R20 D2 D2_5 D5 PSTAV POST CH5 CH5_10 CH10 KPOBCH KPSKLAD KPVYR
Byty
pronájem
Domy
Pozemky Chaty
Komerční prostory
Kanceláře Garáže
3.26 CC_CommercialMode IdCommercialMode
CommercialMode
CommercialModeName
1 2
1 2
Prodej Pronájem
3.27 CC_OfferType IdOfferType
OfferType
OfferTypeName
1 2
1 2
Nabídka Poptávka
prodej
3.28 CC_Region IdRegion
Region
RegionName
1 2 3 4 5 6 7 8 9 10 11 12 13 14
1 2 4 8 16 32 64 128 256 512 1024 2048 4096 8192
Praha Středočeský Jihočeský Plzeňský Karlovarský Ústecký Liberecký Královéhradecký Pardubický Vysočina Jihomoravský Olomoucký Moravskoslezský Zlínský
3.28.1 Abecední řazení IdRegion
Region
RegionName
3 11 5 8 7 13 12 9 4 1 2 6 10 14
4 1024 16 128 64 4096 2048 256 8 1 2 32 512 8192
Jihočeský Jihomoravský Karlovarský Královéhradecký Liberecký Moravskoslezský Olomoucký Pardubický Plzeňský Praha Středočeský Ústecký Vysočina Zlínský
3.29 CC_SubRegion IdSubRegion
IdRegion
RegionName
IdSubRegion
IdRegion
RegionName
105 49 58 50 51 52 53 54 55 56 57 88 59 60 61 62 63 64 65 106 66 69 70 68
1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2
nepřiřazeno Praha 1 Praha 10 Praha 2 Praha 3 Praha 4 Praha 5 Praha 6 Praha 7 Praha 8 Praha 9 Praha hl.m. Benešov Beroun Kladno Kolín Kutná Hora Mělník Mladá Boleslav nepřiřazeno Nymburk Praha-východ Praha-západ Příbram
30 31 89 32 84 118 85 86 87 208 197 198 199 200 201 119 122 120 121 124 125 126 130 127
13 13 13 13 14 14 14 14 14 15 15 15 15 15 15 15 15 15 15 16 16 16 16 16
Nový Jičín Opava Ostrava Ostrava - město Kroměříž nepřiřazeno Uherské Hradiště Vsetín Zlín Bratislava Bratislava I Bratislava II Bratislava III Bratislava IV Bratislava V Malacky nepřiřazeno Pezinok Senec Dunajská Streda Galanta Hlohovec nepřiřazeno Piešťany
71 1 2 3 107 4 5 6 7 42 43 108 90 46 44 45 47 48 15 16 109 17 72 73 74 75 76 110 77 78 23 93 24 25 111 26 18 19 20 112 21 22 38 113 39 40 41 79 80 114 81 82 83 8 92 10 9 11 12 115
2 3 3 3 3 3 3 3 3 4 4 4 4 4 4 4 4 4 5 5 5 5 6 6 6 6 6 6 6 6 7 7 7 7 7 7 8 8 8 8 8 8 9 9 9 9 9 10 10 10 10 10 10 11 11 11 11 11 11 11
Rakovník České Budějovice Český Krumlov Jindřichův Hradec nepřiřazeno Písek Prachatice Strakonice Tábor Domažlice Klatovy nepřiřazeno Plzeň Plzeň-jih Plzeň-město Plzeň-sever Rokycany Tachov Cheb Karlovy Vary nepřiřazeno Sokolov Děčín Chomutov Litoměřice Louny Most nepřiřazeno Teplice Ústí nad Labem Česká Lípa Jablonec n/N Jablonec nad Nisou Liberec nepřiřazeno Semily Hradec Králové Jičín Náchod nepřiřazeno Rychnov nad Kněžnou Trutnov Chrudim nepřiřazeno Pardubice Svitavy Ústí nad Orlicí Havlíčkův Brod Jihlava nepřiřazeno Pelhřimov Třebíč Žďár nad Sázavou Blansko Brno Brno-město Brno-venkov Břeclav Hodonín nepřiřazeno
128 129 123 132 133 196 139 134 135 137 136 138 131 141 142 147 140 143 144 145 146 149 150 151 152 153 154 155 159 156 157 158 148 160 161 162 163 164 165 173 166 167 168 169 170 171 172 175 176 177 178 179 187 180 174 181 182 183 184 185
16 16 16 17 17 17 17 17 17 17 17 17 17 18 18 18 18 18 18 18 18 19 19 19 19 19 19 19 19 19 19 19 19 20 20 20 20 20 20 20 20 20 20 20 20 20 20 21 21 21 21 21 21 21 21 21 21 21 21 21
Senica Skalica Trnava Bánovce nad Bebravou Ilava Myjava nepřiřazeno Nové Mesto nad Váhom Partizánske Považská Bystrica Prievidza Púchov Trenčín Komárno Levice nepřiřazeno Nitra Nové Zámky Šaľa Topoľčany Zlaté Moravce Bytča Čadca Dolný Kubín Kysucké Nové Mesto Liptovský Mikuláš Martin Námestovo nepřiřazeno Ružomberok Turčianske Teplice Tvrdošín Žilina Banská Bystrica Banská Štiavnica Brezno Detva Krupina Lučenec nepřiřazeno Poltár Revúca Rimavská Sobota Veľký Krtíš Zvolen Žarnovica Žiar nad Hronom Bardejov Humenné Kežmarok Levoča Medzilaborce nepřiřazeno Poprad Prešov Sabinov Snina Stará Ľubovňa Stropkov Svidník
13 14 33 116 34 35 36 37 27 28 29 117
11 11 12 12 12 12 12 12 13 13 13 13
Vyškov Znojmo Jeseník nepřiřazeno Olomouc Prostějov Přerov Šumperk Bruntál Frýdek Místek Karviná nepřiřazeno
3.30 CC_Country IdOfferType
OfferType
1 2 3 4 5 6 7 8 9 10 99
CZ SK
NĚMECKO RAKOUSKO CHORVATSKO ITÁLIE ŠPANĚLSKO BULHARSKO EGYPT MAĎARSKO ZAHRANIČÍ
3.31 CC_Vlastnictvi IdVlastnictví 1 2 3 4
Vlastnictví družstevní nájem obecni osobni
3.32 CC_ProfileType Typ služby, výstupních nebo vyhledávaných dat IdService 1 2 3 4 5 6 7 8 9 10 11 117 118
Service SoukromaInzerce Exekuce Drazby Privatizace HlidacLV HlidacCenNemovitosti TipovaHypotek PodobnaNemovitostvOkoli VyhledavacVlastnikaNemovitosti HlidacNemovitostiVlastnika Párování nemovitostí ESO_ BezplatnaInzerce ESO_OsobniMakler
186 188 202 203 204 205 206 207 189 190 195 191 192 193 194
21 22 22 22 22 22 22 22 22 22 22 22 22 22 22
Vranov nad Topľou Gelnica Košice I Košice II Košice III Košice IV Košice V Košice-okolie Michalovce Moldava nad Bodvou nepřiřazeno Rožňava Sobrance Spišská Nová Ves Trebišov
119 120
ESO_openMLS ESO_CenoveMapy
4
PŘÍKLADY
4.1
ASP.NET aplikace
Všechny ukázky kódu jsou součástí demo aplikace, která je ke stažení na internetových stránkách společnosti OctopusPro. Projekt demo aplikace pro párování inzerátů je v namespace Octop.Pairing.Web. Demo aplikaci je možné stáhnout na adrese http://pairing.octopuspro.cz 4.1.1
Pomocná třída pro vytváření jednotlivých requestů na webovou službu:
public static class RequestHelper { /// <summary> /// The Client Tag. /// public static string ClientTag { get; private set; } public static string ClientUsername { get; private set; } public static string ClientPassword { get; private set; } /// <summary> /// Static constructor. Reads from web.config and then stores it in memory. /// static RequestHelper() { ClientTag = ConfigurationManager.AppSettings.Get("ClientTag"); ClientUsername = ConfigurationManager.AppSettings.Get("ClientUsername"); ClientPassword = ConfigurationManager.AppSettings.Get("ClientPassword"); }
public static T Prepare
(this T request) where T : RequestBase { request.RequestId = RequestId; request.ClientTag = ClientTag; request.ClientUsername = ClientUsername; request.ClientPassword = ClientPassword; return request; } /// <summary> /// Generates unique request identifier (a Guid) /// public static string RequestId { get { return Guid.NewGuid().ToString(); } } }
4.1.2
Ukázka volání některých služeb z repository ASP.NET aplikace
/// <summary> /// Metoda pro vytvoreni requestu pro volani metody parovani z povinných atributů /// /// <param name="IdUser"> /// <param name="MaxAdvertAgeDays"> /// <param name="IdCategory"> /// <param name="IdOfferType"> /// <param name="IdCommercialMode"> /// <param name="IdCountry"> /// public ws_pairing_Request PreparePairingRequest(int IdUser,
int int int int int
MaxAdvertAgeDays, IdCategory, IdOfferType, IdCommercialMode, IdCountry)
{ //vytvor request ws_pairing_Request request = new ws_pairing_Request().Prepare(); request.IdUser = IdUser; request.ResultAgeDays = MaxAdvertAgeDays; request.CategoryId = new PairingAttributeCategoryIdDTO() { Category = new CategoryDTO() { IdCategory = IdCategory} }; request.OfferTypeId = new PairingAttributeOfferTypeIdDTO() { OfferType = new OfferTypeDTO() {OfferType = IdOfferType } }; request.CommercialModeId = new PairingAttributeCommercialModeIdDTO() { CommercialMode = new CommercialModeDTO() { IdCommercialMode = IdCommercialMode }}; request.CountryId = new PairingAttributeCountryIdDTO() { Country = new CountryDTO() { IdCountry = 1 }}; return request; } /// <summary> /// Metoda vykonavajici vlastni parovani /// /// <param name="request"> /// public tHitDTO[] ProcessPairing(ws_pairing_Request request) { //zavolej WS var response = Client.ws_octop_pairing(request); Correlate(request, response); if (response.Acknowledge == AcknowledgeType.Failure) { throw new ApplicationException(response.Message); } return response.tHits; } /// <summary> /// Metoda pro získání číselníku subregionů (možnost filtrace podle IdRegion) /// public SubRegionDTO[] Get_LOV_SubRegion(int? idRegion) { LOV_SubRegionRequest request = new LOV_SubRegionRequest().Prepare(); request.IdRegion = idRegion; var response = Client.ws_octop_get_LOV_SubRegion(request); Correlate(request, response); if (response.Acknowledge == AcknowledgeType.Failure) { throw new ApplicationException(response.Message); } return response.SubRegions; } /// <summary> /// Metoda pro získání číselníku regionů (možnost filtrace podle IdRegion) /// public RegionDTO[] Get_LOV_Region(int? idRegion) { LOV_RegionRequest request = new LOV_RegionRequest().Prepare();
request.IdRegion = idRegion; var response = Client.ws_octop_get_LOV_Region(request); Correlate(request, response); if (response.Acknowledge == AcknowledgeType.Failure) { throw new ApplicationException(response.Message); } return response.Regions; }
4.1.3
Ukázka práce s atributy
Přidání atributu souřadnic (hodnoty jsou v příkladu nenastavené): private void CoordinateExample() { int IdUser = -1; int ResultAgeDays = 365; int IdCategory = 1; int IdOfferType = 1; int IdCommercialMode = 1; int IdCountry = 1; double X, Y, Radius = 0; //priprava zakladniho requestu var request = octoRepository.PreparePairingRequest(IdUser, ResultAgeDays, IdCategory, IdOfferType, IdCommercialMode, IdCountry ); //moznost volby typu souradnic iCoordinateType.WGS84 nebo iCoordinateType.JTSK request.Coordinate = new PairingAttributeCoordinateDTO() { CoordinateType = iCoordinateType.JTSK, X = X, Y = Y, Radius = Radius }; }
4.1.4
Vytvoření XML z navrácených dat:
string CreateXml(tHitDTO oHit) { XmlSerializer serializer = new XmlSerializer(oHit.GetType()); MemoryStream ms = new MemoryStream(); XmlTextWriter xmlWriter = new XmlTextWriter(ms, Encoding.UTF8); serializer.Serialize(xmlWriter, oHit); ms = (MemoryStream)xmlWriter.BaseStream; ms.Seek(0, SeekOrigin.Begin); string xml = ""; using (StreamReader reader = new StreamReader(ms)) { xml = HttpUtility.HtmlEncode(reader.ReadToEnd()); } xmlWriter.Close(); ms.Close(); return xml; }
