Boligportal.dk s kravspecifikation til XML-feed

Boligportal.dk s kravspecifikation til XML-feed Introduktion I forbindelse med automatisk import af lejeboliger til Boligportal.dk skal der udarbejdes en XML-feed, som Boligportal.dk kan hente på en URL. Et eksempel på dette kunne være: http://www.ditdomæne.dk/export/boligportal_xml.php Denne genererer ved kald en XML-fil ud fra nedenstående specifikationer. BoligPortal.dk foretager en import af XML-filen fem gange i døgnet. Felt specifikation Alle xml-filer har et rod element: <annoncer> Dertil kan komme et vilkårligt antal elementer af type <annonce> <annonce> har 2 attributer: 1) journalnummer, denne må max være 13 chars lang, 2) ver, som angiver versionen på annonce xml. Hvis en annonce ikke længere fremkommer i den xml, der hentes, antages det, at lejemålet er udlejet, og annoncen bliver derfor markeret udlejet på Boligportal.dk. Medtages annoncen igen i xml-udtrækket, genindrykkes annoncen automatisk på Boligportal.dk med de opdaterede annonceoplysninger. Endvidere skal følgende krav til tekst og tegnsætning opfyldes: XML skal encodes som ISO-8859-1 1

Felter, elementer og attributter Beskrivelse Restriktion annoncer Rod element Må kun indeholde et vilkårligt antal annoncefelter(minimum 1) annonce ver Dette element indeholder al information om et givent lejemål. Angiver hvilken version af boligportal xml import scriptet, der sendes til. Dette element skal indeholde følgende elementer: storudlejerid, sidstrettetdato, bolig, overskrift, tekst, kontakt og kan eventuelt indeholde 1 billedeelement og eventuelt 1 attribut: journalnummer. Pt. er værdien = 1.2 journalnummer Journalnummer på lejemålet i storudlejerens eget system. Restriktion, max 13 tegn. storudlejerid sidstrettetdato bolig Unikt id der identificerer det enkelte lejemål. Dette kan både være tal og bogstaver, men det skal være unikt for hvert lejemål. Dette skal være unix timestamp der angiver hvornår annoncen sidst blev rettet Indeholder information om boligen. 1/2-felter: Der skal være en værdi og den skal være unik for hvert lejemål. Skal være et tal. Alle attributter er optional. Har 5 attributter: accontoforbrug, depositum, forudbetaltleje, indskud og reserveret. 1 = Ja 2= Nej Skal indeholde type, husleje, kvm, overtagelsesdato, moebleret, adresse, husdyr, delevenlig. Alle disse er 1/2 felter som betyder hhv. ja og nej. reserveret Angiver om boligen er reserveret 1 = ja Kun 1 og 2 er mulige værdier for denne attribut. optional. 2

2 = nej accontoforbrug Angiver boligens á conto-forbrug Dette skal være et heltal. Optional. depositum Depositum for boligen Dette skal være et heltal. Optional. Indskud Indskud for boligen Dette skal være et heltal. Optional. forudbetaltleje Forudbetalt leje for boligen. Dette skal være et heltal. Optional. type Angiver lejemålets boligtype, fx. "1 værelses lejlighed". Whitespace bliver preserved Man skal angive om det er en lejlighed, et rækkehus, en villa mv. husleje Hvad det koster at bo i boligen pr. måned ex. forbrug. BEMÆRK: Er huslejen ikke angivet på lejemålet, bliver annoncen ikke aktiv på Boligportal.dk Ved lejlighed skal angives antal værelser, fx 3-værelses lejlighed. Dette skal være et heltal. kvm Angiver m2 for boligen. Dette skal være et heltal. moebleret overtagelsesdato Angiver om boligen er møbleret 1 = Ja 2 = Nej Unix timestamp for hvornår boligen kan overtages. Timestamp angives i sekunder siden 1/1-1970 kl. 00:00:00. Angives som specifik dato eller Snarest. Angiv en specifik dato, der kun ændres, hvis Kan kun have en af de nævnte værdier: 1 eller 2. Skal være et unix timestamp (et heltal). Angiv en specifik dato eller angiv værdien 0 for snarest. Hvis overtagelsesdatoen er overskredet ved annonceindrykning, vil overtagelsestidspunktet figurere 3

