Format d'annonces

Le fichier XML contient une ou plusieurs agences immobilières (ou constructeur, promoteur, ...).

Il doit valider le schéma suivant : gedeon.xsd.
Nous fournissons également un validateur en ligne.

Structure

La structure globale est simple : des agences (<agencies>) contenant des annonces (<ads>). 


<?xml version="1.0" encoding="utf-8"?>

<agencies xmlns="http://www.gedeon.im/xmlns/agencies/v1" version="1.0" generator="mon-logiciel/3.1">

	<!-- Première agence -->
	<agency id="...">

		<!-- Coordonnées de l'agence -->
		<contact>
			...
		</contact>

		<!-- Annonces (biens immobiliers) de l'agence -->
		<ads>

			<!-- Première annonce -->
			<ad reference="...">
				...
			</ad>

			<!-- Deuxième annonce -->
			<ad reference="...">
				...
			</ad>

		</ads>

	</agency>

</agencies>
Note : dans ce document, tous les champs sont obligatoires, sauf indication contraire.

Agences

La balise <agencies> doit faire référence au namespace suivant : http://www.gedeon.im/xmlns/agencies/v1.

Elle doit contenir les attributs suivants :

Suivent ensuite la liste des agences, via les balises <agency>.

Si vous n'avez qu'une agence, alors c'est simple, une seule balise <agency> devra être présente dans le fichier.

Si vous avez plusieurs agences, vous pouvez au choix :

  • Utiliser un fichier XML contenant autant de balises <agency> qu'il n'y a d'agences,
  • ou utiliser un fichier XML par agence avec une seule balise <agency>.

Agence

La balise <agency> doit contenir l'attribut suivant : Doivent ensuite apparaîtrent les deux éléments suivants, dans l'ordre :

Coordonnées de l'agence

La balise <contact> doit contenir les élements suivants :

<contact>

	<name>Mon Agence Immobilière</name>

	<localization>
		<address>18 Rue Jean Jaurès</address>
		<postCode>01234</postCode>
		<city>Saint Paul</city>
		<country>FR</country>
	</localization>

	<fax>0123456789</fax>
	<phone>0123456789</phone>

	<emails>
		<email>mon.agence@example.com</email>
		<email>mon.agence@example.com</email>
	</emails>

	<web>https://www.monagence.example.com</web>
	<logo>https://www.monagence.example.com/logo-large.png</logo>

</contact>

Les noms sont assez explicites, quelques remarques cependant :

Agents

Vous avez des informations concernant les agents, qu'ils soient négociateurs ou agents commerciaux (mandataires) ? Vous pouvez facilement les ajouter en utilisant le format suivant :

	<subagencies [...]>
		<agency [...]>
			<contact>
				<!-- // -->
			</contact>

			<agents>
				<agent type="negociator" email="j.dupond@gmail.com">
					<civility>M</civility>
					<firstname>Jean</firstname>
					<name>Dupond</name>
					<phone>0605040302</phone>
				</agent>
			</agents>
		</agency>
	</subagencies>
Si vous ne pouvez pas définir séparément les champs firstname et name, vous devez seulement remplir le champ name avec le nom complet.

Vous avez encore plus d'informations à fournir ? Ce n'est pas un problème. Voici la liste de tous les champs supportés :

Annonces

Voici le cœur du sujet, les biens immobiliers.

Les annonces sont listées dans la balise <ads>, une <ad> à la suite des autres : 

<ads>
	<ad reference="A1">
		‥
	</ad>

	<ad reference="A2">
		‥
	</ad>

	‥

</ads>

Une annonce <ad> doit posséder l'attribut suivant, non vide :

Il est important que cette reference unique reste la même, pour une annonce, dans le temps.
C'est elle qui permet le relevé de statistiques, le suivi des demandes, et la multi-diffusion correcte.

Voici un aperçu d'une annnonce :

<ad reference="A1">

	<transaction>S</transaction>

	<type sub="Studio">flat</type>

	<localization>
		<address>Rue Centrale</address>
		<postCode>01234</postCode>
		<city>Saint-Paul</city>
		<country>FR</country>
	</localization>

	<price currency="euro">250000</price>

	<rooms>20</rooms>

	<surface>100</surface>

	<mandate>
		<type>simple</type>
		<number>1234</number>
	</mandate>

	<texts>
		<text target="internet" lang="fr">Description du bien immobilier</text>
		<text target="press" lang="fr">Description du bien pour la presse</text>
	</texts>

	<titles>
		<title lang="fr">Titre de l'annonce</title>
	</titles>

	<contact>
		<phone>0123456789</phone>
		<email>agent1@example.com</email>
	</contact>

	<medias>

		<media type="photo">
			<url>https://example.com/photo-A1-1.jpg</url>
		</media>

		<media type="photo">
			<url>https://example.com/photo-A1-2.jpg</url>
		</media>

		<media type="virtualvisit">
			<url>https://example.org/visite/A1.html</url>
		</media>

		<media type="youtube">
			<url>https://www.youtube.com/watch?v=example</url>
		</media>

	</medias>

	<extras>
		‥
	</extras>

	<diffusions>
		<diffusion>lesiteimmo</diffusion>
		<diffusion>seloger</diffusion>
	</diffusions>

</ad>

Ce sont les seuls champs obligatoires pour permettre à votre annonce d'être valide ! Bien sûr il sera possible de la compléter de façon exhaustive, ce que nous verrons plus loin.

Contenu d'une annonce

Voici la description des balises :

Voilà ! L'annonce est maintenant remplie à minima et peut être validée.

Maintenant, afin de lui donner le plus d'informations complémentaires possibles, les champs appelés <extras> vous donnent la possibilité d'enrichir l'annonce.

Il est vivement conseillé, également, de valider votre fichier : Validation XML