overtagelsestidspunktet ændres. som snarest på Boligportal.dk adresse Hvis lejemålet er til overtagelse allerede fra annonceringstidspunktet angiv da værdien 0 for snarest. Dette element beskriver boligens adresse Alle attributter på nær etage er optional. Har 4 attributter: doer, etage, side, bogstav samt 3 elementer: postnummer, vejnavn og husnummer. Etage SKAL angives på lejligheder. doer Dørnummer Skal være et heltal (1,2 mv.) etage Etagenummer. KL, ST eller et heltal SKAL angives på lejligheder side Format MF, TV, TH Optional. Skal have en af de nævnte værdier til venstre. bogstav Evt. bogstav tilhørende adressen. A-Z postnummer Boligens postnummer Dette er et heltal. vejnavn Boligens vejnavn Dette er en string, sørg for at dette er et gyldigt vejnavn i forhold til krak (denne preserverer whitespace). husnummer Husnummeret. Heltal. lejeperiode Angiver den periode boligen er til leje i 1 = 2-12 måneder 2 = 1-2 år 3 = ubegrænset 4 =2 år+ Kan kun antage de 4 værdier angivet til venstre: 1,2,3,4. 4

overskrift Overskrift til annoncen String, preserverer whitespace. Må højst være af længde 30. tekst tekstuk kontakt Email telefon1, telefon2, mobiltelefon Teksten til annoncen. BEMÆRK: Annonceteksten skal være på minimum 100 tegn. Mangler annonceteksten bliver annoncen ikke aktiv på Boligportal.dk. Teksten til annoncen på engelsk. BEMÆRK: Annonceteksten skal være på minimum 100 tegn. Dette element indeholder kontaktinformation E-mailadresse på udlejer til Boligportal.dk s system. Denne bruges dels til boligsøgendes henvendelser og dels som kontakt for Boligportal.dk s medarbejdere. Telefonnummer, de boligsøgende kan kontakte udlejer på. String, preserverer whitespace. String, preserverer whitespace. Feltet er ikke obligatorisk Skal indeholde minimum ét af følgende underelementer: e- mailadresse OG/ELLER telefon1, telefon2 eller mobiltelefon. Hvis ikke angivet kan annoncen ikke importeres. Den anvendte e-mailadresse eller det anvendte telefonnummer skal være Boligportal.dk bekendt og forefindes i Boligportal.dk s system ellers kan annoncen ikke importeres. Preserverer ikke whitespace Der skal mindst være 8 cifre. billeder Samling af billeder. Dette er valgfrit, men hvis den er til stede skal den mindst indeholde 1 billede element og max 16. 5

billede Indeholder information om et enkelt billede Skal indeholde timestamp og url. Billedformatet skal være én af følgende typer: jpg jpeg bmp gif tif tiff png url url til billedet String, preserverer ikke whitespace timestamp aabenthusarrangementer arrangement dato Unix timestamp der fortæller hvornår billedet sidst er blevet ændret. Dette element indeholder en eller flere arrangement-elementer. Elementet beskriver en samling af åbent hus arrangementer. Elementet er valgfrit. Dette underelement beskriver hvornår et åbent hus arrangement finder sted. Elementet indeholder således et datoelement og to tidspunktselementer, hhv. starttid og sluttid, samt evt. alternativ adresse = fremvisningsadresse Dette element beskriver den dag arrangementet finder sted. Dette er et heltal. Tidspunktet skal kun ændres, hvis der er foretaget en ændring af billedet. Hvis angivet skal dette element mindst have et arrangement. Dette element skal have de 3 elementer angivet. Det skal indeholde tekst på formen: YYYY-MM-DD. YYYY er et årstal, MM er en måned angivet med 2 digits og ligeledes med DD. 6

starttid sluttid adresse Dette element beskriver hvornår arrangementet starter på den angivne dato. Dette element beskriver hvornår arrangementet slutter på den angivne dato. Dette element beskriver fremvisningsadressen. Hvis ikke denne er angivet benyttes lejemålets adresse. Dette element har formen: HH:mm:ss, hvor HH er 2 digit timer, mm minutter og ss sekunder. Præcis samme restriktion som starttid. Der gælder det samme for dette element som for lejemålets adresse-element. Definition af XML fil - Eksempel Eksempel xml-fil kan hentes på: http://www.boligportal.dk/storudlejer_xml_eksempel.xml XSD skemaet kan findes på: http://www.boligportal.dk/boligportal.xsd Validering af XML-fil For at teste XML-filens gyldighed kan I benytte følgende link: http://www.boligportal.dk/xml_test.php Spørgsmål Opklarende spørgsmål i forbindelse med XML-filen kan rettes til Jane Ernst Nielsen på 70 20 80 82 eller jane@boligportal.dk Flere brugerprofiler på Boligportal.dk Hvis I har flere brugerprofiler på Boligportal.dk og ønsker, at de forskellige annoncer fortsat skal ligge på de respektive profiler, skal Boligportal.dk på hvert enkelt lejemål kunne identificere hvilken brugerprofil lejemålet skal ind på. Dette gøres via e-mailadressen, der derfor skal anføres på hvert enkelt lejemål i xmlfilen. På denne måde kan Boligportal.dk koble lejemålet til den rigtige brugerprofil. 7

Ved nye medarbejdere eller ændring af en e-mailadresse er det vigtigt at informere Boligportal.dk, således at en ny brugerprofil kan oprettes eller ændringer på eksisterende profiler foretages. Lejemål i XML-filen med en e-mailadresse, der endnu ikke er tilknyttet en brugerprofil på Boligportal.dk, vil som udgangspunkt blive tilknyttet en af de allerede eksisterende profiler, indtil en ny profil er oprettet. Vigtig at vide om annonceringen på Boligportal.dk Udlejet, reserveret og genindrykning Lejemål, der er udlejet eller reserveret skal ikke med ved første kørsel. Når et lejemål er udlejet, skal dette ikke være i XML-filen til Boligportal.dk. Lejemålets manglede tilstedeværelse i XML-filen medfører, at det også bliver markeret udlejet på Boligportal.dk. Når et lejemål bliver reserveret, får det samme status på Boligportal.dk, hvis kravene hertil i henhold til kravspecifikationen er overholdt (se kravspecifikationen ovenfor). En reservering af lejemål varer 7 dage på Boligportal.dk. Herefter bliver lejemålet automatisk markeret udlejet uanset om lejemålet stadig kun har status som reserveret hos storudlejeren. Annoncer, der er markeret udlejet på Boligportal.dk, men som fortsat har status som reserveret hos storudlejeren, bliver ikke importeret. Ændres status på et reserveret lejemål til ikke-reserveret, ændres det ligeledes på Boligportal.dk, hvis kravene hertil er overholdt, jf. ovenstående kravspecifikation. En annonce for et ledigt lejemål løber i 31 dage, hvorefter den kan fornys til endnu en 31 dages periode, hvis lejemålet stadig er ledigt. Dette sker helt automatisk, når annoncerne indrykkes via XML. Så længe et lejemål står som ledigt hos storudlejeren, er det aktivt på Boligportal.dk. Krav til overskrift og annoncetekst Alle annoncer skal indeholde en overskrift og en annoncetekst. Annonceteksten skal være på minimum 100 tegn og indeholde en beskrivelse af lejemålet. Mangler annonceteksten, bliver annoncen ikke aktiv på Boligportal.dk. Huslejen skal angives ex. forbrug. Mangler huslejen, bliver annoncen ikke aktiv på Boligportal.dk. Lejemålets fulde adresse må ikke fremgå af overskrift eller annoncetekst. Henvisninger til hjemmesider, firmanavn, telefonnumre eller e-mailadresser må ikke fremgå af overskrift og annoncetekst. Lejemål skal kunne lejes for en periode på minimum 1 måned. Lejemål der ikke kan lejes for minimum denne periode samt lejemål, der kun kan lejes på dags- og ugebasis kan ikke annonceres. Erhvervslejemål kan ikke annonceres. Overtagelse af et lejemål må ikke være betinget af levering af ydelser eller varekøb, dog med undtagelse af viceværtsfunktion eller noget, der efter Boligportal.dk s mening kan sidestilles hermed. Lejemål skal være klar til indflytning på den angivne overtagelsesdato / snarest. Hermed forstås ikke at lejemålet er nymalet/nyistandsat, men derimod at lejemålets basale installationer (el, vand og varme) er i drift samt at evt. renovering er afsluttet inden indflytning. 8