Champs Extras

Les champs extras sont à renseigner dans la balise <extras>, un <extra> à la suite des autres : 

‥
<ads>
	<ad reference="A1">
		‥
		<extras>
			<extra key="charges">75</extra>
			<extra key="cuisine">équipée</extra>
			‥
		</extras>
	</ad>
	<ad>
		‥
	</ad>
</ads>
‥

Chaque élément <extra> doit un attribut key (clé) et une valeur.

La clé key ne doit contenir que les caractère a à z et l'underscore _.

Les champs extras ont pour concept une extensibilité large des informations complémentaires d'une annonce.

Une liste officielle vous est donnée ci-dessous, n'hésitez pas à nous contacter pour l'ajout de données qui vous importent !

Types

Les champs extras sont typés.

Seuls les valeurs non vides sont prises en compte. Ainsi les valeurs false, 0, 0.00, etc. sont ignorées.

Type Description
bool Booléan : true ou false
Les champs à false sont en fait ignorés.
text Texte libre (court)
int Nombre entier. Ex: 132
float Nombre décimal. Ex: 132.45
money Nombre décimal, valeur en euros. Ex: 132.45
Un suffixe € sera rajouté lors de l'affichage
surface Nombre décimal, valeur en m². Ex: 132.45
Un suffixe m² sera rajouté lors de l'affichage
date Date, format yyyy-mm-dd
year Année, format yyyy

Énumérations

Certains champs extras ont une liste de valeurs possibles.

Dans ce cas, il faut si possible s'y conformer ou nous contacter si aucune de ces valeurs ne semble correspondre à vos besoins.

S'il est possible de renseigner plusieurs valeurs, il faut alors les séparer par les caractères ", " (virgule, espace).

Liste des champs

Programmes Neufs (lots)

Si l'annonce <ad> est un Programme Neuf, donc si et seulement si elle a comme valeur de <transaction> P, alors vous devriez spécifier les lots du programme.

Exemple :

      <ad reference="A1">

         <!-- Transaction "P" pour "Programme Neuf" -->
         <transaction>P</transaction>

         <!-- Type général du programme, s'il n'a pas de lot -->
         <type sub="Studio">flat</type>

         <localization>
            <address>Rue Centrale</address>
            <postCode>01234</postCode>
            <city>Saint-Paul</city>
            <country>FR</country>
         </localization>

         <!-- Prix minimum du programme, s'il n'a pas de lot -->
         <price currency="euro">239000</price>

         <!-- Nb. pièces minimum du programme, s'il n'a pas de lot -->
         <rooms>2</rooms>

         <!-- surface minimum du programme, s'il n'a pas de lot -->
         <surface>60</surface>

         <mandate>
            <type>simple</type>
            <number>1234</number>
         </mandate>

         <texts>
            <text target="internet" lang="fr">Description du programme</text>
            <text target="press" lang="fr">Description du programme pour la presse</text>
         </texts>

         <titles>
            <title lang="fr">Titre/accroche du programme</title>
         </titles>

         <contact>
            <phone>0123456789</phone>
            <email>contact@example.com</email>
         </contact>

         <medias>
            <media type="photo">
               <url>http://example.com/photo-A1-1.jpg</url>
            </media>
         </medias>

         <!-- Champs extras dédiés au neuf -->
         <extras>
            <extra key="nom_programme">Les Nouvelles Demeures</extra>
            <extra key="livraison">1er trimestre 2025</extra>
            <extra key="etat_avancement">Travaux en cours</extra>
            <extra key="certifications">BBC, NF Logement</extra>
            <extra key="mesures_fiscales">Pinel, Duflot, TVA réduite</extra>
         </extras>

         <!-- Lots -->
         <lots>

            <lot reference="1">
               <type>flat</type>
               <price currency="euro">239000</price>
               <rooms>2</rooms>
               <floor>2</floor>
               <surface>60</surface>
            </lot>

            <lot reference="2">
               <type>flat</type>
               <price currency="euro">277000</price>
               <rooms>3</rooms>
               <floor>rdc</floor>
               <surface>69</surface>

               <garden>true</garden>
               <parking>true</parking>
            </lot>

            <lot reference="3">
               <type>house</type>
               <price currency="euro">370000</price>
               <rooms>4</rooms>
               <floor>1</floor>
               <surface>84</surface>

               <balcony>true</balcony>
            </lot>

            <lot reference="4">
               <type>house</type>
               <price currency="euro">369000</price>
               <rooms>4</rooms>
               <floor>4</floor>
               <surface>84</surface>

               <balcony>true</balcony>
               <patio>true</patio>
            </lot>

         </lots>

      </ad>

Les informations de prix, surface et pièces de l'annonces seront déduites des lots, avec leur valeur minimum ("prix à partir de", "surface minimum", etc.).

Les informations de prix, surface et pièces contenues dans <ad> sont alors considérées comme secondaires, et ne sont utilisées que :

  • s'il n'y a pas de lot (programme en avant première, ou information indisponible)
  • ou si les lots manquent d'information.

Chaque <lot> peut avoir un attribut reference.

Voici la description des balises contenues dans <lot> :

Viagers

Un viager est quasiment identique à une vente normale, si ce n'est que le prix indique le bouquet, et qu'il est possible de spécifier la rente mensuelle ainsi que des informations complémentaires.

Si l'annonce <ad> est un Viager, donc si et seulement si elle a comme valeur de <transaction> L, alors voici les spécificités :

Loi ALUR (et décret 2017)

Afin de respecter la loi ALUR et son décret de janvier 2017, voici quelques informations complémentaires :

Pour les vente

Concernant les ventes (<transaction>S</transaction>) :

Pour les locations

Concernant les locations (<transaction>R</transaction>) :