Her beskrives de enkelte elementer og attributter i nærmere detaljer. Brug nedenstående til at få en uddybende beskrivelse af kravspecifikationen ovenfor. Tekst og tegnsætning XML skal encodes som ISO-8859-1. annoncer "annoncer" elementet har ingen attributter. "annoncer" elementet indeholder, som navnet angiver, en liste af annoncer. Et "annoncer" element har kun "annonce" elementer som børn og der skal mindst være et "annonce" element, som vist i eksemplet nedenfor: annonce et "annonce" element har 2 attributter, "journalnummer" og "ver" hvoraf journalnummer er valgfri. Journalnummer er journalnummeret i jeres eget system, dette må kun være 13 tegn langt. "ver" er pt. 1.2. Denne attribut angiver hvilken version af import scriptet Boligportal.dk skal udføre. Tidligere versioner er 1.0 og 1.1. "annonce -elementet skal yderligere indeholde følgende elementer: storudlejerid, sidstrettetdato, bolig, lejeperiode, overskrift, tekst og kontakt. Disse elementer bliver nærmere forklaret nedenfor. Desuden kan "annonce" elementet indeholde "billeder" og "aabenthusarrangementer", som også bliver forklaret i det følgende. [... ] i figuren betyder elementet er valgfrit og [] skal ikke skrives i xml'en. 9

Bemærk, at hvis der ikke er et "billeder"-element på en annonce udelukker det ikke "billeder" på en anden annonce. Det samme gælder for "aabenthusarrangementer". storudlejerid Dette er et unikt id, der identificerer det enkelte lejemål. Det kan både være tal og bogstaver, men det skal være unikt. sidstrettetdato Dette angiver tidspunktet for, hvornår annoncen sidst er blevet rettet. Hvis datoen er større end sidste gang Boligportal.dk modtog denne annonce, bliver informationerne opdateret hos Boligportal.dk. "sidstrettetdato" indeholder et timestamp givet i antal sekunder siden 1/1 1970 kl. 00:00:00 (unix timestamp). Her er et eksempel på 27/9-2010 kl. 20:23:00. De fleste web-sprog har en indbygget funktion til dette. I php er det time(). bolig Dette element indeholder diverse informationer om boligen. "bolig" er et element som har 5 attributter: accontoforbrug, depositum, forudbetaltleje, indskud og reserveret. "accontoforbrug", "depositum", "forudbetaltleje" og indskud er heltal som angiver det navnet siger. "reserveret" er en "ja/nej"-type hvor der angives "1" for reserveret ja og "2" for reserveret nej. Desuden indeholder "bolig"-elementet følgende elementer: type, husleje, kvm, overtagelsesdato, moebleret, adresse, husdyr, delevenlig. Nedenfor gennemgås disse felter. Bemærk at nogle af disse elementer er valgfri. [] har samme betydning som tidligere. type Indholdet af dette element er blot en streng. Strengen skal beskrive hvilken slags lejemål der er tale om, eksempelvis "1-værelses lejlighed". Hvis lejemålet er en lejlighed kræves information om antallet af værelser (ex."1-værelses..."). Ellers kræves information om hvorvidt det er en villa, et rækkehus eller lign. 10

husleje Dette angiver huslejen. Vi restringerer til heltal, dvs. husleje pr. måned angives i kroner. kvm 2 Dette er arealet af lejemålet og angives i kvadratmeter ( m ). Vi restringerer til heltal. overtagelsesdato Dette er et timestamp, som angiver, hvornår boligen kan overtages. Timestamp angives i sekunder siden 1/1-1970 kl. 00:00:00. Angiv en specifik dato eller værdien 0 for Snarest. moebleret Dette er et "ja/nej"-felt, der fortæller, hvorvidt boligen er møbleret ved at sige "1" for møbleret og "2" for ikke møbleret. = (boligen er møbleret). adresse Dette element giver informationer om lejemålets adresse. Der er 4 attributter tilknyttet dette element: doer, etage, side og bogstav. Disse attributter skal bruges til at uddybe adressen på boligen. "doer" er en streng af tal mellem 0 og 9, eller en tom streng. Etage angiver ved lejligheder hvilken etage lejemålet ligger på. "side" angiver hvilken side på etagen lejligheden er beliggende. Mulighederne for side er: "TH","MF","TV","th","mf","tv". Bogstav er et bogstav til at uddybe lejlighedens adresse, dette skal være et bogstav i A-Z eller a-z. Yderligere har adresse tre elementer: postnummer, vejnavn og husnummer som alle er obligatoriske. 11

postnummer Dette skal være et postnummer, og det bliver verificeret, om det er gyldigt, når boligen importeres. vejnavn En almindelig streng. Vejnavnet skal være gyldigt i forhold til Krak. husnummer Dette er et heltal, der fortæller lejemålets nummer på vejnavnet. husdyr Dette element er obligatorisk. Det er et "ja/nej"-element hvor "1" betyder ja og "2" betyder nej. delevenlig Dette element er obligatorisk. Det er et "ja/nej"-element hvor "1" betyder ja og "2" betyder nej. lejeperiode Dette beskriver længden på perioden som lejligheden kan lejes i. Værdierne fyldes efter nedenstående skema: 1 2-12 måneder 2 1-2 år. 3 Ubegrænset. 4 2 år+ 12

(ubegrænset lejeperiode). overskrift Overskriften til annoncen på lejemålet, dette er en streng. Overskriften må ikke være længere end 30 tegn inklusiv whitespace. Er obligatorisk. tekst Dette er en tekst til annoncen som beskriver lejligheden. Den er obligatorisk. Minimum 100 tegn. tekstuk Præcis det samme som "tekst" undtagen denne tekst skal være på engelsk. Dette element er valgfrit. kontakt Dette element beskriver kontaktoplysninger til udlejer for de boligsøgende. Elementet indeholder 4 yderligere elementer: email, telefon1, telefon2 og mobiltelefon. Elementet skal indeholde enten e-mailadresse og/eller mindst ét telefonnummer (elementerne e-mail, telefon1, telefon2, mobiltelefon). Ellers kan annoncen ikke importeres. Den anvendte e-mailadresse eller det anvendte telefonnummer skal være Boligportal.dk bekendt og forefindes i Boligportal.dk s system ellers kan annoncen ikke importeres. [] afgrænser valgfri elementer og disse tegn skal ikke skrives ind i den endelige xml). email Dette er en streng som skal være en e-mailadresse. 13

telefon1, telefon2, mobiltelefon Dette er alle samme type element. Der skal være mindst 8 cifre, evt. mere hvis der er landekode med (004512341234). billeder Dette element indeholder en liste af billed-elementer, som hver især beskriver et billede. billede Dette element beskriver et billede igennem yderligere to elementer: url og timestamp. url Dette beskriver placeringen af billedet i form af en web-adresse (URL). Ex, timestamp Dette element fortæller, hvornår billedet sidste gang blev ændret. Hvis det er nyere end sidste gang det pågældende billede blev hentet, hentes billedet på ny. For at undgå unødige opdateringer skal der kun sendes et nyt timestamp, såfremt der er foretaget ændringer af billedet. timestamp angives igen i sekunder siden 1/1 1970 kl. 00:00:00. Ex, 14

aabenthusarrangementer Dette element indeholder et eller flere arrangementelementer. Elementet beskriver en samling af åbent hus arrangementer. Elementet er valgfrit. Hvis angivet, skal dette element indeholde mindst et arrangement. arrangement Dette element beskriver hvornår et åbent hus arrangement finder sted. Elementet indeholder således et datoelement og to tidspunktselementer, hhv. starttid og sluttid. Dette felt skal have de 3 elementer angivet. Adresse elementet er valgfrit: Hvis det ikke er sat, anvendes lejemålets adresse som mødested for arrangementet, ellers anvendes indholdet af adresse-elementet. Adresse-elementet er beskrevet tidligere i dette dokument, der gælder de samme regler som for det. ([...] angiver igen at elementet er valgfrit og skal ikke skrives) dato Dette element beskriver den dag arrangementet finder sted. Det skal indeholde tekst på formen: YYYY- MM-DD. hvor YYYY er et årstal, MM er en måned angivet med 2 digits og ligeledes med DD. starttid og sluttid Disse elementer beskriver, hvornår arrangementet starter hhv. slutter på den angivne dato. Disse elementer har formen: HH:mm:ss, hvor HH er 2 digit timer, mm minutter og ss sekunder. 15